AnaxiGraph

Keep AI-accelerated codebases coherent as they grow.
See the system behind the source, control entropy, and give coding agents grounded context.

Get started · Agent plugin · Docker · Advanced · Contribute

AI makes it easy to add code faster than a team can understand the architecture absorbing it. Hidden coupling, duplicated responsibilities, inconsistent abstractions, and one-off agent changes quietly become spaghetti code.

AnaxiGraph turns a repository and its Git history into a living architecture record. It helps people and coding agents see how the system fits together, decide what deserves attention, plan a bounded change, and verify what the change actually did. Its job is not to hand out a magic architecture score; it makes trade-offs visible, evidence-backed, and reviewable before entropy hardens into the design.

	What it gives you
🧹 Entropy control	Detect growing modules, cycles, boundary erosion, hotspots, and repeated responsibilities early.
🕸️ System visibility	Move from a bird's-eye architecture map to the dependencies, history, and evidence of one module.
🕰️ Repository biography	Replay representative real Git commits and inspect how the architecture grew.
🧭 Auditability	Keep deterministic facts, model interpretations, recommendations, and human decisions distinct.
🏛️ Design guidance	Ground patterns, refactors, placement, and consolidation advice in the codebase that actually exists.
🤖 Safer agent work	Give a coding agent the smallest useful scope, blast radius, active risks, and verification plan.

🚀 Start in four steps

You need Git, Python 3.11+, and uv.

1. Run one command in the repository

cd /path/to/your/repository
uvx anaxigraph up . --open --semantic agent --connect codex

Use --connect claude for Claude Code. Omit --semantic agent --connect codex when you only want the deterministic map.

This command creates or loads repository policy, stores AnaxiIndex outside the target, completes the current scan, starts the loopback dashboard and AnaxiMCP, and builds representative Git history in the background. Stop it with Ctrl-C; restart with the same command.

2. Open the dashboard

Visit http://127.0.0.1:8765. Current architecture is ready before background history finishes.

3. Restart Codex in the repository

The explicit --connect codex option configures http://127.0.0.1:8765/mcp on the machine where Codex runs. Restart it after first-time setup:

cd /path/to/your/repository
codex

4. Ask it to build the semantic baseline

Use AnaxiGraph to build or resume the semantic baseline for this repository, using your own model context and tokens. Do not edit source while mapping it; continue until no work remains.

That is the key cost model: the connected coding agent does the reasoning with its own tokens. AnaxiGraph needs no model key in provider: agent mode. It leases bounded evidence one module or scope at a time, validates returned dossiers, records provenance, and resumes unfinished work in a later session. Unchanged fingerprints avoid rereading unchanged modules.

The complete onboarding guide explains the normal coding loop and setup diagnostics.

🐳 Durable Docker sidecar

If you prefer an isolated, persistent container beside the repository:

cd /path/to/your/repository
uvx anaxigraph init . --start --semantic agent --connect codex

The generated Compose service mounts source read-only, drops Linux capabilities, enables no-new-privileges, persists AnaxiIndex in a named volume, and publishes only to loopback by default. Use --connect claude for Claude Code. Preview the full repository and client change with --dry-run --json.

See Docker operation for manual Compose review, updates, watchers, and the experimental multi-repository registry.

🔌 Install the guided agent workflow

The shared plugin teaches Codex and Claude Code how to select the right indexed repository, build or resume semantic dossiers, inspect bounded scope and impact, hand off a planned finding, and verify a completed change.

Codex:

codex plugin marketplace add hcekne/anaxigraph && \
  codex plugin add anaxigraph@anaxigraph

Invoke $anaxigraph. Claude Code:

claude plugin marketplace add hcekne/anaxigraph && \
  claude plugin install anaxigraph@anaxigraph --scope user

Invoke /anaxigraph:anaxigraph. The plugin includes the default loopback MCP connection, so plugin users may omit --connect from the start command. See the agent plugin guide for the safety contract and custom endpoint behavior.

How it works

source + Git ── deterministic scan and hashes ──→ versioned AnaxiIndex
                                                       │ changed/stale work only
                                                       ▼
                                            semantic work queue
                                                       │
                                              connected coding agent
                                                       │ own model + tokens
                                                       ▼
                                       versioned, validated dossiers

Three named surfaces share one index:

• AnaxiGraph is the scanner, dashboard, and overall project.
• AnaxiIndex is the SQLite record of repositories, files, symbols, relationships, findings, history, and semantic dossiers.
• AnaxiMCP exposes bounded repository context and controlled index workflows to coding agents.

AnaxiGraph does not execute target code and does not edit repository source. A generated sidecar mounts the target read-only. The target needs only optional .anaxigraph.yml policy; analysis state stays external.

Facts are not opinions

AnaxiGraph deliberately separates:

1. deterministic facts—hashes, syntax, symbols, references, Git changes, complexity, imported coverage, and analyzer provenance;
2. interpretations—purpose, responsibilities, architecture role, related behavior, and pattern opportunities, each with model/prompt/evidence/confidence provenance; and
3. recommendations—reviewable proposals with evidence, counter-evidence, cost, safety, and lifecycle state.

Relationship edges say whether they are resolved, ambiguous, unresolved, or external. Dynamic runtime wiring can still be invisible, so a missing edge is never presented as proof of dead code.

One index, several views

• Overview summarizes areas, evidence completeness, history, and immediate attention.
• Modules is a sortable/filterable ledger of purpose, placement, size, complexity, coupling, Git activity, coverage state, findings, and pattern review.
• Graph moves between architecture regions and module-level relationships.
• Architecture separates a bounded ranked attention queue from the complete diagnostics ledger.
• History replays representative first-parent commits from repository initialization to HEAD.
• Agents builds evidence-backed work scope and explains semantic progress.

🎯 Findings are a workflow, not a wall

The default attention queue shows at most 20 qualifying signals and excludes routine information-level long-function noise. The complete diagnostics ledger remains filterable and paginated; no evidence is deleted merely to quiet the UI.

Every finding explains its priority, evidence, likely false-positive conditions, affected areas, smallest next action, and verification rule. Plan agent work is the explicit approval boundary. Review, accept-risk, and dismiss actions record different human decisions; resolution and regression normally come from a later deterministic scan.

Current support boundary

The deepest deterministic analysis is currently Python-first. JavaScript and TypeScript use the built-in lexical analyzer; other recognized source and text formats have heuristic or inventory support. The roadmap deliberately does not call extension recognition “full language support.” Parser-backed JavaScript/TypeScript, Go, Rust, and Java are the next language-platform phase.

Linux x86-64 is release-gated. Linux ARM64, macOS, and WSL2 are best effort; Docker Desktop is the recommended macOS path. Native Windows is not supported—use WSL2. See the platform matrix.

The REST and MCP service currently has no authentication. Keep it bound to loopback or behind an SSH tunnel. Do not expose it as an untrusted or shared team service until the authenticated deployment phase lands.

Advanced operation

The advanced guide covers hosted OpenAI/Anthropic workers, local Codex/Claude/custom workers, semantic cost and privacy, SSH forwarding, custom ports/state, optional coverage imports, durable history controls, watchers, integrity diagnostics, upgrades, resets, lower-level CLI commands, and several repositories.

🛠️ Development

uv sync --extra dev
uv run pre-commit install --install-hooks
uv run python scripts/run_quality_gate.py --base origin/main

The product brief is repo_instructions.md, the consecutive roadmap is docs/feature-development-plan.md, and the release contract is docs/releasing.md. Contributions are welcome; see CONTRIBUTING.md.