ArchSteer

ArchSteer conformance PyPI License: MIT

Living Architecture Control Plane for the AI-Dev Era.

AI agents now write code faster than any architect can review, document, or govern it. Docs rot instantly, the real architecture is invisible, structural decisions get made silently, and intended architecture drifts with every edit. ArchSteer is the always-current architecture system of record + governance plane: it derives the real architecture from code, keeps living docs and ADRs auto-built, surfaces every major decision for the architect to ratify, enforces declared intent as code-level fitness functions, and steers AI agents to conform instead of replicating local slop.

Everything is a projection of one code-derived model — .archsteer/model.json.

Local by default: the X-ray and governance workflow runs locally and never uploads or executes your repository's source code. It needs no account, API key, or configuration before the first scan; cloud snapshot publishing is a separate, explicit push command.

                    .archsteer/model.json  (single source of truth)
                                 │
   MAP ──── DOCUMENT ──── GOVERN ──── STEER ──── EVOLVE
  model    living docs   fitness     agent     report.html
  from     + auto ADRs   functions   guardrails  (drift/
  source   + diagrams    + ratchet   + MCP       decisions)

Install

As a Claude Code plugin (recommended if you use Claude Code):

/plugin marketplace add einvoice-dev1/archsteer
/plugin install archsteer@archsteer

This installs the bundled MCP server (current_architecture, get_target_pattern, check_file — via uvx, no separate pip install needed) plus a skill that teaches the agent when to x-ray, check, and steer on its own, and /xray / /check commands. See .claude-plugin/plugin.json for the manifest.

As a CLI (works with any editor/agent, or standalone):

pip install archsteer                 # regex engine + local MCP server; no parser toolchain required
pip install "archsteer[treesitter]"   # optional native acceleration

(Since 0.4.1 the MCP server ships in the base install; pip install "archsteer[mcp]" still works as a no-op alias.)

Languages: JavaScript / TypeScript (Next.js App Router-aware, including tsconfig.json path-alias resolution — @/lib/x resolves to a real internal edge, not a phantom third-party dependency), Python, Java (Spring-aware), and Salesforce Apex (SOQL/DML + trigger/handler/selector conventions). Layer detection uses in-source signals first — Spring stereotype annotations, Apex class-name conventions, Next.js reserved filenames (page.tsx → page, layout.tsx → layout, route.ts → api, regardless of directory) — then directory names.

Quickstart

For the fastest proof, run this in a repository and open the generated .archsteer/report.html:

archsteer init && archsteer map && archsteer report

Then add the controls you need:

archsteer init      # scaffold .archsteer/ + a starter rule pack auto-matched to your stack
archsteer map       # build model.json from source
archsteer docs      # regenerate .archsteer/architecture.md (deterministic, Mermaid) — includes a "Start here" hub/entry-point guide and a file-level component map
archsteer graph <path>  # one component's direct dependencies + dependents — no intent required, just dropped into an unfamiliar file
archsteer govern    # conformance + drift score by rule
archsteer adr       # draft ADRs: new structural decisions + widespread rule violations
archsteer baseline  # accept current debt — the ratchet
archsteer steer -f src/controllers/payment.js -t "add refund endpoint"
archsteer check     # CI/pre-commit: fail on NET-NEW violations only
archsteer install-hooks   # wire `check` into a local git pre-push hook
archsteer report    # self-contained .archsteer/report.html

init auto-detects your stack and seeds a matching baseline rule pack — edit .archsteer/architecture.yaml to fit your conventions, or pick one explicitly:

Pack	Detected by	Baseline rules
java-spring	pom.xml / build.gradle	persistence only in repositories; controllers never touch repositories; no hardcoded secrets; outbound calls confined to services
salesforce	sfdx-project.json / force-app	SOQL only in selectors; logic-less triggers; no DML in controllers; no hardcoded secrets; callouts confined to services
python-service	pyproject.toml / requirements.txt	persistence behind repositories; thin API handlers; no hardcoded secrets; outbound calls confined to services
nextjs-app-router	package.json has next, an app/ dir, no express	data access (Supabase/Prisma/raw SQL) and third-party calls confined to lib/ or a route handler; no hardcoded secrets
express-to-next	package.json (fallback, or express present)	repository pattern; Express → Next.js migration; no hardcoded secrets; outbound calls confined to services

A repo with next as a dependency and an app/ directory gets the App Router pack; a package.json with express (even one migrating to Next) gets the migration pack instead — those are different problems with different rules.

Every starter pack ships a security baseline — no hardcoded credentials/API keys/tokens anywhere in source, and all outbound third-party calls confined to the service layer — so day-one governance covers architecture and the two security smells AI agents introduce most often.

archsteer init --pack salesforce   # override the auto-detection

The three design guarantees

