Your first X-ray in under a minute
ArchSteer is a local-first CLI (Python 3.10+). It reads your code statically — it never executes it — and writes everything into a local .archsteer/ folder.
1. Install (Python 3.10+ required)
Recommended — pipx installs the CLI in its own isolated environment and always uses a modern Python:
brew install pipx # macOS — or: python3 -m pip install --user pipxpipx install archsteerarchsteer version # → ArchSteer 0.1.0
If pipx defaults to an older Python, pin a 3.10+ one:pipx install --python python3.11 archsteer
Prefer no extra tools? Use a virtual environment with Python 3.10+:
python3.11 -m venv ~/.archsteer-env~/.archsteer-env/bin/pip install archsteer~/.archsteer-env/bin/archsteer version
Troubleshooting
No matching distribution found for archsteer/Requires-Python >=3.10— yourpip/pip3is tied to Python 3.9 or older. Check withpython3 --version; install with pipx or a 3.11 venv (above).zsh: command not found: pip— usepip3orpython3 -m pipinstead.archsteer: command not foundafter pipx — runpipx ensurepathand restart your terminal.externally-managed-environment— don'tpip installinto Homebrew Python directly; use pipx or a venv.
No native toolchain needed — the engine runs on a regex parser, with optional tree-sitter acceleration via pipx install archsteer[treesitter].
2. X-ray any repo (zero config)
cd your-repoarchsteer xray # map + living docs + evolution + report
Open .archsteer/report.html for the live map, drift, and what changed. No rules required — this is the read-only X-ray. See it on a sample repo →
3. Govern & steer your agents
archsteer init # declare intent in architecture.yamlarchsteer steer -f src/api/payments.ts # guardrails into CLAUDE.md / AGENTS.md / .cursor/rulesarchsteer baseline # accept existing debt (the ratchet)archsteer check # fail only on NET-NEW violations
Now agents build toward your target architecture instead of copying adjacent legacy code, and CI blocks regressions without freezing features.
4. Report to the situation room
archsteer push --token $ARCHSTEER_TOKEN # send a snapshot to your org dashboard
Watch org-wide conformance and the Drift Index in the situation room.
5. Gate it in CI
Add an architecture gate to every PR — block net-new violations, draft ADRs for new decisions:
# .github/workflows/archsteer.yml- run: pip install archsteer- run: archsteer map && archsteer adr && archsteer check
That's the whole loop
X-ray → govern → steer → check → push. Read the thinking behind it in the whitepaper.