🧭 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}

_{Real session, no edits: the cost climbs to $0.35, then the next action is HALTED at the $0.05 cap — before it spends more.}

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

🌐 Site  ·  Why it's different  ·  The self-fixing PR loop  ·  Loops  ·  Install  ·  What's in the box  ·  📚 Docs

---

⭐ 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 two more models — three cross-model gates (Claude review · Codex audit · Gemini audit) — 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 bench corpus; a separate 147-case bypass corpus gates CI), router 96.9%
# 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:

_{Run it locally in 30s with ~/compass/sdlc/orchestrate.sh "<task>" (no tokens), or wire the GitHub loop for every PR. → how it works · reproduce it}

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 five 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.

	Loop	What it drives	Where it stops
🔁	The task loop	generate → test → critique → fix → repeat — one change driven to green	when tests + review pass
🔎	The review loop	review → auto-fix the Blocking findings → re-review, round-capped (×3)	hands off to a human if still red
🩺	The CI-fix loop	any check suite goes red → failure log + auto-fix on the PR; main goes red → one free rerun, then a ci-fix/* PR	round cap → a human; never merges
🛰️	The fleet loop	the whole pipeline, scheduled across every repo you own, overnight, test-gated	a PR per repo, approve from your phone
👥	The workflow loops	parallel agents that fan out, fact-check each other, and converge	one synthesized answer

The newest turn of the crank — pr-shepherd: every open PR taken end-to-end — diagnose the red check from its log, classify it, fix + verify the mechanical ones, and stop at a merge gate that's enforced server-side (required checks + ruleset, not the agent's honor). Run it on demand (/pr-shepherd), on an interval (/loop 15m /pr-shepherd), or unattended: compass schedule add pr-shepherd --twice-daily.

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 compass@compass

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

🚀 Put your other repos on it — one command each (or a list):

compass enable --schedule owner/repo ~/code/another-repo   # config + PR gates + secrets-from-env
                                                           # + required-checks ruleset + auto-merge
                                                           # + twice-daily pr-shepherd (--dry-run to preview)

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

Agent	Native install (no terminal)	or own the files
Claude Code	/plugin marketplace add dshakes/compass → /plugin install compass@compass	make install
Codex	codex plugin marketplace add dshakes/compass → /plugin install	make install (~/.codex/AGENTS.md + config.toml)
Gemini CLI	gemini extensions install https://github.com/dshakes/compass	./install.sh --gemini (~/.gemini/GEMINI.md)
Cursor · Copilot · OpenCode · Windsurf	read the repo's AGENTS.md (AGENTS.md standard)	clone + make install

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.

	Capability	One line	Deep dive
🔁	Autonomous SDLC	the review → security → tests → cross-audit → auto-fix → re-review loop; you merge	09-sdlc
🩺	CI auto-fix	no CI failure goes unhandled: red PR checks feed the fix loop; red main gets one free rerun, then a ci-fix/* PR	09-sdlc
🔄	Loop engineering	the five moves wired up: morning-triage discovery · pr-shepherd takes every open PR to the merge gate (on demand, /loop 15m /pr-shepherd, or compass schedule add pr-shepherd --twice-daily unattended) · an acting/skeptic evaluator · compass digest · per-day budget cap	20-loops
🛰️	The fleet	the loop, scheduled across all your repos through a test gate; approve from your phone	14-fleet
👥	The crew + workflows	cost-tiered expert subagents · slash-commands · dynamic workflows that fact-check each other	agents roster · 12 · 13
🛡	Guardrails & scanning	a hook layer that blocks disasters, catches secrets (write-hook + compass scan), auto-formats, keeps a JSONL audit log	16-hardening
🧪	Red-team hardening	eval-gated defense vs prompt-injection, config poisoning, safety-override, malware & insecure code	17-red-team
🧭	Cost-tier router	a standalone, reusable module — keyword heuristic → optional classifier → judge cascade; eval-gated	router/
🧰	The compass CLI	onboard · impact · drift · scan · redteam · audit-plugin · gate · sandbox · verify · audit-log · spend · dashboard	11-using
🚦	Cross-agent enforcement	compass gate — a localhost proxy that hard-caps spend for Codex/Gemini/any SDK, not just Claude Code	02-cost
🔍	Plugin-security scanner	compass audit-plugin — vet a third-party plugin/marketplace (injection · tool-poisoning · unpinned MCP · fetch-exec) before you install it	17-red-team
🔌	MCP + LSP	curated, version-pinned MCP servers + opt-in language-server intelligence	04 · 06
🪪	Every agent, one source	Claude Code · Codex · Gemini — plus Cursor/Windsurf/Copilot via the AGENTS.md standard	12-every-agent
💸	Live budget ceiling	a hard cap that halts the session before the next tool call (COMPASS_MAX_USD), plus a per-day cap for unattended loops	02-cost

---

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. Fundamentals → The layers — prompt/context/harness/loop/graph, dated and evidence-graded, with a rubric for the next one. Fundamentals → Context — the context window as a budget you spend, not a container you fill. Fundamentals → Harness — everything around the model that isn't the model, and the evidence it moves outcomes more than the model does. Fundamentals → The gate — a loop without a gate is just an agent talking to itself; generator vs. evaluator, and what makes a gate real vs. asserted. Fundamentals → Verification — the ladder of what counts as proof, from "the model said so" to a human watching it run. Fundamentals → Orchestration — when fan-out earns its cost, the Cognition/Anthropic disagreement, and graph engineering graded honestly. Fundamentals → Ablation — make every config rule defend itself with a number, or admit your corpus never tested it. Fundamentals → Glossary — every term from this series, alphabetized and graded, so you can look one up mid-sentence.

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 · The layers · Context · Harness · The gate · Verification · Orchestration · Ablation · Glossary · Agents roster · Router module · ADRs

_{MIT · built to be shared · contributions welcome}