Archy README

Your folders show your architecture. Your imports decide it. archy turns a Python import graph into something an agent can use: blast radius before an edit, the tests that edit affects, the modules most at risk. And it fails when the graph disagrees with the layers you declared. Same graph either way, as a CLI and an MCP server, every session and in CI.

[!IMPORTANT] Status, 2026-09-02: active again, on one question.

archy is back in development after five weeks in maintenance. The focus is narrow and it is not the original one: coding agents running a small model on local hardware. A DGX Spark carries 128 GB of unified memory, which puts roughly 70B to 200B models within local reach at 4-bit, but their usable context stays far below a frontier API model's and degrades faster across it. Under that constraint a structural answer to "what does this change reach, and what breaks if it is wrong" may substitute for context the model cannot hold at all.

This is a bet, not a finding, and the difference matters here. Everything in the section below still stands: I measured this tool's premise four times and the problem it prevents is rare, the one real effect was capped at 12% by how seldom the mistake happens, and two token-reduction propositions came back null. Every one of those studies ran against an agent with a large context window and strong long-range code reasoning - the population where a structural index has the least to add, because the model can often just read the code. A small local model is a different population. That is the one reading of the prior nulls that does not require reinterpreting them, and it might still be wrong.

So the discipline does not relax because the project is active again. The thresholds are pre-registered in #408, no treatment arm has been scored, and any result, including another null, gets published in docs/WHAT_DIDNT_WORK.md like the other four. Nothing archy ships today claims a local-model benefit; archy brief (v0.46) shipped explicitly on judgment ahead of that measurement rather than on one.

What is not changing. The original use case is still supported and still works: layer governance in CI, blast radius and affected-tests for a frontier agent, the MCP server. This is an adjacent focus, not a replacement, and nothing is being removed or renamed to make room for it. Bugs still get fixed, pull requests still get reviewed, and the good first issue tickets are still deliberately left open.

Read this first: I measured the premise, and it was wrong

I built archy after watching coding agents produce changes that passed review and rotted the import graph underneath. Then I measured whether that happens, and it barely does.

