🧭 compass

Let your coding agent off the leash — not off the rails.

Guardrails, a hard budget cap, and a self-fixing PR loop for your AI coding agent. eval-gated guardrails 100/100 · a budget cap that actually halts · you always merge

🧭  Explore the interactive site →

the guided tour — live demos, clickable architecture, one-click install

compass is a local-first config layer for Claude Code, Codex & Gemini that stops your agent from doing three things it shouldn't — burning your budget, running unsafe commands, and merging unverified code. Set COMPASS_MAX_USD=5 and the session hard-stops at the cap; catastrophic commands are blocked before they run — and the guardrail policy is scored 100/100 in CI against a labeled corpus, not asserted. You install it once, and you always merge.

# no curl|sh, fully reversible — then just open any repo in your agent
git clone https://github.com/dshakes/compass ~/compass && cd ~/compass && ./quickstart.sh
# or, inside Claude Code:   /plugin marketplace add dshakes/compass

⭐ The part people screenshot: it fixes its own PRs.

Open a PR and compass reviews it, security-checks it, runs the tests, cross-audits it with a second model — then pushes its own fixes until it's green. You merge. ☝ That's a real PR — every event above is inspectable.

The idea in one line: the loop is the unit of work. A one-shot agent stops at its first wrong answer. compass loops — generate → test → critique → fix → repeat against a gate — so quality comes from iteration, not one lucky prompt. → how the loop works · the thesis

Why it's different — measured, not vibes

Every AI-agent config claims "safe" and "cheap." compass is the one that hands you the number — and lets a skeptic reproduce it in 30 seconds. Everyone has the same models; the edge is configuration you can trust. Five claims, five commands:

🛡 Guardrails with a score. Catastrophic commands and secret writes are blocked before they run — and the policy is eval-gated in CI, not asserted.

compass bench     # → guardrail 100% precision/recall (61-case corpus), router 96.9% — in CI
# then ask the agent to `rm -rf /` or write a .env → denied; `rm -rf ./build` → allowed

🧪 Red-team resistance, measured. Prompt-injection (direct/indirect/paste), agent-config poisoning, local safety-override, malware & insecure-code — scored against a labeled corpus that gates CI, obfuscation-resistant (--attack), with optional escalation to a managed guardrails backend. A poisoned repo or web page can't quietly turn your agent against you — and you can measure how well that holds.

compass redteam            # → injection corpus 100% P/R (99 cases) + 100% obfuscation-robust, then scans THIS repo's config/MCP/settings
compass redteam --external # → score the detectors against a public corpus we DIDN'T write (honest: 90% precision, and we tell you why recall is what it is)

Most tools show you 100% on their own test set. We show that too — and the number against someone else's corpus, because a floor you can only hit on your own cases isn't a floor.

💸 A budget ceiling that actually stops it. Usage trackers report spend; compass enforces it — the session is halted before the next tool call once your dollar cap is reached. An agent can't quietly run up a $40 bill while you're away.

export COMPASS_MAX_USD=5     # this session hard-stops at $5 — blocked, not warned
compass spend --max-usd 5    # the same ceiling on the ledger, for scheduled / fleet runs

📉 Cost routing that's measured. Cheap work goes to cheap models — ~62% cheaper than all-Opus at 96.9% routing accuracy on the 44-case routing evalset, with the pricing table and token assumptions stated in the output. Run the number, don't take it.

compass route "redesign the auth model"    # → opus
compass route "fix a typo"                 # → haiku
compass bench                              # → routed vs all-Opus: ~62% cheaper (assumptions printed)

🔏 Supply chain you can verify. Releases carry keyless SLSA provenance — a tampered or look-alike download is rejected — and the repo publishes an OpenSSF Scorecard. And before you trust someone else's plugin, scan it.

compass verify                 # resolves the latest release → ✓ provenance verified
compass audit-plugin ./their-marketplace   # injection · tool-poisoning · unpinned MCP · fetch-and-execute hooks — before you install

No service, no telemetry, no --dangerously-skip-permissions; git pull to update. The work it can't safely own, it hands back — you keep the merge.

See it work

The day-to-day feel — guardrails, the cost-aware status line, the loop, and the crew, in ~25 seconds:

How the loop works — review · security · tests · cross-audit run in parallel; Blocking findings get auto-fixed and re-reviewed (round-capped) until green, then it stops at you:

And the everyday status line quietly keeps score, so you watch it earn its keep:

Opus 4.8 · myrepo · main* · 45k ctx · $1.23 · 🧭 🛡1 🧹2 💡1 📉~$1.65

session spend, then today's compass activity: 🛡 footguns blocked · 🧹 files formatted · 💡 policy nudges · 📉~$ estimated saved vs all-Opus. Nothing leaves your machine.

Loops all the way up

Autonomy here isn't one big magic button — it's the same closed loop applied at four scales. Each runs until a gate says "done," then stops at a human. That's the whole trick: iteration under a gate beats a single confident guess.

