AnaxiGraph

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

Get started · Docker guide · Contribute

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

AnaxiGraph creates an architectural feedback loop for that problem. It turns a repository and its Git history into a living, explorable system map, helping people and coding agents understand how the code fits together before they change it. The goal is not architecture-by-score; it is to make important trade-offs visible, evidence-backed, and reviewable while there is still time to act.

	What you get
🧹 Control entropy	Catch growing modules, dependency cycles, boundary erosion, and repeated responsibilities before they harden into spaghetti code.
🏛️ Build for change	Review whether boundaries, patterns, and abstraction candidates fit the codebase you have and the system you are building toward.
🕸️ Graph understanding	Move from a bird's-eye architecture map to the dependencies, history, and evidence behind an individual module.
🕰️ Repository biography	Replay how the system grew across real Git history instead of seeing only today's tree.
🧭 Auditability	Trace findings and interpretations back to files, relationships, commits, and snapshots.
🤖 Safer AI coding	Give Codex a small, evidence-backed work envelope so agent changes respect the wider architecture.

Under the hood, AnaxiGraph is a standalone temporal architecture observatory. It scans source and Git history without modifying the target, persists a versioned dependency graph, evaluates architecture signals, renders an interactive dashboard, and serves bounded context and impact analysis to coding agents.

The dashboard includes a filterable Modules ledger for purpose, architecture placement, size, complexity, coupling, Git activity, imported coverage, findings, and review attention. Graph regions scale with their module populations so dense areas receive proportionally more space.

Three surfaces, one index

• 🔭 AnaxiGraph is the dashboard, analysis engine, and overall project.
• 🗂️ AnaxiIndex is the persistent SQLite knowledge store for repositories, modules, symbols, relationships, intent, findings, and history.
• 🔌 AnaxiMCP exposes that knowledge to Codex and other coding agents over MCP.

The analysis engine is Python-first and supports mixed repositories containing Python, TypeScript, JavaScript, JSX, CSS, configuration, and documentation.

Deterministic facts + real module understanding

AnaxiGraph has two separate AI-facing paths that reinforce one another:

source + Git ── deterministic scan/hashes ──→ versioned graph
                                                   │ changed modules only
                                                   ▼
                                  semantic work queue in AnaxiIndex
                                      │                        │
                            connected coding agent      optional model worker
                                      └──────────┬─────────────┘
                                                 ▼
                                versioned semantic dossiers

The first opt-in semantic bootstrap reads every eligible first-party module and records its purpose, contracts, architecture role, related responsibilities, pattern opportunities, placement guidance, risks, and provenance. It then synthesizes subsystem and repository context. Later scans compare structural, interface, relationship, prompt, model, and intent fingerprints, so unchanged source is reused rather than paid for again. Parser facts and model interpretations remain separate throughout.

🚀 Get running in five minutes

AnaxiGraph normally runs as a Docker sidecar beside the repository you are coding in. From that repository, run these commands in a normal terminal:

cd /path/to/your/repository
uvx --from git+https://github.com/hcekne/anaxigraph anaxigraph init .
docker compose -f compose.anaxigraph.yml up -d

The initializer writes .anaxigraph.yml and compose.anaxigraph.yml without replacing existing files. The Compose service mounts the repository read-only, persists AnaxiIndex in a named volume, scans the current tree, and imports representative graph frames from the initial Git commit through HEAD.

Open http://127.0.0.1:8765 and follow the four-step dashboard tour.

🤖 Connect Codex

Run the following in a shell on the machine where Codex itself runs. It can be run from any directory:

codex mcp add anaxigraph --url http://127.0.0.1:8765/mcp
codex mcp list

By default, codex mcp add stores the connection in ~/.codex/config.toml. Future Codex CLI and IDE sessions on that same host can then use AnaxiMCP from any coding repository. Start a new Codex session in the project you want to edit:

cd /path/to/your/repository
codex

If you want the connection available only inside one trusted repository, add it to that repository's .codex/config.toml instead:

[mcp_servers.anaxigraph]
url = "http://127.0.0.1:8765/mcp"

Remote Linux server + local browser

When AnaxiGraph and Codex run on a remote Linux server while you view the dashboard from another computer, the Codex-to-AnaxiMCP route is direct:

Codex on server ── http://127.0.0.1:8765/mcp ──→ AnaxiMCP container
Local browser   ── SSH port forward ───────────→ dashboard on :8765

The SSH tunnel is only needed by the browser. Codex on the server does not go through your local computer or the tunnel; it reaches the published container port on its own host. A server session looks like this:

# Run on the Linux server where Codex runs
curl http://127.0.0.1:8765/healthz
codex mcp add anaxigraph --url http://127.0.0.1:8765/mcp
codex mcp list
cd /path/to/your/repository
codex