1. Ratchet, not freeze. archsteer check blocks only net-new violations against a baseline — teams keep shipping features while debt can only shrink.
2. Conservative, architect-in-the-loop ADRs. Two narrow sources, both opt-in review — never auto-committed. Across time: external-boundary changes (new dependency, new datastore, new layer) — never internal reshuffles. Within a snapshot: a rule violated in 3+ components — a genuine pattern worth ratifying or relaxing, not a one-off left to check/govern. Drafts are idempotent; re-running never duplicates one already on disk.
3. Sharp agent steering. Guardrails injected into CLAUDE.md, AGENTS.md, and .cursor/rules/archsteer.mdc (an always-on Cursor rule) are scoped to the files in play and point at the governing ADR — they don't dump the whole model into the context window.

Declaring intent — .archsteer/architecture.yaml

target: "Migrate Express + raw SQL to Next.js route handlers + the repository pattern"
layers: [route, controller, service, repository, model]
rules:
  - id: no-raw-sql-outside-repository
    type: required_layer_for_data_access
    allowed_layers: [repository]
    operations: [RAW]
    severity: error
    adr: .archsteer/adr/0001-repository-pattern.md
    steer: "Wrap all queries in a repository under src/repositories/. No raw SQL elsewhere."

Rule types: required_layer_for_data_access, forbidden_import, forbidden_data_access, forbidden_layer_edge, forbidden_security_finding (hardcoded secrets), and required_layer_for_external_call (confine outbound HTTP/SDK calls to a layer).

Using with AI agents (MCP)

archsteer mcp runs a local MCP server over stdio — spawned by your own editor/agent, never hosted by us. It reads only what init/map/govern already wrote to .archsteer/ on disk, so there's no network call and nothing leaves your machine. It exposes three tools:

• current_architecture — component/layer counts, conformance/drift, the declared target.
• get_target_pattern — the invariants that apply to a file, before you write to it.
• check_file — whether a file you just edited conforms, without waiting for CI.

Using the Claude Code plugin above? This is already wired up — skip to Quickstart. The rest of this section is for every other client.

Add it to Cursor with one click: Install in Cursor →

Add it to Claude Code by hand (instead of the plugin), or any other MCP-compatible client:

claude mcp add archsteer -- uvx archsteer mcp    # no separate pip install needed

Or in JSON config directly:

{ "mcpServers": { "archsteer": { "command": "uvx", "args": ["archsteer", "mcp"] } } }

(Already have archsteer on PATH via pip/pipx? {"command": "archsteer", "args": ["mcp"]} works identically — uvx just means no install step at all.)

Also published to the official MCP registry as io.github.einvoice-dev1/archsteer.

CI / pre-commit / pre-push

• GitHub Action: .github/workflows/archsteer.yml (maps, drafts ADRs, runs the net-new gate, uploads report.html).
• Local pre-push hook: archsteer install-hooks wires archsteer check into .git/hooks/pre-push — an architecture conformance score printed on every push, blocking only NET-NEW error violations (the same ratchet as CI, just earlier feedback). archsteer map/check cache per-file parse results in .archsteer/parse_cache.json, so a push that only touches a handful of files re-parses just those files, not the whole repo. Uninstall with archsteer install-hooks --uninstall.
• Already using husky, pre-commit, or lefthook? Add archsteer check as a step instead of the raw git hook, e.g. a .husky/pre-push containing archsteer check.

Conformance badge

If your repo pushes snapshots to the situation room (archsteer push), its latest conformance score is a live badge — the one at the top of this README is this repo governing itself:

[![ArchSteer conformance](https://img.shields.io/endpoint?url=https%3A%2F%2Fwww.archsteer.com%2Fapi%2Fbadge%2FYOUR-REPO)](https://www.archsteer.com)

Replace YOUR-REPO with the repo name archsteer push reports. Green at ≥90%, grey while you're still x-ray-only (no architecture.yaml declared yet).

Try the demo

cd examples/demo-repo
archsteer init && archsteer map && archsteer report   # open .archsteer/report.html

Roadmap

• Shipped — cloud control plane (Next.js + Supabase): multi-repo situation room with drift/decision time-series. archsteer mcp: a local MCP server so agents query the live model + intent mid-edit. An org-wide, hosted MCP server (Team tier) so agents can ask cross-repo questions against the situation room — "what's our drift index," "which repos have pending ADRs" — the same data as the dashboard, over MCP. A Claude Code plugin (skill + commands + the MCP server, one install). A dedicated Next.js App Router pack (layers from page.tsx/layout.tsx/route.ts, tsconfig.json path-alias resolution, Supabase/Prisma-aware data-access detection). archsteer install-hooks: the same net-new conformance ratchet as CI, wired into a local git pre-push hook.
• Later — a VS Code extension (inline diagnostics, status-bar score — the CLI/MCP already work in any editor today), auth, org/repo model, billing.

Development

python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

Found a surprising edge, a false positive, or a stack ArchSteer should understand better? Open an issue with the language, framework, and smallest reproducible example. Builder feedback directly shapes the detectors and starter rule packs.