A loop that runs while you sleep is five moves — discovery → handoff → verification → persistence → scheduling — and compass ships a primitive for each. It also guards the four costs a loop runs up silently (verification debt, comprehension rot, cognitive surrender, token blowout): an independent evaluator that assumes broken and runs it, compass digest to keep you understanding what merged, the permanent human gate, and per-day + live budget caps. → the five moves & four guards · the thesis

Every loop ends the same way — you merge. That gate never moves.

Install

Pick the door that fits — all reversible, version-pinnable, no curl | sh. You need an AI assistant (Claude Code; Codex/Gemini optional) + git. No API keys for the manual, guardrails, crew, and CLI; the autonomous PR loop and fleet need model auth when you opt in.

🍺 Homebrew — managed & versioned

brew install dshakes/tap/compass         # latest release · --HEAD to track main
compass quickstart                       # previews, asks, then wires it into ~/.claude

📦 Git clone — own & edit your config (recommended)

git clone https://github.com/dshakes/compass ~/compass && cd ~/compass
git checkout "$(git describe --tags --abbrev=0)"   # optional: pin to the latest release
./quickstart.sh          # previews every change, asks first, fully reversible

🧩 Claude Code plugin — no terminal (ideal for a team)

/plugin marketplace add dshakes/compass
/plugin install core@compass

🛠️ By hand: make dry-run (preview) → make install → make doctor. → Team rollout

What install actually does: replaces your global ~/.claude config (settings, CLAUDE.md, agents, skills, hooks…) with symlinks into the repo — so git pull/brew upgrade updates everything. Anything it replaces is backed up first to ~/.claude/backups/; --copy copies instead of linking; make uninstall removes only what it added. Personal overrides (your model, plugins, UI prefs) live in claude/settings.local.json — gitignored, deep-merged at install, so your prefs never fight the shipped defaults.

One config, every agent

CLAUDE.md · AGENTS.md · GEMINI.md are one file (symlinks), and the plugin/extension manifests are generated from one source and CI-checked (scripts/check-vendor.sh) — a git pull updates every agent at once and a manifest can't drift. The manifests are structure-validated in CI; the live gemini extensions install / codex plugin marketplace add paths are verified manually (those CLIs aren't in the runner).

Enforcement, not just the manual. Claude Code gets the full hook layer (guardrails, budget gate, scans). For everything else — Codex, Gemini, Cursor, any SDK — the budget cap travels via compass gate, a localhost proxy you point ANTHROPIC_BASE_URL/OPENAI_BASE_URL at, so the hard dollar ceiling holds for any agent, not only the one with hooks. → 02-cost

✅ Verify → your first run

compass doctor      # validate the install — expect "0 error"
compass status      # is compass active here, and what's loaded?

Then open your agent as usual. Feel it in a minute: ask for a dangerous command (blocked), run /review on your diff, or compass route "<task>" to see the tier it picks. No tokens, no signup.

What's in the box

Everything below is on after one install or a single opt-in — the autonomous loops sit on top. Each row links to the detail.

Safety, honesty & status

Built to be trusted before it's run — and honest about its limits.

• You own the irreversible. Agents prepare; humans push, merge, deploy. Required checks + code-owner approval enforce it.
• Readable & reversible. No curl | sh; the installer backs up what it replaces and make uninstall removes only what it added. Pin a tag, not main.
• Guardrails reduce footguns; they are not a security boundary. Keep least-privilege credentials and review your diffs. For untrusted code, compass sandbox is a real boundary. Red-team hardening is defense-in-depth, not immunity — the cardinal rule (external content is data, not instructions) and the human gate are what actually hold.
• What talks to the network. compass phones home to nothing. The pinned MCP servers reach the endpoints you'd expect (library docs, URLs you request); hooks are short, commented shell scripts in claude/hooks/ — disable any in your settings.

Status: beta. The core — manual, hooks, subagents, commands, MCP, plugin — is stable, dogfooded daily, and eval-gated in CI (guardrails + red-team scored on labeled corpora; run compass bench yourself). The SDLC pipeline is newer: statically validated in CI, exercised via a smoke-test you run on your own repo. Managed-guardrail adapters are contract-tested, with live cloud-backend calls unverified in CI (need your creds). Dynamic workflows are a research preview. The human merge/deploy gate is permanent, by design. → full details

Docs

Start here → Using compass — install, the pieces in plain language, the daily workflow. The thesis → Loop engineering — why iteration-under-a-gate beats a one-shot guess. In practice → The five moves — each move of a self-running loop, mapped to the primitive that builds it.

Philosophy · Architecture · Cost & models · Customize · MCP · Plugin & team rollout · LSP · Practices · Defaults · SDLC · Roadmap · Every agent · Workflows · Fleet · Competitive audit · Hardening · Red-team · Benchmark · Provenance · Loops · Run any framework · Agents roster · Router module · ADRs