AI coding agents (Claude Code, Codex, Cursor) often edit files with local context only. This causes architectural erosion:

1. Low-level modules import high-level UI modules to save time.
2. Refactoring steps silently break exported symbols and APIs.
3. Reading whole repositories wastes tens of thousands of tokens per turn.

agent-arch provides a zero-token, sub-15ms AST safety net. It builds a deterministic topology map and enforces strict layering rules with a physical Git hook.

Quick Start

Two commands to protect your codebase from AI coding agent erosion:

# 1. Query upstream and downstream dependencies for an agent (< 15ms)
uvx agent-arch --query <module_or_symbol>

# 2. Install Git pre-commit hook and AGENTS.md rules in one command
uvx agent-arch --init

The diagram uses example layer names. Configure layer ranks for your project.

The sub-15ms figure applies to cache reads. Local architecture checks use zero LLM tokens. These checks cover layering and public APIs. They do not prove that all code is correct. See the benchmark report and image prompts and settings.

Features

• Sub-15ms Index Latency: Deterministic AST scanning with compact JSON caching.
• Zero Token Verification: Check architectural rules locally with zero LLM API cost.
• No Reverse Imports: Prevent lower layers from importing upper layers.
• Public API Safety Net: Detect breaking changes and require backward-compatible facade shims.
• Zero External Dependencies: Pure standard library Python with optional orjson acceleration.

Comparison with Existing Tools

Key Differences

1. vs Aider repo-map: Aider ranks symbols with PageRank to feed large context into LLM prompts, but it does not prevent architectural erosion. agent-arch enforces strict single-direction layering and API compatibility checks.
2. vs Tach / Import Linter: Tach and Import Linter target human CI pipelines with terminal error outputs. They lack a sub-15ms surgical query interface for agents to look up upstream dependencies and downstream callers on-demand.
3. vs ast-grep: ast-grep is a powerful single-file CST pattern matcher, but it cannot resolve imports across files or detect circular dependency cycles.
4. vs arch-analyzer / LLM Reviewers: Wrapping LLMs to review code is slow, expensive, and non-deterministic. agent-arch uses deterministic, zero-token local AST analysis that runs on every git commit.

Installation

Run directly with uvx (no prior installation needed):

uvx agent-arch --query <symbol_or_module>
uvx agent-arch-guard --strict

Or install via uv / pip:

uv add --dev agent-arch
# or
pip install agent-arch

Usage

0. One-Click Guardrail Installation (--init)

Enforce guardrails on any repository with a single command:

uvx agent-arch --init

This command automatically:

1. Installs a Git pre-commit hook (.git/hooks/pre-commit) that physically blocks any git commit violating architectural rules.
2. Appends architectural guidelines to AGENTS.md so AI agents (Claude Code, Codex, Cursor) know the constraints before writing code.
3. Initializes .agent_arch/ cache and default pyproject.toml settings.

1. Query Codebase Topology (Surgical Agent Orientation)

Display a clean architectural summary of your codebase:

agent-arch

Query a specific module to inspect its layer, classes, upstream imports, and downstream callers:

agent-arch --query relabel.py

Locate a symbol across the entire repository:

agent-arch --query UserEntity

2. Verify Architecture Integrity (CI & Preflight Guardrails)

Run layering and compatibility checks:

agent-arch-guard

Compare API compatibility across Git revisions:

agent-arch-guard --base origin/main

Compare two files directly:

agent-arch-guard --compare-files old_module.py new_module.py

Configuration

Add an optional [tool.agent-arch] section to your pyproject.toml to customize layers and scanned directories:

[tool.agent-arch]
scan_dirs = ["src"]
exclude_dirs = [".git", ".venv", "tests", "dist"]
cache_path = ".agent_arch/index.json"
cache_ttl = 300.0

[tool.agent-arch.layers]
0 = { name = "Domain", description = "Base entities and types", match = ["domain", "models", "types"] }
1 = { name = "Storage", description = "Database and file I/O", match = ["storage", "io", "db"] }
2 = { name = "Core", description = "Business logic and algorithms", match = ["services", "core", "algorithms"] }
3 = { name = "Workflow", description = "Controllers and handlers", match = ["controllers", "handlers"] }
4 = { name = "UI", description = "User interface and entrypoints", match = ["ui", "views", "cli", "main"] }

Benchmarks

See BENCHMARK_AND_VERIFICATION.md for stress test records across 2,300+ modules and sub-1ms cache latency measurements.

License

MIT License.