Metadata-Version: 2.4
Name: anaxigraph
Version: 0.2.0
Summary: A temporal architecture and intelligence layer for software repositories
Author: AnaxiGraph contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/hcekne/anaxigraph
Project-URL: Repository, https://github.com/hcekne/anaxigraph
Keywords: architecture,static-analysis,knowledge-graph,mcp,repository-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: mcp<2,>=1.28
Requires-Dist: PyYAML<7,>=6
Requires-Dist: uvicorn<1,>=0.30
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: httpx<1,>=0.27; extra == "dev"
Requires-Dist: pre-commit<5,>=4.6; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: pytest-cov<7,>=5; extra == "dev"
Requires-Dist: ruff<1,>=0.9; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="src/anaxigraph/dashboard/favicon.svg" width="112" alt="AnaxiGraph logo" />
</p>

<h1 align="center">AnaxiGraph</h1>

<p align="center">
  <strong>Keep AI-accelerated codebases coherent as they grow.</strong><br />
  See the system behind the source, control entropy, and give coding agents grounded context.
</p>

<p align="center">
  <a href="https://github.com/hcekne/anaxigraph/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/hcekne/anaxigraph/actions/workflows/ci.yml/badge.svg" /></a>
  <a href="LICENSE"><img alt="Apache 2.0 license" src="https://img.shields.io/badge/license-Apache--2.0-167a96" /></a>
  <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-315f9f" />
  <img alt="MCP Streamable HTTP" src="https://img.shields.io/badge/MCP-Streamable_HTTP-7652a4" />
</p>

<p align="center">
  <a href="docs/onboarding.md">Get started</a> ·
  <a href="docs/agent-plugin.md">Agent plugin</a> ·
  <a href="docs/docker.md">Docker</a> ·
  <a href="docs/advanced-operations.md">Advanced</a> ·
  <a href="CONTRIBUTING.md">Contribute</a>
</p>

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`](https://docs.astral.sh/uv/).

### 1. Run one command in the repository

```bash
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:

```bash
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](docs/onboarding.md) explains the normal coding loop and setup
diagnostics.

## 🐳 Durable Docker sidecar

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

```bash
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](docs/docker.md) 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:

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

Invoke `$anaxigraph`. Claude Code:

```bash
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](docs/agent-plugin.md) for the safety contract and custom endpoint behavior.

## How it works

```text
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](docs/platform-support.md).

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](docs/advanced-operations.md) 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

```bash
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`](repo_instructions.md), the consecutive roadmap is
[`docs/feature-development-plan.md`](docs/feature-development-plan.md), and the release contract is
[`docs/releasing.md`](docs/releasing.md). Contributions are welcome; see
[`CONTRIBUTING.md`](CONTRIBUTING.md).
