archy

Architectural sensor for Python codebases - keeps structure honest under AI-assisted development.

pip install archy
archy score .         # one-shot architectural health number
archy hotspots .      # refactor priority = complexity x git churn
archy mcp             # expose 17 tools to Claude Code, Cursor, any MCP client

Free, MIT licensed, no commercial version planned. Built and maintained by Alex Lee.

Status: v0.27.0. Usable today via:

Mode	Command
Inspection	archy graph, archy cycles
CI governance	archy check (reads archy.yaml)
Transitive contracts	archy contracts (reads .importlinter (canonical) or falls back to archy.yaml; requires archy[contracts])
One-shot score	archy score
Trended score	archy score --record + archy trend
Refactor priority	archy hotspots (CC x git churn)
CI impact lookup	archy affected (git diff -> impacted modules + tests, depth-capped)
MCP server	archy mcp (cached: warm graph builds in seconds even on 10k+ module repos)
Parse cache	archy index sync / archy index clear (persistent .archy/index.db; transparent under the MCP server)
Agent install	archy install / archy uninstall (auto-detect Claude Code, Cursor, Codex, opencode, Continue; wire in or cleanly remove the MCP server)

How the score is computed and how to read it: docs/SCORING.md. Benchmarks against pydantic, fastapi, flask, pytest, and archy-on-archy: docs/CASE_STUDIES.md. Design rationale and comparison with sentrux: docs/LEARNINGS.md.

In the wild

archy is used in production by the projects listed in ADOPTERS.md. If you're running archy on a real codebase, please open a PR to add yourself, or file an issue and I'll add you.

Why

I built archy because I kept watching coding agents generate code that passed review but rotted the import graph underneath. The score on a feature change would look fine; six weeks later the cycle count had doubled and nobody noticed until a refactor blew up. I wanted a single number per commit that would have caught it.

AI agents generate code at machine speed. Without a feedback loop on structural health (module coupling, import cycles, layer violations), codebases drift architecturally even when every individual change looks fine in review.

archy watches a Python codebase, builds a live module-dependency graph, and surfaces drift through a single trended score plus a handful of actionable sub-metrics. It's designed to run in CI, in pre-commit, and as an MCP server (archy mcp) so coding agents can read their own architectural impact before committing.

The agent-feedback framing is empirically supported by 2025-2026 research: the Navigation Paradox paper shows large LLM context windows do not eliminate the need for structural graph navigation, LocAgent's ablation finds graph edges materially improve code-localization accuracy, the Constraint Decay paper (arxiv:2605.06445) finds agents lose ~30 points in pass rate as architectural constraints accumulate (Clean Architecture layering alone costs -9.1 points, on the open and mid-tier models tested) and that its ground-truth layer/dependency-direction verifier is essentially archy check, and the coding-agent failure-mode literature names the specific patterns (scope drift, cross-file reasoning failure) that an architectural feedback loop is built to catch. Citations, a failure-mode-to-archy-capability mapping, and the resulting roadmap priorities are in docs/research/RESEARCH_METRICS.md §14c.

Scope