multiagent-protocol

Self-built branch protection and decision routing for solo developers and small teams who use multiple AI coding agents (Claude Code, Codex, Cursor, Gemini-CLI, …) on the same GitHub repositories.

One human, many agents. Different sessions, different machines, different models — same main branch. This protocol stops them from stepping on each other, gates merges through a self-built check, and routes irreversible decisions back to you instead of letting agents decide.

v1.5.0. The cron orchestrator is live: your private installation evaluates open PRs, merges the auto-approvable quadrants (A/B/C), routes irreversible+critical changes (D) to you via the Decision Inbox, and audits main (L2 + L5). Installation is delegated — hand docs/agent-setup/AGENT_SETUP.md to your own AI agent. New in 1.5: exact-object declared-state completion subreceipts and a fail-closed version-contract downgrade guard. These receipts verify Git-bound declarations; they do not claim live deployment causality. See the version-truth guide and STATUS.md.

---

What problem does this solve?

If you are a single developer using two or more AI coding agents to work on the same GitHub repository, you have probably hit at least one of these:

1. Concurrent edits collide. Agent A is editing app/auth.py while Agent B (on a different machine, different model) is editing the same file. Nobody noticed; you spend an hour reconciling.
2. An agent silently merges something irreversible. A model "fixed a flaky test" by deleting the test. The commit was already on main before you saw it.
3. You cannot tell who did what. Three commits land overnight, signed Claude / Codex / Cursor, but you cannot see which session was responsible or what reasoning each used.
4. GitHub Free has no branch protection on private repos. You want "required status checks" + "merge only via bot" but cannot pay for GitHub Pro, or do not want to make the repo public.

multiagent-protocol is a portable, vendor-neutral, self-built equivalent of branch protection that runs entirely from your own GitHub account on the Free tier. It enforces:

• Pre-merge gate (L1) — 5 conditions a PR must satisfy before it can merge (label, CI green, owner approval or auto-approval per classifier, base up-to-date, identity trailers present). Wired end-to-end in v0.2.0: C1 verifies the label was applied by an allowlisted actor (timeline), C3 owner-approval reads the live classifier verdict, and the cron loop merges / opens an inbox issue / comments accordingly.
• Post-merge re-validation (L2) — required checks rerun on the merged commit; infrastructure-only failures (cancelled / never-run) are ignored. Implemented as detection + incident in v0.2.0; automatic revert-PR creation is a documented follow-up (see STATUS.md).
• Race-guard (L3) — re-check the PR's base against main HEAD just before merge; the merge_pr call passes a sha precondition GitHub enforces server-side, and a stale base triggers an update-branch rebase. Implemented.
• Identity gate (L4) — validate every commit's Agent-* / Task-Ref trailers against your registry. Trailer-format (C5) is implemented; registry tool/model lookup ships advisory (P2) in v0.2.0 — promote to a hard block via severity_overrides. The 60-day burn-in is later.
• Break-glass auditor (L5) — scan main for [break-glass-*] commits and require an ADR within 24 hours. Implemented, including the 24-hour ADR deadline check (v0.2.0).

The protocol is split into a small bot (Python, ~3 kLOC, plug-in extensible) and a doctrine layer (Markdown files that an agent reads at session start). The bot runs as a GitHub App on a cron you size to your Actions budget — */30 by default on GitHub Actions Free, */5 on a self-hosted runner (the honest arithmetic is in the quick start, step 3).

Why "multiagent" rather than "Claude" / "Codex" / etc.?

The protocol is intentionally vendor-neutral. It treats every agent as one of:

• claude-code, codex, cursor, gemini-cli, aider, <anything else you register>

Identity is enforced through commit trailers, not API endpoints, so adding a new agent vendor takes a one-line registry update (config/agent_registry.yml). No agent has special status; all are equally untrusted-by-default.

What this is NOT

• Not a CI/CD system. Bring your own tests; the bot reads CI status from GitHub.
• Not a code reviewer. It routes PRs to you or to an auto-approval classifier; it does not opine on diff quality.
• Not a replacement for branch protection on GitHub Pro. If you can pay, GitHub's built-in protection is simpler. This is for people on the Free tier or with reasons to self-build.
• Not a multi-tenant SaaS. Each owner runs their own copy. No accounts, no servers (the optional web wizard is a static site that runs in your browser).

Framework vs. your config

This repo is the framework — shared, public, generic. Your config (identity, repo list, agent registry, custom skills) is a separate private data layer under config/. The product = framework + your config; there is no "public version" and "my version" of the code, only different config. The web wizard generates your config layer for you. See docs/concepts/configuration-model.md.

Quick start

The recommended path is delegated installation — your own AI agent sets everything up:

This is the beginning of the README. Read the rest at the original. Read the full README ↗