devguard

devguard is an evidence-first engineering workflow (verified-dev) combined with a curated, version-pinned toolkit of token-saving MCP servers and CLI tools. Install it once and share the exact same engineering discipline and tool wiring across Claude Code, VS Code (Copilot), Google Antigravity, Cursor, OpenCode, Codex CLI, and Gemini CLI.

Installation

Quit running instances of Claude Code, VS Code, and Antigravity first (so they do not overwrite their config files on exit), then run:

curl -fsSL https://raw.githubusercontent.com/Burapa-J/devguard/main/bootstrap.sh | bash

irm https://raw.githubusercontent.com/Burapa-J/devguard/main/bootstrap.ps1 | iex

The bootstrap script performs the following idempotent steps:

1. Installs missing prerequisites via Homebrew on macOS, apt-get on Debian/Ubuntu, or winget on Windows (git, jq, python3, node, xcbeautify on macOS, ast-grep, shellcheck).
2. Clones the repository to ~/.local/share/agent-kit/src (or updates an existing clone).
3. Runs ./install.sh (via Git Bash on Windows) with the default setup: global rules, the verified-dev skill, compaction reminder hook, codegraph, projectmem, rtk, and automatic repository indexing under ~/Developer.
4. Ensures ~/.local/bin is on your PATH (including Windows User PATH and .cmd shims for PowerShell/CMD).

Custom Install Options

If you already cloned the repository, run ./install.sh directly or pass flags through bootstrap after bash -s --:

./install.sh --dry-run                                        # Preview changes without modifying any files
./install.sh --with=codegraph,projectmem,rtk,context-mode     # Enable optional context-mode component
./install.sh --targets=claude,vscode,antigravity              # Configure specific agents only
./install.sh --auto-project=~/Developer,~/Work                # Customize auto-indexed directories

Quickstart

After installation, open a new terminal and verify your setup:

devguard status        # View the agent & tool wiring matrix
devguard doctor        # Run all 8 installation health checks
devguard stats         # View token savings, AST graph coverage, and verification pass rates
devguard gate init     # In a repo: write .devguard/checks and install the commit/push gate

1. Working Mode (verified-dev)

Adapted from ideas in Lauren Tan's pstack, Andrej Karpathy's coding guidelines, and Ponytail, the working mode consists of a 9-line always-on block (rules/core.md) and an on-demand skill (skills/verified-dev/SKILL.md):

• Route by task type: Every request routes to one explicit playbook: Investigation, Bug fix, Feature, Refactor, Perf issue, or Prompt / LLM pipeline.
• Read-only on questions & plan reviews: When you ask a question, discuss tradeoffs, or review a plan, the agent stays strictly read-only until you ask to implement.
• No guessing from --help or filenames: Before claiming how a module works or proposing a design, the agent must read the actual implementation source (read/write paths, ID/state lifecycle, ignore/conflict rules) and cite file:line.
• Smallest change & sibling-caller checks: Checks every caller of a modified function via codegraph_explore and fixes the shared path once.
• Runtime evidence required: A successful build is never proof. Every "done" must read .verify/<name>.log and report a one-line verification receipt (command, exit code, key verdict, and log link), pasting verbatim log lines only on failure.
• Source tag on every claim: Each factual claim ends with (read file:line), (ran: command → exit N), (inferred) or (unchecked); evidence is gathered before answering, and a changed answer names the evidence that changed it.
• Pre-mortem before features: A table of what breaks, when, the design that prevents it, and the test that proves it; rows without a test are reported as open risks.
• Prove the test can fail: A new test counts only after it has failed for the right reason (before the fix, or with the guard removed again).
• Done gate: If the repo has .devguard/checks, devguard check must pass before "done", and its git hooks are never bypassed with --no-verify.

2. Components & Companion CLI Tools

All third-party tools are installed directly from upstream at pinned versions. No prompt-modifying local proxies (such as headroom) are used.

Supported Agents & Config Paths

CLI Command Reference

Capturing Verification Evidence (agent-verify)