If Codex runs on your local computer instead, the forwarded URL works while the SSH tunnel is active. If Codex itself runs in another container on the same Docker network, use http://anaxigraph:8765/mcp instead of 127.0.0.1.

Other MCP clients use the same endpoint. See the complete onboarding guide for the human-to-agent workflow, optional coverage, history, custom ports, updates, and reset behavior, and the official Codex MCP documentation for Codex configuration details.

Build the semantic baseline with your coding agent (optional)

The recommended Docker path needs no LLM key inside AnaxiGraph. Enable agent-funded semantics in .anaxigraph.yml:

semantic:
  enabled: true
  provider: agent
  refresh: manual
  max_parallel_jobs: 1
  agent_lease_seconds: 1800

Refresh the scan or choose Prepare semantic work in the dashboard. Then ask the coding agent that is already connected to AnaxiMCP and running in the target repository:

Use AnaxiGraph to build or resume the semantic baseline for this repository. Call ANAXIGRAPH_SEMANTIC_SCHEMA once, then repeat ANAXIGRAPH_SEMANTIC_WORK, fetch every requested evidence page, analyze the module or scope using your own model context, and call ANAXIGRAPH_SEMANTIC_SUBMIT. Continue until WORK returns complete. Do not edit source while performing this mapping task.

AnaxiGraph chooses only stale work, supplies source plus deterministic graph/Git evidence, leases each job, validates the returned dossier, and writes it to AnaxiIndex. The coding agent supplies the reasoning and uses its own token allowance. The repository mount remains read-only, and the queue can resume in another agent session if the first session stops.

An in-container hosted worker remains available as an alternative for unattended schedules:

semantic:
  enabled: true
  provider: openai       # or anthropic
  model: your-model
  refresh: periodic

export OPENAI_API_KEY="..."       # use ANTHROPIC_API_KEY for provider: anthropic
docker compose -f compose.anaxigraph.yml --profile ai up -d
docker compose -f compose.anaxigraph.yml logs -f anaxigraph-semantic

For a local installation, provider: codex and provider: claude run those authenticated CLIs as workers. The semantic onboarding guide explains the agent-funded loop, hosted workers, privacy controls, incremental invalidation, and scheduling.

🔄 Keep it current

Follow startup or scanning with:

docker compose -f compose.anaxigraph.yml logs -f anaxigraph

To refresh automatically while you code, enable the optional watcher:

docker compose -f compose.anaxigraph.yml --profile watch up -d

🗺️ Shared multi-repository service

The repository also contains an operator setup for one dashboard across several allowlisted read-only mounts. This is useful for a team installation or for switching projects without running several ports:

git clone https://github.com/hcekne/anaxigraph.git
cd anaxigraph
cp .env.example .env
cp repositories.example.yml repositories.yml
# Edit the host mounts and registry, then:
docker compose up --build -d

The browser cannot ask the server to browse arbitrary host paths. See Docker operation and MaxOS integration.

💻 Local CLI

uv tool install -e .
anaxigraph init /path/to/repository --no-compose
anaxigraph scan /path/to/repository
anaxigraph serve --repository /path/to/repository --scan-on-start --open

AnaxiIndex is stored outside the target at ${XDG_STATE_HOME:-~/.local/state}/anaxigraph/anaxi-index.db. Override it with --db or ANAXIGRAPH_DB.

Useful commands:

anaxigraph update /path/to/repository
anaxigraph understand /path/to/repository
anaxigraph semantic-status /path/to/repository
anaxigraph history /path/to/repository --limit 64
anaxigraph review /path/to/repository
anaxigraph scope /path/to/repository --goal "Add saved prompts to Workbench"
anaxigraph impact /path/to/repository --target backend/app/services/chat.py
anaxigraph watch /path/to/repository
anaxigraph mcp --repository /path/to/repository --port 8765

The serve and mcp commands both expose the dashboard and JSON API at http://127.0.0.1:8765, with Streamable HTTP MCP at http://127.0.0.1:8765/mcp. See docs/maxos-agent.md for the ready-to-run MaxOS integration.

🧠 What is persisted

• repositories, commit/working-tree snapshots, artifacts, and artifact versions
• source symbols and deterministic import/call relationships with evidence
• raw and language-aware structural hashes for incremental scans
• declared and inferred architecture groups
• metrics, coverage measurements, Git change history, and temporal trends
• architecture findings with stable identity and lifecycle state
• durable intrinsic, contextual, subsystem, and repository dossiers with provider/model/prompt plus coding-agent executor provenance, resumable work state, fingerprints, token usage, and cost estimates

The target repository only needs an optional .anaxigraph.yml; analysis state remains external.

🛠️ Development

uv sync --extra dev
uv run pytest
uv run ruff check .

The product brief and requirement source is repo_instructions.md. Contributions are welcome; see CONTRIBUTING.md.