v9.0.0 · AGPL-3.0-or-later

Research before you build.
Understand before you change.

Genesis researches across the software ecosystem before you start a new project, using the sources available where it runs, and diagnoses an existing codebase before you touch it. Every recommendation cites evidence. Nothing acts without your approval.

Get started View on GitHub

pip install genesis-architect

Two entry points

New project

genesis init "a CLI that syncs notes"

Finds comparable repositories, mines their issues for pitfalls, lets you choose an architecture, then scaffolds it.

New projects

Existing project

genesis recover .

Reads your code without executing it. Reports import cycles, anti-patterns and a score, then proposes fixes for approval.

Existing projects

Run it yourself

The fastest check needs no API key and changes nothing:

pip install genesis-architect
cd your-project
genesis recover .

recover does not edit your source; it writes reports to .genesis/ and FRAGILITY_MAP.md. init needs an LLM key and sends your description to GitHub and to that LLM. See Configuration.

Genesis audits itself

These figures are generated from the code by a script and re-checked in CI. They are not typed by hand. Source: data/public-product-facts.json.

Architecture score: 93/100
Import cycles: 0
Critical anti-patterns: 0
Tests collected: 2,877
Engines: 19
Approval gates: 14
Mapped capabilities: 50
Commands: 22

Evidence you can inspect

Genesis writes an evidence pack: what it looked at, what it found, and how thin or strong the evidence is. When research is weak it says THIN instead of hiding it. The repository keeps a real pack for Genesis itself: ARCHITECTURE_EVIDENCE.md.

How evidence works

From evidence to verified change

EvidenceSourced findings from public repositories or from your own code.
AnalysisImport graph, anti-patterns, architecture score.
DecisionOptions with trade-offs, ranked against the evidence.
Approval14 gates. Nothing acts without your sign-off.
ActionScaffold or fix, only what was approved.
VerificationRe-run the analysis and compare.

Capabilities by goal

Start a project
genesis init
Research, compare architectures, scaffold with tests and CI.
Read more about Start a project
Recover a codebase
genesis recover .
Diagnose cycles, anti-patterns and drift. Your source is not edited.
Read more about Recover a codebase
Harden
genesis harden
Find security and quality gaps against a checklist.
Read more about Harden
Check dependencies
genesis deps
Inspect declared dependencies for risk.
Read more about Check dependencies
Ask your agent
MCP tools
Four read-only analysis tools for any MCP client.
Read more about Ask your agent

These are the common starting points. Genesis maps 50 capabilities in 9 families, each with its maturity, what it writes and what it needs:the full capability catalog. Engines and capabilities are counted differently, and the catalog explains how.

Safety

Analyzed code is never executed.
Mutating commands are dry-run by default and need an explicit apply.
Secrets found in a scan are redacted in every report.
Telemetry is off unless you opt in.

Security · Approval model

Works with your agent

Install as a skill for Claude Code, Cursor or Codex. As a skill, research can also draw on the web and MCP tools your agent has. Or connect any MCP client to the four read-only analysis tools, which do not use the network.

Agent integrations · MCP

Install

pip install genesis-architect
genesis doctor

Python 3.11 or newer.

Documentation

When not to use it

Throwaway scripts. The research costs more than it saves.
Non-Python code you want analyzed. Analysis is Python-first.
When you need a verdict rather than a signal. The score points you at findings; read them.

All limitations

Try it on a real project

Get started Star or read the source

Research before you build.Understand before you change.