Because shell compressors like rtk condense stdout, verification commands are run through agent-verify, which writes the complete unfiltered output and exit code to .verify/<name>.log and extracts failing line numbers (errors_at=L...):

agent-verify unit-tests -- swift test
# Output: agent-verify[unit-tests] exit=0 lines=42 log=.verify/unit-tests.log

agent-verify build-check -- xcodebuild test -scheme MyApp -destination 'platform=macOS'
# Output: agent-verify[build-check] exit=65 lines=184 errors_at=L92,L141 log=.verify/build-check.log

Done Gate (.devguard/checks)

Rules ask an agent to verify; the gate checks for it, whatever model wrote the code. Each repo lists its real checks in a committed .devguard/checks, one per line:

commit build:   swift build                                    # every commit: keep it fast
push   test:    swift test                                     # before push: full suites
commit secrets: gitleaks git --staged --redact --no-banner .   # optional: block committed secrets

devguard gate init writes a commented template and installs pre-commit / pre-push hooks; devguard check runs everything by hand. Each check runs through agent-verify, so a failure prints one line and leaves the full log in .verify/gate-<name>.log.

• Never overwrites a hook it did not write (you get the line to add instead); follows linked worktrees and core.hooksPath.
• Lets the commit through with a warning if the kit has moved, so a moved kit cannot block every repo.
• Flags a commit that edits .devguard/checks; a malformed line fails closed with its line number.
• Runs checks with default SIGPIPE and isolated Python, so they behave as in a terminal.
• Known limits: checks see the whole working tree, not only the staged part, and git commit --no-verify still skips them (the core rule forbids it).

Cross-model Review (devguard review)

Models catch different things. devguard review sends the change (uncommitted work including new files, the last commit, or --base REF for a range) to a model from another vendor, read-only, with a fixed rubric: correctness bugs, failure modes, tests that would pass without the change, and claims the code does not back. It prints one line (verdict, finding count, report path) and saves the report to .verify/review-<time>-<reviewer>-<pid>.md.

devguard review --with agy        # Claude wrote it: let Gemini (via Antigravity) review
devguard review --with claude     # Gemini wrote it: let Claude review
devguard review --base main       # review a whole branch

Pick the vendor that did not write the code. Gemini CLI refuses individual accounts, so reach Gemini through agy. Each reviewer CLI must be signed in once in a terminal; a signed-out reviewer gets a clear hint. Treat findings as leads and check each against the code.

Measuring Agents (devguard eval)

A rule change is a claim until it is measured. Cases are JSON lines with a prompt, an expect regex, an optional reject regex and an optional pushback follow-up asked in the same conversation:

devguard eval run .devguard/evals/kit.jsonl --with agy --reps 3 --label before
# ...change a rule...
devguard eval run .devguard/evals/kit.jsonl --with agy --reps 3 --label after
devguard eval compare .verify/eval-before-*.json .verify/eval-after-*.json

Per case it reports first-answer correctness, source tags per answer, and how often the answer flipped under pushback.

Evidence: Does Cross-model Review Help?

Seven commits of this kit were rebuilt as isolated repos and reviewed blind by Claude and Gemini. Against 11 bugs known to be in them, each reviewer found 8/11 and the two together found 10/11; each caught bugs the other missed. A commit assumed clean drew a finding from both that turned out to be a real bug. A diff-based "should I review?" heuristic flagged every code commit, so it was not built. Decision: agents run devguard check on every task and invoke devguard review only when explicitly requested by the user (suggesting it after high-risk changes to persisted data, sync, concurrency, or security). One run per commit and reviewer, 11 bugs from one author: a trend, not a precise rate. Details: docs/experiments/2026-10-30-cross-model-review.md.

Measuring ROI & Workflow Quality (devguard stats)

Run devguard stats to view three real-data telemetry tables across your machine:

