A vendor-neutral source-of-truth for running multiple AI coding agents on the same workspace — without them stepping on each other or shipping things you didn't approve.
One AGENTS.md. Three autonomy tiers. One hard gate on customer-facing actions. A few shell scripts that survive iCloud and offline. Built and used in production by a solo operator.
Most people running AI agents (Claude Code, Cursor, Cline, Codex CLI, Aider, Goose, Copilot, etc.) hit the same three walls:
- Agents disagree about the workspace. Each tool has its own conventions, scope, commit style. Multi-agent = chaos.
- Agents sprawl. Without explicit per-task scope, every agent thinks the whole repo is fair game and
git statusbecomes a yard sale. - Agents ship things they shouldn't. Either you approve everything (slow) or you approve nothing (risky).
This repo is the contract layer I wrote to solve all three for myself. Every agent reads the same AGENTS.md, classifies its own changes into three tiers, and stays inside the per-task git scope. Customer-facing actions hit a hard gate no matter how confident the agent is.
Three things I haven't seen combined elsewhere:
Agents classify every change by risk × reversibility, not by "what the user told me":
| Tier | Behavior | Triggers |
|---|---|---|
| T1 Auto-Apply | Direct commit | Content output, logs, < 20-line patches, typos |
| T2 Auto + Decision Log | Commit + append reasoning to log.md |
Multi-file changes, rule tuning, batches |
| T3 Queue for Human | Write to _pending/, wait for approval |
Governance docs, schema migrations, anything irreversible |
Result: agents ship the 95% boring stuff without asking, and reliably stop on the 5% that matters.
Anything that affects a customer, public audience, or third-party platform is T3 by default — no matter how confident the agent is.
Outbound email, social post, customer deploy, public push, payment API call, ad-spend trigger — agent prepares the exact artifact, operator approves a named hash, agent executes. "Ship now" does not bypass this gate.
This is the single most important rule in the file. See AGENTS.md §5.5.
Every task tag (feature, outbound, research, whatever yours are) has an explicit allow-list of paths it can stage. Before every commit, the agent constructs:
intended_files: [] # in-scope and actually changed
unexpected_dirty_files: [] # stranded — don't touch, just log
forbidden_files_touched: [] # in-scope but shouldn't be modified — commit blockedNo more git add -A chaos. No more "the agent silently modified my AGENTS.md while it was supposedly editing my README."
.
├── AGENTS.md ← The contract every agent reads first (~450 lines)
├── CLAUDE.md ← symlink → AGENTS.md (for tools that read CLAUDE.md)
├── LICENSE ← MIT
├── .gitignore
└── .sync/
├── sync.sh ← launchd auto-sync: mkdir-lock, rebase-abort, offline-tolerant
├── commit.sh ← manual/agent commit helper at task boundaries
└── migration-scripts/com.example.workspace-sync.plist.tpl
Six files. No framework. No install step. No vendor lock-in.
git clone https://github.com/<you>/solo-agent-ops ~/workspace
cd ~/workspace
# 1. Read AGENTS.md top to bottom. This is the contract.
# 2. Edit §1 (identity), §6.3 (task-tag scope), §9 (preferences) to match your work.
# 3. Copy .sync/migration-scripts/com.example.workspace-sync.plist.tpl to
# ~/Library/LaunchAgents/, edit the {{HOME}} placeholders, then launchctl bootstrap.
# 4. Point your AI tool of choice at this directory.
# Cursor, Cline, Codex CLI, Claude Code, Aider, Goose all work — they read AGENTS.md.The architecture is general; the defaults are mine. Minimum to adapt:
- Identity (
AGENTS.md §1) — replace with your domain - Task tags (
AGENTS.md §6.3) — pick 8-15 that match your work (feature,bugfix,outbound,client-deliverable,research, etc.) - Per-task scope table (
AGENTS.md §6.3) — for each task tag, list the paths it can stage. Tighter is safer. - Tier thresholds (
AGENTS.md §5.2 / §5.3 / §5.4) — start conservative (everything T3), then demote things to T1/T2 after watching them work safely 5-10 times. - External Side-Effect Gate triggers (
AGENTS.md §5.5) — explicitly enumerate. "Customer-facing stuff" is not a gate. "Outbound email, proposal send, calendar invite, public post" is. - launchd plist — replace
{{HOME}}and Label with your username; pick StartInterval 120s (interactive) or 300s (always-on).
Why no docs/adapting-to-your-domain.md? Because the six steps above are the whole adaptation. If you need more, open an issue.
If you're tempted to put ~/workspace/ inside iCloud Drive or any cloud file sync: don't. They will corrupt your .git/objects/ eventually. Cloud file sync clients don't understand git's atomic write patterns; storage-optimization will evict pack files; multi-device race will truncate writes mid-flight.
This repo's two-machine pattern uses git itself as the sync mechanism (via a GitHub remote). The .sync/ scripts make that ~2-min latency without manual intervention. Cheap, robust, no new dependencies.
Follows the emerging AGENTS.md convention (single canonical file all agents read). Works with:
- Read/write: Cursor · Cline · Codex CLI · Claude Code · Aider · Goose · Copilot · self-hosted agents (e.g. Hermes)
- Read-only review/audit: OpenClaw and similar sandboxed reviewers (see
AGENTS.md §4.1) - Any LLM-based agent that respects an
AGENTS.md/CLAUDE.md/.cursorrulesfile
The included CLAUDE.md → AGENTS.md symlink handles tools that look for CLAUDE.md.
- Not a framework or library — nothing to install
- Not an LLM wrapper or orchestrator — your existing agent tools do the LLM calling; this shapes how they behave
- Not opinionated about model or vendor
- Not about RAG or knowledge management — see "What this repo is not (yet)" below
Earlier versions of this system also included hallucination gates (source-required, inline citation, SHA256 reality-sync of source files) and outcome evidence schemas for a knowledge-base layer. Those are a separate concern (grounded retrieval, not multi-agent governance) and may show up as a sister repo. Not in scope here.
- Linter to validate AGENTS.md schema and per-task scope at agent start
- Linux cron equivalent for
.sync/sync.sh - Adapter docs for specific agents (Cursor rules, Cline rules, etc.)
- More worked task-tag/scope examples by archetype (solo dev, consultant, researcher, B2B operator)
Contributions welcome. Open an issue.
- Andrej Karpathy —
AGENTS.md §5.0extends his four coding rules (Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution). The tier system started as "how do I let agents skip rule 1 safely." - Nous Research / Teknium — my always-on agent is named Hermes in homage.
- The AGENTS.md convention community — for converging on a vendor-neutral SOT.
MIT. Use it, fork it, ship it.