Genesis Architect

Evidence-first architecture for real software.

Research before you build. Understand before you change.

Documentation · Getting started · Architecture · Contributing

Genesis researches across the software ecosystem before you build, using the sources available in the current execution environment, then turns that evidence into architecture options you approve. It mines the failures that keep recurring in comparable projects and scaffolds with those mitigations already in place. For code that already exists, it builds the import graph, scores the architecture, and reports what is fragile before anyone changes it. Every recommendation carries its sources, and nothing acts without your approval.

The sources depend on how you run it. The standalone genesis init CLI researches GitHub repositories and their issues. When Genesis runs as an agent skill, its research workflow can combine GitHub with available web and MCP sources, community discussions, package registries, security data and relevant media. Genesis's own MCP server is separate: four read-only analysis tools that do not use the network. See Research and evidence.

pip install genesis-architect

recover needs no API key, never executes your code and does not edit your source files. It writes its own reports to .genesis/ and FRAGILITY_MAP.md in the project directory. init needs an LLM key and sends your description to GitHub and to that LLM (configuration).

A recorded, reproducible walkthrough of both flows is in demo/. The terminal output in it is captured from real runs, not written by hand.

Genesis is run against its own source in CI. These figures are rendered from the code, and CI fails if this table drifts from the facts file.

Generated for v9.0.0 from data/public-product-facts.json.

The first self-audit (v9.0.0) found four import cycles and seven critical anti-patterns in Genesis itself. The method and what was fixed are in docs/architecture/overview.md.

flowchart LR
    E[Evidence] --> A[Analysis] --> D[Decision] --> P[Approval] --> X[Action] --> V[Verification]
    V -.->|re-run| E

1. Evidence. Public repositories, issues and forks for a new project; your own import graph for an existing one.
2. Analysis. Dependency graph from the AST, anti-pattern rules, architecture score.
3. Decision. Options with trade-offs, ranked against the evidence. Weak evidence is reported as THIN.
4. Approval. Policy gates stop before any change. Mutating commands are dry-run by default.
5. Action. Only what you approved.
6. Verification. The analysis runs again and the result is compared.

Genesis groups what it can do by the question you are asking. Each family links to the complete table in the capability catalog, which is generated from the code and lists maturity, what each capability writes and what it needs.

Command reference: Commands.

Genesis ships as an agent skill for Claude Code, Cursor and Codex, and exposes four read-only MCP analysis tools that do not use the network. As a skill it may also use whatever external MCP and web tools your agent has for research; that is separate from the tools Genesis exposes. Setup: Agent integrations and MCP.

Skip it for throwaway scripts and anything you will delete next week. Analysis is Python-first. See Limitations.

The documentation site is built from site/. The former Pro package source is kept in genesis-architect-pro/. There is no paid tier.

git clone https://github.com/maioio/genesis-architect
cd genesis-architect
pip install -e ".[dev]"
pytest -q

See CONTRIBUTING.md and the Code of Conduct. Report vulnerabilities privately as described in SECURITY.md.

GNU AGPL-3.0-or-later. Copyright (C) 2026 Maio Eshet. Free to use, modify and redistribute, including commercially; if you modify it and offer it over a network, publish your changes under the same license. A commercial license for closed-source use is available from maio.eshet@gmail.com. Releases up to v5.4.1 were MIT.