╭─ 1. RTK Shell Compression Savings ─────────────────────────────────────────────╮
Total commands:    2446                 Tokens saved:      194.2K (38.6%)
Efficiency meter:  █████████░░░░░░░░░░░░░░░ 38.6%
╰────────────────────────────────────────────────────────────────────────────────╯
╭─ 2. Repositories (CodeGraph & ProjectMem) ─────────────────────────────────────╮
│ Repository                      Files  Symbols    Edges    Fixes Tokens Saved │
├────────────────────────────────────────────────────────────────────────────────┤
│ TOTAL (8 repos)                   655    16207    46092       51       134000 │
╰────────────────────────────────────────────────────────────────────────────────╯
╭─ 3. Verification & Workflow Quality (.verify/*.log) ───────────────────────────╮
│ Repository                   Verifies   Passed   Failed Pass Rate  Lines Saved │
├────────────────────────────────────────────────────────────────────────────────┤
│ TOTAL (5 repos)                   135      127        8       94%        22497 │
╰────────────────────────────────────────────────────────────────────────────────╯

Self-Healing Health Checks (devguard doctor)

devguard doctor audits 8 common configuration problems and repairs them automatically when invoked with --fix:

1. Legacy tokless residue (leftover binaries, ANTHROPIC_BASE_URL proxy env in ~/.claude/settings.json, and .zshrc blocks).
2. Broken or stale symlinks in ~/.local/bin.
3. Conflicting brevity/workflow plugins (caveman, ponytail, cavecrew).
4. MCP server configuration drift across canonical agent files.
5. RTK global plugin & hook registration for Google Antigravity.
6. Synchronization of <!-- agent-kit:begin --> blocks against rules/core.md.
7. Version drift of pinned components and presence of companion tools (ast-grep, xcbeautify, shellcheck).
8. Cross-machine memory sync: the .pth hook loads this kit, the iCloud hub exists, and no projectmem MCP server is still running old sync code (restart your agents; --fix never kills them).

Automatic Repository Setup & Multi-Mac Sync

Every Git repository under ~/Developer (1–2 levels deep) is automatically configured once: .verify/ is appended to .gitignore, codegraph init builds the AST index, and pjm init initializes per-repo memory (verifying config.toml, .git/hooks/post-commit, and registration in ~/.projectmem/projects.json). Setup is triggered via:

• Claude Code SessionStart hook when opening a project in Claude Code.
• zsh chpwd hook when you cd into a repository in any terminal.
• macOS launchd background scan every 30 minutes (covering GUI-cloned repositories in VS Code and Antigravity).

Cross-Machine Memory Sync (iCloud Drive CRDT): When iCloud Drive is signed in, projectmem automatically syncs per-project and global memories across all your Macs via ~/Library/Mobile Documents/com~apple~CloudDocs/devguard-sync/:

• Per-device node files: Each Mac writes only to its own nodes/<device_id>.jsonl, docs/<device_id>-PROJECT_MAP.md, docs/<device_id>-plan.md, and global/nodes/<device_id>.json, preventing iCloud file conflicts (* 2.jsonl).
• Git root commit matching (root-<sha12>): Repositories are matched by their initial Git commit hash so folder names can differ across machines.
• Offline issue_id collision resolution: Concurrent offline issues with the same number are deterministically renumbered with parent_issue_key linkage and .projectmem/.current_issue marker updates.
• Zero-touch real-time hook: A .pth runtime hook inside projectmem-venv syncs automatically on every MCP read/write, complemented by cd, launchd, and devguard sync. Writes to events.jsonl take a shared lock, so an event appended while a sync runs is never lost.
• Is it synced? devguard sync --check compares every Mac's node file per project and names any Mac that is missing events; devguard status shows the totals. A repo with no commit and no remote is not synced until its first commit, so two unrelated repos with the same folder name never merge.

Uninstalling

Every modified file is backed up to ~/.agent-kit-backup/<timestamp>/ (automatically retaining the 10 newest snapshots) before editing, and uninstalling restores your original files byte-for-byte:

devguard uninstall --dry-run     # Preview what will be removed
devguard uninstall               # Remove rules, skills, hooks, and MCP wiring (keep tool CLIs)
devguard uninstall --purge       # Also uninstall tool CLIs that devguard installed