So: the problem is real (I have watched a developer's own architecture rule get broken in the wild), and it is rare, for agents and humans alike. "Agents will rot your import graph" is a claim I made and have retracted. Nobody has measured what one occurrence costs, so I cannot argue "rare but expensive" either.

The last row is the one that says what archy is for. All 25 unaided agents produced the four layer directories correctly. Every failure was an import going the wrong way: entities reaching down into data access. They got the layout right and the direction wrong, and a directional rule caught all three cases at no cost to the API's behaviour.

That is the shape of the whole thing. Layout is visible in a file tree. Direction, transitive reach and cycles are visible nowhere, at any zoom level, in any single file. And a separate study found that once one of these lands it is never repaired: zero violations were resolved across the sampled corpus, and 2 of 14 repositories sat on broken contracts indefinitely. Rare and permanent, not rare and self-healing.

What that means for the roadmap: it is closed. Feature work premised on "agents will wreck your architecture" went off the table when that premise was retracted. What survives is narrower and now has a number behind it: directional rules, transitive contracts and cycle detection, checked every session. That is a real job and archy does it, but four studies produced no evidence that more of it is worth building, and the honest reading of four headroom-limited results is that the next feature is not the missing piece.

So archy is finished rather than abandoned. It is maintained, bugs get fixed, and contributions are welcome. There is no roadmap left to publish.

The full write-up, including the six measurement artifacts that nearly turned a failed study into a success story, is in docs/WHAT_DIDNT_WORK.md. If you only read one thing here, read that.

The failure it catches

Nothing in that picture is derived. Which layer a module belongs to, and which direction is forbidden, are facts you write down in archy.yaml; archy only checks that the source still agrees with them.

Here is the failure it was built for, compressed into one line. This is archy's own source, under archy's own layer rules, with a single import of the kind an agent adds when it needs a helper and the nearest one is upward:

# src/archy/graph.py
from archy.cli import main    # convenience import. The diff looks harmless.

$ uvx archy check .
# 1 layer violation(s) (config: archy.yaml)

graph -> cli (forbidden):
  archy.graph -> archy.cli  (line: 21)

$ echo $?
1

$ uvx archy cycles .
# 1 cycle(s) found

Cycle of 8 module(s):
  - archy.cli
  - archy.conventions
  - archy.duplicates
  - archy.graph
  - archy.index
  - archy.mcp
  - archy.simulate
  - archy.watcher

$ uvx archy score .
# archy score: 0.647          (0.656 before the edit)
...
acyclicity:  0.942  (1 cycles, tangle=0.058)
# graph: 139 modules, 264 edges     (263 before the edit)

One import, one edge. A forbidden layer edge, an eight-module cycle, and the score down 0.009. Nothing in the diff itself says any of that, and no amount of reading the file reveals it, because the rule that makes it a violation is not in the source. You supplied it.

Note the size of the score move. 0.009 is small, and that is the honest shape of this problem: no single edit looks alarming on the number. The cycle count going 0 to 1 and check exiting 1 are the signals that matter here, and the score is what catches the version of this that happens forty times over six weeks. Read docs/SCORING.md before treating the composite as a quality gate.

That example is a direct forbidden import, which is the easy case: an agent that reads archy.yaml first can catch it without archy. The harder and more honest case is a transitive violation, where the edit adds no forbidden import at all and reading the config tells you nothing. docs/WALKTHROUGH.md is a one-command reproduction of that, and it states plainly which archy surfaces catch it (one) and which miss it (three).

Reproduce the example above on a checkout: add that import to src/archy/graph.py, then run the three commands with the uvx prefix. It has to be a separate archy, because that one import is a genuine runtime import cycle, and an editable-installed archy can no longer start to report on itself. archy check exits 1, which is what it does in CI and what the MCP server reports to an agent before it commits.

What archy is not: a code-navigation tool. It will not help an agent find and read code faster; that job belongs to symbol-level, multi-language graph tools like codegraph, and they are better at it. archy answers the other question: you declared this codebase should have these layers, no cycles, and this score; is the agent's edit about to break that, and has the trend been sliding for six weeks? Nothing in a navigation graph carries that intent, because intent is not in the source, you supply it.

The sharp version, re-checked against codegraph on 2026-07-27: it ships no cycle detection, no config in which to declare layers or forbidden edges, and no command that exits non-zero on a violation. It will happily show you that models imports repositories if you ask the right question. It cannot tell you that is wrong, because wrongness needs a declaration and there is nowhere to put one. Descriptive tools answer questions; archy makes an assertion that breaks the build. The two are both local MCP servers and compose fine; run them together. See docs/research/CODEGRAPH_COMPETITIVE_ANALYSIS.md for the full comparison, including where archy loses and why this distinction is a choice they made rather than a wall they hit.

Start in one command

uvx archy install     # detects Claude Code, Cursor, Codex, opencode, Continue and wires each one up

Nothing lands on your PATH: the config it writes runs uvx archy mcp on demand. Prefer a real install? pip install archy, uv tool install archy, or pipx install archy. Either way, try it on a project without installing anything:

uvx archy score .        # one-shot architectural health number
uvx archy cycles .       # import cycles, Tarjan SCCs plus self-loops
uvx archy check .        # layer rules from archy.yaml; exits 1 on violation

Free, MIT licensed, no commercial version planned. One maintainer, Python only. Built by Alex Lee.

Status: v0.46.2, working, installed and maintained; in active development on the local-model line (see the top of this page). Usable today via:

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

ADOPTERS.md is empty and no issue has yet been filed by anyone but me. Outside pull requests are a different story and recent: three landed on 2026-07-25, two merged. Good-first tickets are labelled and deliberately left for others.

If you are running archy on a real codebase I would like to hear what it found, especially if the answer is "nothing useful" - that answer is now supported by measurement rather than merely possible.

Why

The failure at the top of this page is the whole reason archy exists: I wanted a single number per commit that would have caught it.

AI agents generate code at machine speed, and the reasoning went: 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.

That reasoning is the part I tested and could not support. Twenty-five agent runs produced zero structural regressions, and human commits break their own declared rules on 0.66% of commits. The drift may still be real over long horizons, which is not what a per-edit measurement can see, but I have no evidence for it and I am not going to assert it. The rest of this section is the case as I originally made it, kept because the citations are accurate even where my inference from them was not.

Where a feedback loop did pay is narrower, and it is the moment code is written rather than the patrol afterwards. Building a new backend to a specified architecture, 3 of 25 unaided agents got the dependency direction wrong; with a checker in the loop, none did, and the API behaved just as well. That is one model, one framework, and the mildest of the Constraint Decay paper's conditions, so it is not a general claim. It does say the loop is worth having at generation time, where the mistake is cheap to prevent and, per the decay study, never repaired afterwards.

What that buys you is placement: it runs in CI, in pre-commit, and as an MCP server (archy mcp), so a coding agent can read its own architectural impact before it commits rather than after review.

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.

The underlying mechanism

Beneath the empirical case is a structural one. Anthony Hobday, writing about software quality, names it precisely: "as the number of things goes up, the number of relationships goes up even faster. Eventually it's impossible for people to properly consider all of those relationships." Coherence is the state where those relationships still hold together; entropy is its steady loss as a system grows. A single author keeps a codebase coherent by remembering every edge. An agent generating code at machine speed cannot, and neither can a team past a certain size.

That relationship load is exactly what archy reads. Coupling, the DSM, import cycles, and change-coupling are all measures of how far the graph has drifted from "one person can hold it in their head." archy externalizes that memory into a number and a trend, so the growth in relationships stays visible instead of being discovered during a refactor that blows up.

Scope

• Python only. The cross-language story belongs to sentrux; that division is settled. archy goes deep on Python (transitive contracts, SDP, NCCD, if TYPE_CHECKING: semantics) rather than broad across languages; see docs/LEARNINGS.md §"Competitive landscape".
• Tree-sitter powered. Robust to in-flight edits and partial files; survives syntax errors that would crash ast.
• Score that trends over time. A single number per commit, persisted, plotted. Trend matters more than the absolute value.
• Rules as YAML. "Layer X cannot import Y." No DSL, no plugins (yet).

Non-goals

• Multi-language analysis
• Replacing linters, type checkers, or test runners
• Generating code or auto-fixing violations

Quick start

Covered above in Start in one command; this section is the detail behind it.

Requires Python 3.10+ (archy depends on mcp>=1.28.1 which is 3.10-only). If you only have system Python 3.9 or older, install a newer Python first or use uv, which manages versions for you and is what uvx comes from.

pip install archy
# or: uv tool install archy
# or: pipx install archy
# or nothing at all: prefix any command with `uvx`, e.g. `uvx archy score .`

Using archy as an MCP server inside an AI coding agent? Skip the manual config and run uvx archy install, which wires it into Claude Code, Cursor, Codex, opencode, or Continue automatically and writes a config that invokes uvx archy mcp, so archy never needs to be on your PATH. See docs/INSTALL.md.

All examples below use the installed archy command. If you're working from a checkout, prefix them with uv run (e.g. uv run archy graph .).

See docs/SIXTY_SECOND_TOUR.md for the copy-paste path from zero to first score.

Inspect the graph

archy graph path/to/project --internal-only
archy graph path/to/project --format json > graph.json
archy graph path/to/project --format dot | dot -Tsvg > graph.svg

Find import cycles

Ranking the modules is what makes a cycle visible: every ordinary import points down a rank, so the one edge pointing back up is the entire finding.

Tarjan SCCs of size >= 2, plus self-loops (a module importing itself). Use --strict in CI to fail on any cycle.

archy cycles path/to/project
archy cycles path/to/project --format json
archy cycles path/to/project --strict

Enforce layer rules

Reads archy.yaml from the repo root. Exits 1 on any violation. See Layer rules below.

archy check path/to/project
archy check path/to/project --format json
archy check path/to/project --config custom.yaml

Transitive contracts (archy contracts)

archy check only sees direct edges. archy contracts wraps import-linter so the same layer story is enforced transitively (A → B → C still counts as A reaching C). It is the strictness upgrade for projects whose layers leak through indirect paths.

pip install 'archy[contracts]'
archy contracts path/to/project
archy contracts path/to/project --format json

archy check --contracts runs this same transitive verdict inline, nested under the check output. It never changes check's own exit code: a flag that can turn a passing check into a failing one because an optional dependency is absent would be unsafe to leave on in CI. Use the standalone archy contracts when the transitive result should itself gate the build.

A kept contract is not automatically protection. A contract whose module expressions match nothing in the graph holds no matter what the code does, so all_kept calls it kept while nothing was ever checked. archy contracts exits non-zero on verified (evaluated and held), not on all_kept, and archy check --contracts reports transitive_checked: false for the same reason: a rule that could not have failed was not evaluated. The text output marks such a contract ?? rather than OK and names the expressions that matched no module; --format json adds top-level verified and unverifiable alongside kept/broken, and per-contract matched_nothing and unmatched_expressions. A .importlinter type = layers contract needs no such flag: import-linter itself refuses to run when a required layer's module is absent, which archy reports as a config error, and an optional layer (written (name)) is absent by design.

Config resolution. archy contracts reads, in order:

1. The --config argument if passed.
2. .importlinter in the project root: the canonical contracts config.
3. archy.yaml: best-effort fallback. Each forbid: rule becomes one Forbidden contract checked transitively. Emits a UserWarning because this path cannot express ignore_imports, so any legitimate transitive edge (e.g., a service layer reaching psycopg through a sanctioned app.libs.db.* module) will be reported as a violation with no way to whitelist it.

Two configs, one concern each:

• archy.yaml owns layer definitions, direct-edge gating (archy check), required-reach rules (required:), sdp:, exclude:, and roots:.
• .importlinter owns transitive contracts: all five contract types (Forbidden, Layers, Independence, Protected, AcyclicSiblings) and ignore_imports whitelists.

Reach for .importlinter as soon as you need transitive enforcement at all; the archy.yaml fallback is a zero-config onramp, not a feature target. See .importlinter in this repo for a real-world example, and the import-linter contract types reference for the full grammar.

Common case: forbid services from reaching psycopg but allow the sanctioned db library to do so:

[importlinter]
root_package = app

[importlinter:contract:services-must-not-reach-psycopg]
name = services must not reach psycopg
type = forbidden
source_modules =
    app.services
forbidden_modules =
    psycopg
ignore_imports =
    app.libs.db.engine -> psycopg

Compute a quality score

Composite of modularity, acyclicity, depth, equality, and complexity (geometric mean of five axes). See docs/SCORING.md for formulas and how to interpret the breakdown. These five axes were chosen after surveying ~15 alternatives from the package-metrics literature (Martin's I/A/D, Lakos's NCCD, MacCormack propagation cost, Structure101 fat/tangle, reflexion models, cognitive complexity, hotspots, logical coupling, dead/duplicate-code detection); Martin's I and the Stable Dependencies Principle check are also shipped as a per-module diagnostic and an archy check rule. See docs/research/RESEARCH_METRICS.md for the full validation, what was shipped, and what was deferred and why.

archy score path/to/project
archy score path/to/project --format json

Track score over time

Persist per-commit scores to .archy/history.jsonl and chart the trend.

archy score path/to/project --record
archy trend path/to/project
archy trend path/to/project --last 30 --format json

Regression gate

Fail if the current score drops more than --strict-tolerance (default 0.02) below the most recent recorded run.

archy score path/to/project --strict
archy score path/to/project --strict --record           # check then record
archy score path/to/project --strict --strict-tolerance 0.0

Blast radius

List internal modules that transitively depend on a given file. Useful before refactoring or removing a module.

archy impact path/to/project --file app/libs/db.py
archy impact path/to/project --file app/libs/db.py --file app/services/auth.py --format json

Affected tests (CI gating)

archy affected is the CI-shaped cousin of archy impact: given changed files, it returns the impacted modules pre-classified into tests and other downstream code, with a depth cap (default 5 hops) so a one-line edit doesn't fan out to thousands of nodes on a monorepo. Pipes naturally from git diff:

git diff --name-only HEAD | archy affected . --stdin
git diff --name-only HEAD | archy affected . --stdin --quiet | xargs pytest
archy affected . src/foo.py --filter "tests/integration/**" --json

Test classification defaults to pytest conventions (test_*.py, *_test.py, anything under a tests/ directory); override with --filter <glob>. Internal modules only; vendored or third-party code is not traced.

Design Structure Matrix (archy dsm)

The DSM puts modules on both axes in a chosen ordering, and cell (row=source, col=target) is non-empty when source imports target. Reading positionally exposes properties any single scalar would hide: block-diagonal cohesion under community grouping, above-diagonal back-edges under topological ordering, off-block layer leakage under layer grouping. Visualization-only (docs/research/DSM_EMPIRICS.md for why no scalar joins the score).

archy dsm path/to/project --group community     # block-diagonal orientation
archy dsm path/to/project --group topological   # back-edges sit above diagonal
archy dsm path/to/project --group layer --weight calls   # cross-layer call traffic
archy dsm path/to/project --focus pkg.module --focus-depth 1   # focal neighborhood
archy dsm path/to/project --format json > .archy/dsm-before.json
# ... edit code ...
archy dsm path/to/project --group topological --diff .archy/dsm-before.json
# prints any new back-edges the edit introduced

archy dsm refuses ASCII rendering for projects larger than --max-nodes (default 80) with an actionable error pointing at --focus, --package, or --format json.

Static HTML export (archy render)

Every other archy surface targets the agent. archy render targets the human reviewing what the agent did: a single self-contained HTML file to attach to a PR, drop in docs, or open offline. No JavaScript, no CDN, no vendored bundle, no server, and byte-stable for a fixed input, so two exports diff cleanly.

archy render path/to/project --view dsm --out dsm.html     # the matrix, flagged cells in red
archy render path/to/project --view dsm --group topological --out cycles.html
archy render path/to/project --view trend --out trend.html # five axes over .archy/history.jsonl
archy render path/to/project --view dsm                    # HTML to stdout

What red means follows the ordering you asked for, because only one ordering encodes it: under --group=topological red is a back-edge (a cycle seed), and under --group=community or --group=layer, where block order is not a dependency order, red is an edge crossing a block boundary. The DSM view refuses matrices larger than --max-nodes (default 300) rather than writing an unreadable file.

There is no graph view. A node-link diagram is the one view that needs a vendored layout engine, and it is also the lowest-signal of the three; it stays deferred behind a usage signal (see docs/SPEC_VISUALIZATION.md).

Snapshot and diff (agent feedback loop)

Capture a baseline at the start of an editing session, then diff after edits to see exactly which cycles or layer rules changed. See docs/AGENT_LOOP.md for the full playbook (also available via the MCP server's loop prompt).

archy snapshot path/to/project   # writes .archy/baseline.json
# ... edit code ...
archy diff path/to/project       # risk-weighted summary + score deltas + added/resolved cycles & violations

Run as an MCP server

Stdio transport, so AI agents can call archy directly. See MCP server below.

archy mcp

MCP server (archy mcp)

The server is backed by a persistent parse cache (.archy/index.db): each tool call re-parses only the files whose content changed since the last call, so warm graph builds stay in the low seconds even on very large repos (benchmarked: 21.5s cold to 2.5s warm on Home Assistant's 17,299 modules). The cache is transparent and disposable; deleting .archy/index.db only costs one cold rebuild. The graph is always re-derived from the current files, so a cached result is never stale. archy index sync warms it explicitly; archy index clear removes it.

archy mcp exposes thirteen tools and one prompt to MCP-aware AI agents (Claude Code, the Anthropic API, etc.):

The server also exposes a loop prompt with the agent feedback-loop playbook (snapshot at start, impact before edit, diff after edit). Discoverable via the standard MCP prompts/list call. See docs/AGENT_LOOP.md for the human-readable version.

The archy mcp server still keeps a debounced filesystem watcher warming .archy/index.db so graph builds stay fast, and every tool syncs on demand so a result is never stale. The index-freshness readout that used to be the archy_status MCP tool is now the CLI archy index status (#267): freshness is diagnostic plumbing an agent rarely needs mid-task, not a per-edit decision.

Tool output contract (structured output)

Every tool declares an outputSchema (JSON Schema, derived from its return model) in tools/list, and every tools/call returns both a structuredContent object (validated against that schema) and a text block with the same JSON, per the 2025-06-18 MCP structured-output spec. All tools are also annotated readOnlyHint: true (closed-domain, idempotent, non-destructive), so trusted clients can auto-approve archy's calls instead of prompting on every read. Sequence returns (archy_cycles, archy_score(view="history")) and union returns (archy_diff, archy_graph, archy_dsm) are wrapped under a top-level result key since structuredContent must be a JSON object; for unions every branch (including the in-band *ErrorPayload shapes) is a conforming anyOf member.

Error model (recovery contract)

archy maps failures onto MCP's two error mechanisms with one convention, so an agent has a single recovery contract:

• Usage error → isError: true (a raised exception): an invalid argument value (e.g. response_format="xml", last_n=0), a malformed archy.yaml, or a project over the scan ceiling. The caller must fix the call or the environment.
• Recoverable / advisory → in-band result (isError: false): an expected precondition that isn't met but is recoverable, or a valid-but-degraded result. These are normal results the agent branches on. Either a union variant when there's no usable result (no baseline → DiffErrorPayload, output too large → *TooLargePayload, no config → CheckErrorPayload, no DSM snapshot → DSMErrorPayload), or an advisory field on an otherwise-valid payload (ContractsPayload.available=false, WhatToRefactorPayload.git_available / WhatToRefactorPayload.note). The marker for a "no usable result" variant: a payload with an error field and no success data.
• Protocol error (JSON-RPC): unknown tool or a missing/mistyped required argument, handled by the framework.

Wiring it into your agents

One command detects your installed clients (Claude Code, Cursor, Codex CLI, opencode, Continue) and wires each one up:

uvx archy install        # detect, confirm, register the MCP server in each client
uvx archy uninstall      # the exact inverse; --dry-run to preview

This registers the uvx archy mcp server, drops a short rules file so the agent knows when to call the tools, and (on Claude Code) seeds the permissions.allow allowlist. It does not install a binary or the Claude plugin. The full guide, including the per-client path matrix, the manual stanza for unknown clients, plugin-vs-installer guidance, and troubleshooting, is in docs/INSTALL.md.

The lowest-friction path specifically on Claude Code is the bundled plugin at plugins/claude/: /plugin marketplace add hslee16/archy then /plugin install archy@archy from inside Claude Code (or claude --plugin-dir /path/to/archy/plugins/claude from a checkout). See docs/INSTALL.md for when to prefer it over the installer.

Regression-gate semantics

--strict reads the last row from .archy/history.jsonl and compares the current score against it. Drops beyond the tolerance fail with exit code 1. The default tolerance (0.02) matches the threshold sentrux's gate uses. This gives archy parity with sentrux's regression-gate use case while keeping the long-term JSONL history for archy trend.

CI integration

GitHub Action

archy ships a composite action you can drop into any workflow:

- uses: hslee16/archy@v0.46.2
  with:
    command: score      # score | check | cycles
    path: .
    strict: "true"      # fail on regression (score) or any cycle (cycles)

Inputs (all optional unless noted):

Pre-commit hook

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/hslee16/archy
    rev: v0.46.2
    hooks:
      - id: archy-check          # layer rules from archy.yaml
      - id: archy-score-strict   # regression gate against last recorded score
      - id: archy-cycles         # fail on any import cycle

archy-score-strict reads .archy/history.jsonl; commit a baseline first with archy score . --record.

Layer rules (archy check)

Drop an archy.yaml at the repo root declaring layers and forbidden directions:

layers:
  domain:
    modules:
      - "myapp.domain.**"
  application:
    modules:
      - "myapp.application.**"
  infra:
    modules:
      - "myapp.infra.**"
      - "myapp.adapters.**"

forbid:
  - {from: domain, to: application}
  - {from: domain, to: infra}
  - {from: application, to: infra}

Pattern syntax. Dotted-name globs: * matches one segment, ** matches zero or more. myapp.domain.** covers the package itself and every descendant. Modules must belong to at most one layer.

Required reach (required:). The inverse of forbid:. A forbid rule catches an edge that should not exist; a required rule catches one that should exist and does not, which forbidding cannot express:

required:
  - source: "app.commands.*"
    must_reach: app.core.database.model_registry
    reason: standalone entrypoints need the full mapper registry

Every module matching source must transitively reach must_reach, counting the implicit package-__init__ import Python guarantees (importing a.b.c runs a/b/__init__.py first). So one import in app/commands/__init__.py satisfies the rule for every command module, which is usually the correct fix -- a direct-import rule would report all of them as violations after that fix.

This came from a production incident: 34 command modules run standalone, each needing a SQLAlchemy model registry imported before first mapper configuration. 11 imported it, 21 crashed at runtime, and 2 passed only because they happened to reach it through unrelated imports. Those 2 are why the rule is defined over reach rather than imports.

reason is carried into every output surface, because "X does not reach Y" is a fact about the graph and not an explanation, and a rule nobody can justify gets deleted rather than satisfied. A rule whose patterns match nothing is reported as a violation, not passed over. Note pkg.** includes pkg/__init__.py itself; use pkg.* to scope the rule to submodules.

Be honest about what this does: archy cannot derive such a requirement (that is framework semantics, not graph structure). Someone has to know the constraint and write it down. What the rule then does is find every other module that violates it and stop the next edit from undoing the fix -- a ratchet, not a detector.

Excluding directories. Add an optional exclude: list of directory basenames to skip codegen output, vendored code, etc. Each name is matched anywhere in the project tree (same mechanism as the built-in skips for .venv, node_modules, __pycache__):

exclude:
  - baml_client
  - generated

exclude: applies to every analysis (graph, cycles, score, check) and the equivalent MCP tools.

Scan-size guard (max_modules:). archy refuses to start a scan of a tree with more modules than a ceiling, so a stray vendored, cache, or generated directory that the named exclude: skips do not cover cannot silently wedge a scan for minutes. The default (10,000) sits well above the largest real projects; a scan that trips it stops with a message pointing at exclude: / a narrower path. Override or disable it:

max_modules: 25000   # raise the ceiling for a genuinely large monorepo
# max_modules: 0     # disable the guard entirely

Namespace packages (roots:). archy discovers packages by walking __init__.py files. PEP 420 namespace packages (no __init__.py) are invisible by default. Declare them as roots so descendants get qualified names:

roots:
  - app           # `app/main.py` becomes `app.main`
  - src/service   # `src/service/db.py` becomes `service.db`

Without roots:, a project like app/libs/db.py (no app/__init__.py) is either skipped entirely or shows up as a top-level libs.db, which makes layer rules like app.libs.** match nothing.

Layer presence (min_layers_present:). Forbidding edges between layers says nothing about whether the layers exist. A codebase that collapsed four layers into one module satisfies every forbid rule by having no cross-layer edges at all, and passes silently. Set a floor to catch that:

min_layers_present: 3   # at least 3 of the declared layers must contain a module

Empty declared layers are reported either way, because every rule naming one is dead:

#   layers present: 2 of 4 declared; empty: repositories, models
#   FAIL: 2 layer(s) present, min_layers_present is 3

Unset by default, so existing configs keep their exit codes. The shape is taken from the Constraint Decay paper (arxiv:2605.06445), whose architecture verifier pairs a dependency-direction rule with exactly this presence floor ("at least 3 of the 4 canonical layers present as distinct directories"). bench/fixtures/conduit_clean/ reproduces its three cases.

It is a backstop, not the main event, and the measurement says so. Across 50 agent-generated backends, every single one produced all four layer directories: this check never fired once, while the direction check caught every failure. Keep it for the collapsed-into-one-module case it is named for, but if you are deciding where to spend effort in a config, spend it on forbid rules.

Discovery. archy check walks PATH upward to find archy.yaml unless --config is given. Exits 1 on violation.

Coverage. Every check reports how much of your code the rules actually reach, on a pass as well as a failure:

$ archy check .
# No layer violations (config: archy.yaml).
#   layer coverage: 9 of 42 modules (21%), 16 of 117 internal edges (14%); 33 module(s) match no layer (`archy check --show-unlayered`)

That line exists because a rule set that cannot fire is indistinguishable from a clean codebase: without it, a config governing 14% of your import edges prints the same "No layer violations" as one governing all of them. The edge percentage is the one to watch, since a config can put most modules in layers while ruling almost none of the edges between them. Coverage is scoped to the root packages your patterns name, so scripts and benchmarks sitting beside your package are counted separately rather than dragging the number down. --show-unlayered lists the modules no layer matches.

The numbers above are archy's own, and they are not flattering. They are printed here because the alternative is not knowing.

archy enforces its own architecture this way; see archy.yaml at the repo root and the archy check . step in .github/workflows/ci.yml.

Stability check (sdp:). Optionally enable Robert Martin's Stable Dependencies Principle: a module should not import one that is less stable than itself. Stability is I = Ce / (Ce + Ca) where Ce is outgoing internal imports and Ca is incoming, so I = 0 means "depended on, depends on nothing" (most stable) and I = 1 means "depends on lots, nothing depends on this" (least stable).

sdp:
  enabled: true
  tolerance: 0.0   # ignore violations within this I gap; default 0
  mode: error      # 'error' fails the gate (default); 'warn' reports but exits 0

When enabled, archy check flags every internal import edge whose target's I strictly exceeds the source's (plus tolerance). Per-module I is also surfaced in archy graph --format json whether or not sdp: is enabled, so you can audit before turning enforcement on.

Gradual adoption. Existing codebases will often have SDP violations on day one. Set mode: warn to report violations in the output (and archy_check's sdp_violations payload) without failing the gate, then flip to mode: error once the count is at zero. Layer-rule violations always fail the gate regardless of sdp.mode.

Development

uv sync                    # install runtime + dev deps from uv.lock
uv run ruff check          # lint
uv run ruff format         # format
uv run ty check            # type check
uv run pytest              # tests

One pytest case (test_pagerank_matches_networkx_when_available) compares archy's hand-rolled _pagerank against nx.pagerank, which needs numpy/scipy. The dependency is intentionally not in the default install (archy stays scientific-stack free); to run that test locally, sync the optional parity group:

uv sync --group parity     # pulls in numpy + scipy for the parity test
uv run pytest              # the test now runs instead of being skipped

Roadmap

This roadmap is closed. Nothing below is planned. See the status note at the top of this page; docs/ROADMAP.md and docs/FUTURE.md carry the same closure and the reasoning behind it.

Both phases of the index-and-install work shipped (Phase 1 install-DX in v0.25.0 / v0.26.0, Phase 2 persistent index + watcher in v0.27.0). What follows is kept as a record of what was considered and why, not as a plan. Several items rest on a premise that has since been retracted, so read docs/WHAT_DIDNT_WORK.md before picking one up. Anyone is welcome to.

Considered and never started:

• Per-module score breakdown so an agent can ask "did my edit make this module worse?" rather than "did the project overall regress?". Pairs with archy_diff.
• Opt-in agent hooks (archy install --hooks): register a lifecycle hook in the agent client (Claude Stop, Cursor afterFileEdit, ...) that runs the archy gate automatically after edits, so the loop fires whether or not the agent remembers to call the tools. Spec: docs/SPEC_INSTALL_HOOKS.md.
• Static fragility proxy (high-instability x high-fan-in) as a git-free hotspot stand-in. Advisory, not a score axis. (Duplicate-function detection has shipped as the archy duplicates CLI command: a two-tier surfacer with a primary "likely duplicate" list and a demoted "same-class / boilerplate variant" list. A literature review confirmed ~50% refactorability precision is the expected ceiling for any similarity-only detector, so the semantic call is left to the agent; change-history co-change is the precision layer, shipped as demote_independent (#242) on the change-coupling machinery #131. Exposed on both the CLI (archy duplicates) and MCP (archy_duplicates, the 14th tool).)

The shipped history moved to docs/SHIPPED.md, grouped by the part of the tool each feature belongs to. It is a record of what was built, not evidence that any of it helped.

Empirically rejected (kept here so they don't get re-proposed): type-hint coverage in any form, calls_per_edge as a 6th axis, HTML output on agent-facing commands, dead-function detection, multi-language analysis. See docs/ROADMAP.md for the evidence behind each.

See docs/FUTURE.md for the longer list and docs/LEARNINGS.md for design notes.

Contributing

See CONTRIBUTING.md for style rules. Notably: no em-dash characters (U+2014) anywhere in the repo.

Reporting security issues

Please report vulnerabilities privately via the Security tab, not as a public issue. See SECURITY.md for scope and response targets.

License

MIT, see LICENSE.