io.github.einvoice-dev1/archsteer
Architecture governance for AI agents: query the live model, get target patterns, check files.
Open source Open in the app JSON README (API)
About
Architecture governance for AI agents: query the live model, get target patterns, check files.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- einvoice-dev1
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.10.0
- Stars
- 5
- Last push
- 2026-07-30T18:04:36Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:45
- Updated
- 2026-08-29 03:02:45
- Origin id
io.github.einvoice-dev1/archsteer
README
<!-- mcp-name: io.github.einvoice-dev1/archsteer -->
# ArchSteer
[](https://www.archsteer.com)
[](https://pypi.org/project/archsteer/)
[](LICENSE)
**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`](.claude-plugin/plugin.json) for the manifest.
**As a CLI** (works with any editor/agent, or standalone):
```bash
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`:
```bash
archsteer init && archsteer map && archsteer report
```
Then add the controls you need:
```bash
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.
```bash
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`
```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](#install) above?** This is already wired up — skip to
[Quickstart](#quickstart). The rest of this section is for every other client.
Add it to Cursor with one click:
[**Install in Cursor →**](cursor://anysphere.cursor-deeplink/mcp/install?name=archsteer&config=eyJjb21tYW5kIjoiYXJjaHN0ZWVyIiwiYXJncyI6WyJtY3AiXX0%3D)
Add it to Claude Code by hand (instead of the plugin), or any other MCP-compatible client:
```bash
claude mcp add archsteer -- uvx archsteer mcp # no separate pip install needed
```
Or in JSON config directly:
```json
{ "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](https://registry.modelcontextprotocol.io) 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:
```markdown
[](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
```bash
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](#install) (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
```bash
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](https://github.com/einvoice-dev1/archsteer/issues) with the language,
framework, and smallest reproducible example. Builder feedback directly shapes the
detectors and starter rule packs.