devguard

An evidence-first working mode (poteto / pstack style) plus token-saving tools (tokless style), installed once and shared across Claude Code, VS Code (Copilot), Antigravity, OpenCode, Cursor, Codex CLI, and Gemini CLI.

Two layers:

• Working mode (always installed): rules and a skill that control how the agent works. It picks a playbook, names the data shape, verifies on the real surface, and never calls something "done" without evidence.
• Components (opt-in, pinned versions): third-party tools installed from their upstream projects and wired into each agent. They replace a tokless-style bundle with only the parts you choose. No prompt proxy (headroom) is included.

What's inside

Path	Kind	Loaded
rules/core.md	Always-on instruction (9 lines)	Every prompt, via each agent's global rules file
skills/verified-dev/SKILL.md	On-demand instruction	When the agent matches it, or you type /verified-dev
bin/devguard → devguard	CLI & interactive menu	Manage setup, status, doctor, stats, updates (update / upgrade), and project init
bin/doctor.sh → devguard doctor	Health & repair tool	Audits 8 failure modes (legacy tokless, symlinks, conflicting plugins, MCP drift, RTK hooks/plugin, rules sync, version drift, memory sync) and repairs them with --fix
bin/stats.sh → devguard stats	Telemetry & quality summary	Shows RTK shell savings, ProjectMem fixes/tokens, CodeGraph index counts, and .verify/*.log verification pass rates
bin/pjm_sync.py → devguard sync	Multi-Mac memory sync	Real-time & batch CRDT sync of projectmem across machines over iCloud Drive
bin/verify.sh → agent-verify	Verification harness	Captures full output + exit code into .verify/<name>.log and reports error line numbers (errors_at=L...) for compiler, test, Python traceback/exception, and Rust panic lines
bin/gate.sh → devguard check / devguard gate	Done gate	Runs a repo's .devguard/checks (commit, push, or all) and installs pre-commit / pre-push hooks that block on failure
bin/review.sh → devguard review	Cross-model review	Sends the change to another vendor's CLI (claude, agy, gemini) in read-only plan mode; report in .verify/review-*.md
bin/eval.py → devguard eval	Agent rule evaluation	Runs .jsonl eval cases (with pushback flip & source-tag scoring) against agy or claude and compares before/after runs
bin/project.sh → devguard-project	Per-repo setup tool	Runs codegraph init, pjm init, and .gitignore setup per repository
hooks/remind.sh	Mechanism (Claude Code, opt-in)	After context compaction, reminds the agent to re-load verified-dev and resume from the task list, projectmem, and git status -sb
components/*.sh	Installers	Install, upgrade, wire, unwire and remove each tool

Components

Component	What it does	Installed from	Wired as	Default
codegraph	Code graph search (codegraph_explore); supports Swift and ObjC	npm @colbymchenry/codegraph@1.6.2	Its own codegraph install (MCP + marked CLAUDE.md section + prompt hook); telemetry turned off	on
projectmem	Per-project & global memory (issues, attempts, fixes, decisions) with real-time iCloud Drive CRDT sync	PyPI projectmem==0.3.5 in its own venv (~/.local/share/agent-kit/projectmem-venv)	One global MCP server for all projects + .pth real-time sync hook	on
rtk	Compresses shell output before the agent reads it	Homebrew rtk (macOS) or GitHub release binary (Linux / Windows) (1.2.0+)	rtk init -g (per-agent flags)	on
context-mode	Sandboxed execution + indexed search	npm context-mode@2.1.7 (Node ≥ 22.5)	MCP only, no hooks	off

Companion CLI Tools (installed by bootstrap.sh / devguard update)

Tool	What it does	Installed from
ast-grep	Tree-sitter structural search & refactoring (ast-grep run -p '<pattern>' -l swift)	Homebrew ast-grep
xcbeautify	Condenses xcodebuild build/test logs into clean summaries (also used by rtk for Xcode output)	Homebrew xcbeautify
shellcheck	Static analysis for shell scripts; this kit runs it in its own commit gate	Homebrew shellcheck
osv-scanner	Scans dependency lockfiles for known vulnerabilities (OSV database); devguard gate init adds it as a self-skipping push deps: check when a lockfile is present	Homebrew osv-scanner
gitleaks	Scans staged changes for secrets; devguard gate init adds it as a self-skipping commit secrets: check	Homebrew gitleaks

rtk compresses routine shell output while verified-dev captures full verification logs into .verify/<name>.log via agent-verify and reads them with the file-read tool, so failing lines are never lost.

Install

One command on a new machine (quit Claude Code, VS Code and Antigravity first):

macOS / Linux:

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

Windows (PowerShell):

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

(If the repository is still private on your account, run gh api -H 'Accept: application/vnd.github.raw' repos/Burapa-J/devguard/contents/bootstrap.sh | bash instead.)

It installs missing prerequisites (brew on macOS, apt-get on Debian/Ubuntu, or winget on Windows), clones the kit to ~/.local/share/agent-kit/src (or reuses an existing clone), and runs install.sh (via Git Bash on Windows) with the recommended defaults:

• rules and skill for all three agents
• the compaction hook
• codegraph, projectmem and rtk
• automatic setup of every git repository under ~/Developer

Then open a new terminal, restart your agents, and run devguard status.

Already cloned? Run ./install.sh. Options (all optional): --with=LIST, --auto-project=DIRS|none, --targets=LIST, --no-hooks, --dry-run. See ./install.sh --help. To pass them through bootstrap, use ... | bash -s -- --with=codegraph,projectmem,rtk,context-mode.

Everyday commands

devguard                 # interactive menu (status, select tools, doctor, stats, update, uninstall)
devguard status          # compact overview table of what is installed, wired and set up
devguard doctor [--fix]  # audit 8 common failure modes and optionally repair them automatically
devguard stats           # unified token savings, codegraph index & verification pass-rate stats
devguard sync [--quiet]  # sync projectmem across machines over iCloud Drive (CRDT merge)
devguard sync --check    # read-only: per project, do all Macs hold the same events?
devguard check [commit]  # run this repo's .devguard/checks (`commit` for fast inner loop, default `all`)
devguard gate init       # write a checks template and install the git hooks
devguard review          # another model reviews uncommitted changes (or the last commit)
devguard eval ...        # run/compare agent rule evaluations against .devguard/evals/kit.jsonl
devguard select          # interactively pick agents and tools to enable/disable
devguard update          # (or: devguard upgrade) pull the latest kit, upgrade tools and re-apply settings
devguard init [--all]    # set up this repo now, or every repo under your auto-setup folders
devguard skip            # never set up this repo automatically
devguard disable         # interactive uninstall / unwire (or: devguard uninstall [--purge])

Done gate (.devguard/checks)

Rules and skills 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

devguard gate init also writes two security checks that each self-skip (with a one-line install hint) when their tool is absent, so a fresh clone never fails the gate on them: commit secrets: runs gitleaks on staged content and blocks the commit on a secret, and push deps: runs osv-scanner on dependency lockfiles (when one is present) and blocks the push on a known vulnerability. Both tools are installed by bootstrap.sh and refreshed by devguard update (Homebrew; on Linux/Windows install them yourself and the checks start working).

devguard gate init auto-detects the repo's stack (Package.swift, Cargo.toml, package.json, *.py, *.sh) to write runnable checks (falling back to a commented template in empty repos) and installs pre-commit / pre-push hooks; devguard check runs everything by hand (devguard check commit for the fast inner loop), and the core rule tells agents to run it before calling a task done. Each check runs through agent-verify, so a failure prints one line and leaves the full log in .verify/gate-<name>.log.

Safety: the hooks are only written where no hook exists or ours does (a foreign hook is left alone and you get the line to add), they follow linked worktrees and core.hooksPath, they let the commit through with a warning if the kit has moved, and a commit that edits .devguard/checks is flagged for review. Known limits: checks run on the working tree, not only the staged part, and git commit --no-verify still skips them.

Cross-model review (devguard review)

Models catch different things. devguard review sends the current change to a model from another vendor and saves its findings to .verify/review-<time>.md, printing one line: verdict, finding count, report path. It reviews uncommitted changes, or the last commit when the tree is clean, or --base REF for a range. The reviewer runs read-only (claude --permission-mode plan, agy --mode plan, gemini --approval-mode plan) inside the repo so it can open files for context. Pick it with --with claude|agy|gemini or DEVGUARD_REVIEWER; the default is the first installed of claude, agy, gemini. Use the vendor that did not write the code. Gemini CLI refuses individual accounts, so reach Gemini through agy (Antigravity). Treat findings as leads: check each against the code before acting.

Measured on this kit: seven commits reviewed blind by both vendors against 11 bugs; each found 8/11, together 10/11, while a rules/docs-only commit produced 0 findings from Gemini and 4 debatable remarks from Claude (at 49–610 s per run). So: agents run devguard check on every task and invoke devguard review only when explicitly requested by the user (suggesting it in the report for high-risk changes — persisted data/migrations, cross-device sync, concurrency/locking, or security/keychain — rather than calling another vendor's CLI automatically). Details and limits: docs/experiments/2026-10-30-cross-model-review.md.

Measuring an agent (devguard eval)

A rule change is a claim until it is measured. devguard eval run CASES.jsonl --with agy|claude --reps N --label L asks each case N times in read-only plan mode and records, per case, whether the first answer matched expect (and not reject), how many source tags it carried, and, for cases with a pushback follow-up asked in the same conversation, whether the answer flipped. Results: .verify/eval-<label>-<time>.json; devguard eval compare before.json after.json prints the per-case change. A/B a rule: run with label before, change the rule, run with label after, compare. This kit's own cases are in .devguard/evals/kit.jsonl.

Automatic project setup

Each repository under your auto-setup folders (default ~/Developer, 1–2 levels deep) is set up once: .verify/ goes into .gitignore, then codegraph init and pjm init run. It is triggered three ways, so every agent is covered:

Trigger	Covers
Claude Code session start (hook)	Claude Code
cd into a repo in zsh	every agent's integrated terminal, and yours
launchd scan every 30 min and at login (macOS)	everything, including repos cloned from a GUI

Setup runs in the background, ready repos are skipped instantly, and logs go to ~/.agent-kit/logs/. Repositories outside the folders are never touched, and a .agent-kit-skip file opts one out (the kit's own repo has one).

Unlike tokless, pjm init writes into each project: it installs git hooks, verifies config.toml and ~/.projectmem/projects.json registration, and adds a "projectmem bridge" section to the project's CLAUDE.md and AGENTS.md. That is why setup is limited to your own folders.

Cross-machine memory sync (iCloud Drive)

When iCloud Drive is signed in, projectmem automatically syncs project and global memories across all your Macs via ~/Library/Mobile Documents/com~apple~CloudDocs/devguard-sync/ using an append-only CRDT merge (bin/pjm_sync.py):

• Conflict-free per-device 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, avoiding iCloud events 2.jsonl conflict copies.
• Git root commit matching (root-<sha12>): Repositories are matched across Macs by their initial Git commit SHA even if folder names differ. A repo with no commit falls back to its remote URL; with neither it is not synced until its first commit, because a folder name alone (two unrelated test repos) would merge unrelated memory.
• 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 sync: A .pth runtime hook inside projectmem-venv syncs automatically on every MCP read/write, complemented by cd, launchd, and devguard sync.
• Is it synced? devguard sync --check compares every Mac's node file per project: in-sync, diverged (a Mac lacks events another has: still travelling through iCloud, or that Mac has not synced since; it names the Mac and how many events) single (only one Mac has written) or incomplete (a node file is still an iCloud placeholder, not downloaded). devguard status shows the totals.

Coming from tokless / caveman / ponytail

Remove legacy tools first so hooks and plugins aren't wired twice: tokless uninstall, or simply run devguard doctor --fix after installing devguard to automatically clean up leftover tokless blocks, broken symlinks, and conflicting caveman / ponytail / cavecrew plugins.

Where things go

Agent	Rules block	Skill link	MCP config
Claude Code	~/.claude/CLAUDE.md	~/.claude/skills/verified-dev	~/.claude.json
VS Code / Copilot	~/.copilot/copilot-instructions.md	reads ~/.claude/skills (or ~/.copilot/skills if Claude Code is not a target)	~/Library/Application Support/Code/User/mcp.json (macOS), %APPDATA%/Code/User/mcp.json (Windows), ~/.config/Code/User/mcp.json (Linux)
Antigravity	~/.gemini/GEMINI.md	~/.gemini/config/skills/verified-dev, ~/.gemini/antigravity-cli/skills/verified-dev	~/.gemini/config/mcp_config.json
OpenCode	~/.config/opencode/AGENTS.md	~/.config/opencode/skills/verified-dev	~/.config/opencode/opencode.jsonc
Cursor	~/.cursor/rules/devguard.mdc	~/.cursor/skills/verified-dev	~/.cursor/mcp.json
Codex CLI	~/.codex/AGENTS.md	~/.codex/skills/verified-dev	~/.codex/config.toml
Gemini CLI	~/.gemini/GEMINI.md	~/.gemini/skills/verified-dev	~/.gemini/settings.json

Uninstall

devguard uninstall --dry-run
devguard uninstall            # remove rules, skill, hooks, zsh block, launchd agent and component wiring; keep tool CLIs
devguard uninstall --purge    # also remove tool CLIs that devguard installed

--purge never removes a CLI you installed yourself. devguard records ownership in ~/.agent-kit/ and keeps that record after a plain uninstall, so a later --purge still works.

Left in place on purpose, because they are the tools' own data: ~/.codegraph/, ~/.projectmem/ and per-project .codegraph/ / .projectmem/. Remove per project with codegraph uninit and pjm hooks uninstall.

Verify after installing

1. Run devguard status and devguard doctor. Every core line should say ok, each enabled component should be wired for your agents, and devguard doctor should report 0 issues (if not, run devguard doctor --fix).
2. Open a new session in each agent and ask: "What rules are you following for code tasks?" It should stay read-only, mention verified-dev, and cite runtime evidence requirements.
3. Ask it to fix a bug that has a failing test. The reply should include a compact summary and a one-line verification receipt (agent-verify log path, exit code, and key verdict), pasting raw log lines only for failures.

If step 3 comes back without evidence, an always-on rule from another setup is probably winning. See section 9 of the skill.

Testing the kit itself

devguard check                  # runs all 7 checks: syntax, shellcheck, gate, review, eval, kit, components
bash tests/test-kit.sh          # core: install / reinstall / uninstall / agent-verify
bash tests/test-components.sh   # components, doctor, and iCloud CRDT sync with stub CLIs (no downloads)

Both run against a throwaway HOME and check that user content survives and that uninstall restores every file byte-for-byte. Needs jq and git.

Known limits

• VS Code reads ~/.copilot/copilot-instructions.md for the Copilot harness. Confirm your VS Code version picks it up by asking the agent what rules it has.
• Agent hooks (agent-kit's own) are installed for Claude Code only, because VS Code hooks are in preview and Antigravity IDE hooks are not reliably documented yet. Automatic project setup still covers those agents through zsh and launchd.
• launchd is macOS only. On Linux the zsh hook and the Claude Code hook still work.
• rtk has no documented unwire for Copilot. Uninstall warns you to remove its hook by hand.
• codegraph unwire is all-or-nothing upstream. Uninstall removes codegraph from every agent at once.

Customize for your stack

The workflow (sections 1, 2 and 4-9 of the skill) is stack-neutral. Section 3's verification table is written for Swift/macOS; replace its rows with your stack's real surfaces. To add a component, copy components/context-mode.sh, implement the same functions, and add its name to ALL_COMPONENTS in components/common.sh.

ภาษาไทย (สรุป)

คู่มือใช้งานฉบับเต็มภาษาไทย: docs/USAGE.th.md · รายการตรวจสอบอัปเดตจากต้นทาง (Upstream Radar): docs/UPSTREAM-RADAR.md

devguard มี 2 ชั้น

• วิธีทำงาน (ติดตั้งเสมอ): rules และ skill ที่บังคับให้ agent เลือก playbook ตามประเภทงาน, กำหนด data shape ก่อนเขียนโค้ด, verify บนของจริง และห้ามบอกว่าเสร็จถ้าไม่มีหลักฐาน
• Components (เลือกได้): เครื่องมือของคนอื่นที่ติดตั้งจาก upstream โดยตรงแบบ pin version แล้ว wire เข้าแต่ละ agent ให้ ค่าเริ่มต้นคือ codegraph + projectmem + rtk ส่วน context-mode ต้องเลือกเอง และไม่มี headroom

ติดตั้งคำสั่งเดียวด้วย bootstrap (ดูส่วน Install) หรือรัน ./install.sh ใน repo ที่ clone ไว้ ค่าเริ่มต้นตั้งค่าทุก repo ใน ~/Developer ให้อัตโนมัติ ผ่าน Claude Code, การ cd ใน zsh และการสแกนของ launchd ทุก 30 นาที

ใช้งานผ่านคำสั่ง devguard เช่น status, doctor [--fix], stats, sync [--quiet], check [commit|push], review, eval, select, update (หรือ upgrade), init [--all], skip และ uninstall [--purge] ความจำของ projectmem จะซิงค์ข้ามเครื่องผ่าน iCloud Drive แบบ CRDT อัตโนมัติ (จับคู่โปรเจกต์ด้วย Git root commit SHA แม้ชื่อโฟลเดอร์ต่างกัน) และไฟล์ที่ถูกแก้จะ backup ไว้ที่ ~/.agent-kit-backup/ (เก็บล่าสุดสูงสุด 10 ชุด) ถ้าเคยใช้ tokless หรือปลั๊กอิน caveman/ponytail ให้รัน devguard doctor --fix เพื่อเก็บกวาดคราบเก่าอัตโนมัติ

Credits

The verified-dev workflow adapts ideas from pstack by Lauren Tan (@poteto), MIT licensed. Components install and wire third-party tools from their own projects: codegraph, projectmem, rtk, context-mode. No third-party code is vendored. See NOTICE.