Archkeel

Architecture checks for coding agents.

Python 3.11+ CI PyPI MIT

Archkeel checks code against declared boundaries. It reports forbidden imports, misplaced types and gaps in static analysis, with source evidence for review.

Use it in your coding-agent harness or CI. Checks run locally and deterministically, without an LLM. They complement tests of runtime behavior.

Explore observed code, declared architecture and their differences in one offline report.

Start here

Requires Python 3.11+ and a Git repository with at least one commit. Run Archkeel with a Python version that meets your project's requirements.

uv tool install archkeel
archkeel skill install codex    # or claude

Then ask your coding agent:

Set up Archkeel for this repository. Read the architecture documents,
propose the boundaries, and let me decide which dependencies are allowed.

The skill guides the setup. init drafts components and interfaces; you decide the target architecture. Existing imports are evidence, not permission. You can delegate decisions to the agent, but its authorship is recorded separately. See the onboarding guide for setup and plugin installation.

For an existing setup:

archkeel report      # inspect code and evidence
archkeel validate    # check the contract

report writes architecture.json and an offline architecture.report.html. Read the verdicts: a report can exit 0 with failed or undecided rules. validate checks the contract; check also compares a submitted change with its published expectation. Use archkeel <command> --help for command options.

Review the evidence

Use the report to inspect findings and source locations, then explore the components. Filters narrow the view without changing the verdicts.

archkeel report --only violations --component store
archkeel report --only calls --component store

Agents start with a focused architecture summary, then query the recorded snapshot:

archkeel report --only architecture --json
archkeel report --input test-artifacts/architecture/architecture.json --only architecture --json

Use --component with an id or scope from the summary, and --only violations for findings. Saved queries do not rescan or change the repository. See focused agent reports.

The explorer shows As-Is (observed code), Target (declared architecture), and Diff (their differences). These are views of one snapshot, not two revisions. Folders help navigation; they do not establish ownership or runtime behavior.

PASS means the required rules have complete evidence and no decided violation. UNKNOWN means evidence is missing. A rule can fail and still have undecided positions. A clean graph does not prove a good design.

Catch changes that finding diffs miss

This change adds no forbidden import or cycle, but makes a call harder to resolve:

 def run(key: str) -> int:
-    return first() + second()
+    handlers = {"first": first, "second": second}
+    return handlers[key]()

In Fixture A, resolved calls drop from 2 of 2 to 0 of 1. New finding fingerprints stay at zero. Archkeel rejects the candidate because unresolved calls increase from 0 to 1.

check compares the accepted and candidate commits, checks the contract, and verifies the candidate against an expectation published before submission. Publication order needs trusted host records. A local replay checks supplied records without authenticating them. The reference explains the commit protocol and its limits.

Keep a target the code has not reached

Record existing violations, review the file, then reject new ones in CI:

archkeel validate --baseline known-violations.json --write-baseline
archkeel validate --baseline known-violations.json

Known violations remain FAIL. After fixing them, rewrite the baseline in the same change. New or increased violations require explicit --accept-new; do not use it to hide a regression. See the target-first guide for the full workflow.

Try a reproducible example

git clone https://github.com/rapiddweller/archkeel.git
cd archkeel
make demo
make demo-onboarding

make demo rejects a coverage regression and a late expectation, then shows a passing candidate. make demo-onboarding replays setup on a two-level shop using committed decision fixtures; it performs no live approvals. More cases are in the demo catalog.

Scope and limits

Archkeel observes static source in configured roots. Python support covers imports, calls, and declared boundaries; Dart and TypeScript support imports. TypeScript roots may name files or directories. Archkeel does not prove runtime behavior, performance, or the quality of every design decision. Separate test trees need their own scan and contract.

Exit meanings are defined per command.

Details: rules · known limits · command reference · roadmap.

Development

make check              # lint, types, tests
make gate               # also build, isolated installs and self-validation
make browser-install
make report-browser OUTPUT=test-artifacts/report-browser

Archkeel checks its own architecture contract and compares fresh observations with fixtures/D-self. See CONTRIBUTING.md.