Metadata-Version: 2.4
Name: anaxigraph
Version: 0.1.0
Summary: A temporal architecture and intelligence layer for software repositories
Author: AnaxiGraph contributors
License: 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: httpx<1,>=0.27; 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"
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 architecture, 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/docker.md">Docker guide</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 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:

```text
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**:

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

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

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

```toml
[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:

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

```bash
# 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](docs/onboarding.md)
for the human-to-agent workflow, optional coverage, history, custom ports, updates, and reset
behavior, and the official [Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp)
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`:

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

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

```bash
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](docs/onboarding.md#build-the-ai-understanding-baseline)
explains the agent-funded loop, hosted workers, privacy controls, incremental invalidation, and
scheduling.

## 🔄 Keep it current

Follow startup or scanning with:

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

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

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

```bash
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](docs/docker.md) and [MaxOS integration](docs/maxos-agent.md).

## 💻 Local CLI

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

```bash
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`](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

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

The product brief and requirement source is [`repo_instructions.md`](repo_instructions.md).
Contributions are welcome; see [`CONTRIBUTING.md`](CONTRIBUTING.md).
