The check as a gate
Run archboard check where you already run tsc, ruff and your tests. It fails while the map and the code disagree, in a Git hook, in CI and in an agent's loop.
On this page
A rule in AGENTS.md is a request. An agent can ignore it. A check that fails the build is a fact that the agent must deal with. archboard check is deterministic: the same model and the same code give the same answer, with an exit code that CI understands.
The relay example: the check passes, fails on a call that the model does not draw, and passes again. A real recording of the published CLI.
What passes and what fails#
archboard check runs three checks in order: semantics, code, then embeds. It exits 1 while one of them has something that you must fix.
| Outcome | Exit | Example |
|---|---|---|
| Nothing to report | 0 | A model that matches its code |
| Information only | 0 | A relationship whose evidence is a candidate, matched by name only |
| A code warning | 1 | RELATIONSHIP_UNDRAWN: code calls a module that the model does not join |
| A semantic diagnostic | 1 | RELATIONSHIP_ON_CONTAINER: a line that ends on a module with parts |
| An outdated picture | 1 | EMBED_OUTDATED: a tracked SVG that no longer matches the model |
| No vault in the checkout | 0, or 1 when an embed warns | Only the embeds check runs, and a skip says that the others did not |
| A usage error, or no checkout | 2 | Outside any Git checkout, with no vault above it |
| No server | 3 | The server did not answer and could not start |
Information and skips print on standard error and never change the exit status. Check findings lists every code. Each check also runs alone:
archboard check semanticsarchboard check codearchboard check embedsRead a failure#
A warning of the code check names its code, the file of the module in the vault, the module and what to do. Each piece of evidence follows on its own line, with its kind, whether it is resolved, and its file and line:
warning: RELATIONSHIP_UNDRAWN: ZvzEpjXR.module.json: module "Rate card": The code of "Accept parcel" reaches "Rate card". No relationship joins these modules. Add the relationship between the parts that make and answer the call. If this dependency is unintended, change the code. configured-path, resolved, services/intake/src/accept.ts:51 configured-path, resolved, deploy/kubernetes/peer-endpoints.yaml:13There are two fixes, and the finding says both. If the call is intended, the agent draws the relationship. If it is not, the agent changes the code. Either way the next check passes. The JSON answer on standard output carries the same findings for a script.
In a Git hook#
A pre-push hook keeps a failing map off the remote. Save this as .githooks/pre-push and make it executable:
#!/bin/sh# Block the push while the architecture check fails.# Skip it once with: git push --no-verifyarchboard check > /dev/nullPoint Git at the directory once per clone:
chmod +x .githooks/pre-pushgit config core.hooksPath .githooksIn a Node.js repository, pin the CLI as a dev dependency and let npm install set the hook path for every clone:
{ "scripts": { "prepare": "test -e .git && git config core.hooksPath .githooks || true" }, "devDependencies": { "archboard": "0.5.0" }}For this setup, replace archboard check in .githooks/pre-push with ./node_modules/.bin/archboard check. The hook then runs the pinned program, the same one that CI runs. A pre-commit hook works the same way, but a full check on every commit is slow on a large repository. Push is the better moment.
In CI#
The check Action installs the CLI, runs archboard check, and turns each finding into an annotation on the pull request’s diff. It fails the job on a warning or a diagnostic:
name: architectureon: pull_request: push: branches: [main]
permissions: contents: read
jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - uses: actions/setup-node@v5 with: node-version: 22 # The checkout's own TypeScript is the default TypeScript server. - run: npm ci # A server for each other language in .archboard/language-servers.json. - run: pip install pyright - uses: miklschmidt/archboard/actions/check@30d365ca9caab6dad98f45568a50a890c9f105f9 # v0.5.0 with: version: "0.5.0"The code check resolves a name only through a language server, and only resolved evidence makes a warning. So install the dependencies first. npm ci installs the checkout’s own TypeScript, which serves from version 7. Before 7, the check also needs typescript-language-server in the dev dependencies. Install the server of each other language that .archboard/language-servers.json names, as pip install pyright does for Python. Without a server, a call that needs resolved evidence stays information, and the gate passes.
Pin version to the release that your team runs, as you pin your compiler. Without it, the Action installs the CLI of the release that it comes from. The examples pin the Action to the commit of v0.5.0, with the tag in a comment. A tag can move, and a commit cannot, so pin any third-party Action this way. The Actions reference lists every input: fail-on: never reports findings without failing, though a checkout without a vault still fails, and allow-codes keeps chosen findings visible without failing on them.
Any other CI runs the same command. The exit code is the gate:
architecture: image: node:22 script: - npm ci - npm install --global archboard@0.5.0 - archboard check > check.json artifacts: when: always paths: [check.json]In an agent’s loop#
Give the check’s words back to the agent before a person reviews the work. The agent then fixes the map or the code while it still holds the context. Three ways work today.
Claude Code: a hook when it stops#
A Stop hook runs when Claude Code wants to finish. When the hook ends with status 2, Claude Code gives the hook’s standard error back to Claude, and Claude goes on working:
{ "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "archboard check > /dev/null 2> /tmp/archboard-check.log || { cat /tmp/archboard-check.log >&2; exit 2; }" } ] } ] }}Any agent: a loop in the shell#
Run the agent, run the check, and give the findings back until the check passes or the rounds run out:
#!/usr/bin/env bash# Ask the agent for a change, then hold it to the architecture check.set -utask="$1"codex exec "$task"for round in 0 1 2 3; do if archboard check > /dev/null 2> check.log; then echo "archboard check passed after round $round" exit 0 fi if [ "$round" -eq 3 ]; then break fi codex exec "archboard check failed. Fix the code or the Archboard model so that it passes. Do not hide a finding. The findings:$(cat check.log)"doneecho "archboard check still fails after 3 rounds" >&2exit 1In the instructions of the repository#
Tell the agent where the gate is, so it runs the check before it says it is done:
Run `archboard check` before you finish. It fails while the architecture model and the codedisagree. Fix the code or the model. Never silence a finding.An instruction alone is a request, so keep the hook or the loop as the gate.
Keep the pictures current#
Pictures in your README and ADRs are embeds: SVG or PNG files that Archboard drew and Git tracks. The embeds check fails when one no longer matches the model. Draw them again and commit them:
archboard check embeds --fixgit add docs/architecture