Coordinate agents without the chaos.
A file-based protocol for multi-agent AI workflows. Two pillars — cross-agent communication and persistent shared memory. Across runtimes, projects, and machines. No daemons. No central server. Just files.
$ uv tool install oacp-cli
The CLI ships structured tasks between agents and lets you watch the conversation in real time.
Every multi-agent thread is a sequence of typed messages — review_request, review_feedback, review_addressed, review_lgtm — with explicit quality gates.
Text version (terminal browsing / grep / a11y)
PROJECT · my-app ● live
C claude code drafting PR #42
X codex cli reviewing
G gemini api idle
claude → review_request "auth refactor" [codex]
codex → review_feedback 2 minor, 0 blocking [claude]
claude → review_addressed [codex]
codex → review_lgtm [merge]
thread #42 · 4 msgs · 8m quality gate ✓
Everything is plain files in $OACP_HOME. Agents have inbox/, outbox/, dead_letter/. Projects have shared memory/ (durable) and per-thread artifacts/, checkpoints/, packets/. Org-wide knowledge lives in $OACP_HOME/org-memory/.
Text version (terminal browsing / grep / a11y)
$OACP_HOME/projects/my-app/ ● writing
agents/
claude/
inbox/ 3 msgs [in]
outbox/ 12 sent [out]
dead_letter/ empty [dl]
codex/
inbox/ +1 new [in]
memory/ shared durable
project_facts.md 2.4 kb [md]
decision_log.md edited 3s ago [md]
open_threads.md 1.1 kb [md]
known_debt.md 812 b [md]
artifacts/ build · research
checkpoints/ progress
packets/ review findings
workspace.json metadata [json]
$OACP_HOME/org-memory/ org-wide
recent.md auto-loaded [⌘]
rules.md 12 rules [⌘]
decisions.md org decisions [⌘]
uv tool install oacp-cli
oacp init my-project --agents alice,bob
oacp send my-project --from alice --to bob --type task_request \
--subject "Implement feature X" --body "Details here..."When running inside a configured agent runtime, --from can be omitted — OACP infers the sender from OACP_AGENT, AGENT_NAME, or the agent card. See QUICKSTART.md for a full walkthrough. Or try the 5-minute quickstart → to send your first message to a real AI agent.
- Inbox/outbox messaging — async YAML messages with threading, broadcast, and expiry
- Structured review loop — severity-graded findings, quality gates, multi-round review
- Inbox CLI —
oacp inboxlists pending messages across agents with table or--jsonoutput - Watch CLI —
oacp watchemits inbox delta events for Claude Monitor or shell loops - Durable shared memory — project facts, decisions, and known debt with active/archive split
- Agent safety defaults — baseline rules for git, credentials, and scope discipline
- Runtime-agnostic — works with any runtime that reads/writes files
claude -p runs an agent synchronously and headless — your script blocks while it works, and as of June 15 programmatic usage draws from a separate metered credit.
OACP routes the same work to a standing interactive Claude Code session instead: oacp send queues the task, the session picks it up and runs it async, you're not blocked — and because it's a real interactive session, it stays on your subscription.
From claude -p to an interactive Claude Code session → — paste-into-your-agent setup, the honest tradeoffs, and where it fits.
After installing, run oacp doctor to verify your environment is wired up:
oacp doctorOACP has companion agent skills that teach Claude, Codex, and other runtimes how to use the CLI and protocol in real workflows.
Install or browse them here:
The core oacp-cli package remains the protocol/tooling kernel,
while oacp-skills contains runtime guidance and workflows.
When multiple AI agents work on the same codebase, they need a way to:
- Communicate — send task requests, review feedback, and handoffs without shared memory
- Review each other's work — structured review loops with quality gates and severity-based findings
- Stay in sync — durable memory files that persist decisions across sessions and runtimes
- Stay safe — baseline safety rules for git operations, credential scoping, and scope discipline
OACP solves this with a filesystem-based protocol that requires no server, no database, and no vendor lock-in. Agents read and write YAML files in a shared directory — that's it.
Four protocols are shaping multi-agent development. They solve different problems at different layers:
┌─────────────────────────────────────────────┐
│ A2A — Agent discovery & remote messaging │ internet-scale
├─────────────────────────────────────────────┤
│ OACP — Async workflow messaging │ local filesystem
├─────────────────────────────────────────────┤
│ ACP — Client ↔ agent sessions │ IDE / editor
├─────────────────────────────────────────────┤
│ MCP — Agent-to-tool integration │ tool access
└─────────────────────────────────────────────┘
MCP gives agents access to tools and data sources — databases, APIs, file systems. It defines how an agent calls a tool.
ACP (Agent Client Protocol, by Zed Industries) connects clients to coding agents. JSON-RPC, primarily over stdio today. Adopted by Zed, JetBrains, Neovim, and 28+ agents in its registry.
A2A lets agents discover and communicate with each other across the internet. HTTP-based, enterprise-grade, backed by 150+ organizations under the Linux Foundation.
OACP is the async messaging layer for multi-agent workflows — typed workflow messages (task dispatch, code review, handoff, brainstorm) over persistent transport that survives crashes. Zero infrastructure required.
| MCP | ACP | A2A | OACP | |
|---|---|---|---|---|
| Solves | Tool access | Client ↔ agent sessions | Agent discovery + networking | Async workflow coordination |
| Transport | JSON-RPC (stdio/HTTP) | JSON-RPC (stdio; HTTP draft) | HTTP/HTTPS | Filesystem (YAML) |
| Best for | Connecting agents to APIs, DBs, files | IDE ↔ coding agent interaction | Cross-org, internet-routable agents | Local teams, dev machines, CI |
| Infrastructure | MCP server per tool | ACP-capable client + agent | TLS, auth, HTTP endpoints | A shared directory |
| Offline support | N/A (synchronous) | N/A (session-based) | Agent must be reachable | Native — messages wait in inbox |
| Setup | Install MCP server | Use ACP-capable client + agent | Deploy servers + networking | oacp init my-project |
These protocols are complementary, not competing. An agent can use MCP to access tools, speak ACP for IDE integration, and check OACP inboxes for multi-agent coordination — different layers, no conflict.
A2A connects agents across the internet. OACP coordinates agents on your machine. A gateway between OACP inboxes and A2A endpoints is a natural bridge — and A2A's own community is exploring inbox patterns that validate this design.
uv tool install oacp-clipipx install oacp-cliuvx --from oacp-cli oacp doctorFrom source
git clone https://github.com/kiloloop/oacp.git
cd oacp
uv tool install .| Command | Description |
|---|---|
oacp init |
Create a project workspace under $OACP_HOME/projects/ |
oacp add-agent |
Add an agent to an existing project workspace |
oacp setup |
Generate runtime-specific config files (Claude, Codex, etc.) |
oacp send |
Send a protocol-compliant inbox message (--from auto-inferred) |
oacp inbox |
List pending messages across agents (table or --json) |
oacp watch |
Emit inbox delta events for one agent across selected projects |
oacp memory |
Archive, restore, or git-sync project/org memory files |
oacp agent |
Manage global agent profiles (init, show, list) |
oacp org-memory |
Initialize org-level memory at $OACP_HOME/org-memory/ |
oacp write-event |
Write an event to org-memory/events/ |
oacp doctor |
Check environment and workspace health |
oacp validate |
Validate an inbox/outbox YAML message |
oacp --version |
Print the installed version |
Key flags
oacp send: --in-reply-to, --expires, --body-file, --channel, --dry-run, --json, --quiet
oacp watch: --agent, repeatable --project, --all-projects, --json, --since (default now), --show-archived
oacp doctor: --fix (auto-fix safe issues), --memory, --json, -o/--output
oacp memory: init [--remote URL], clone <URL> [--force], pull, push, disable, archive <project> <file>, restore <project> <file>
If OACP_HOME is unset, workspace commands default to ~/oacp.
| Concept | Description |
|---|---|
| Inbox/Outbox | Async messaging between agents via YAML files in agents/<name>/inbox/ |
| Review Loop | Structured code review: review_request → review_feedback → review_addressed → review_lgtm |
| Quality Gate | Merge-readiness criteria: no unresolved P0/P1 findings, deferred nits tracked |
| Durable Memory | Shared memory/ directory with an active working set plus memory/archive/ for historical memory; optional $OACP_HOME git sync tracks only org-memory/** and projects/*/memory/** |
| Dispatch States | Task lifecycle: received → accepted → working → pr_opened → in_review → done |
| Safety Defaults | Baseline rules all agents follow: no force push, no secrets in commits, stage hygiene |
oacp/
├── docs/
│ ├── protocol/ # Canonical protocol specifications
│ └── guides/ # Setup, adoption, versioning
├── scripts/ # Kernel scripts (Python + shell)
├── templates/ # Packet, role, and guardrail templates
├── tests/ # Test suite
├── Makefile # Task runner (make help for all targets)
└── SPEC.md # Full protocol specification
- agent-estimate — Estimate how long agent tasks take. Pairs with OACP dispatch for task sizing.
- Python 3.9+
- Bash 3.2+ (macOS default is fine)
ghCLI (optional, for GitHub operations)
The full protocol is documented in SPEC.md, covering:
- Inbox/Outbox Messaging — message format, types, lifecycle, threading, broadcast
- Dispatch State Machine — task lifecycle from delivery to completion
- Review Loop — packet-based and inbox-based review with quality gates
- Cross-Runtime Sync — durable memory, handoff context, session init
- Safety Defaults — git safety, staging hygiene, credential scoping
Individual protocol specs live in docs/protocol/.
oacp init creates a project workspace with this structure:
$OACP_HOME/projects/<project>/
├── agents/
│ ├── <agent-a>/
│ │ ├── inbox/ # Other agents write here
│ │ ├── outbox/ # Sent messages (copies)
│ │ └── dead_letter/ # Undeliverable messages
│ └── <agent-b>/
│ └── ...
├── memory/ # Shared durable memory
│ ├── project_facts.md
│ ├── decision_log.md
│ ├── open_threads.md
│ ├── known_debt.md
│ └── archive/
├── artifacts/ # Build/research artifacts
├── checkpoints/ # Progress checkpoints
├── logs/ # Agent session logs
├── merges/ # Merge decision records
├── packets/ # Review/findings artifacts
└── workspace.json # Project metadata
Optionally, oacp org-memory init creates org-level shared memory:
$OACP_HOME/org-memory/
├── recent.md # Always-loaded rolling summary
├── decisions.md # Org-wide decisions
├── rules.md # Standing conventions
└── events/ # Timestamped event entries
make test
make preflight- SPEC.md — Full protocol specification
- examples/quickstart/ — Hands-on tutorial: send a message to an AI agent
- QUICKSTART.md — CLI reference walkthrough
- docs/guides/doctor.md — Doctor guide: checks, sample output, common fixes
- docs/guides/setup.md — Detailed setup guide
- docs/guides/adoption.md — Adoption guide (minimum → full)
- docs/protocol/ — Individual protocol specs
- CONTRIBUTING.md — How to contribute
We welcome contributions! See CONTRIBUTING.md for guidelines.
Apache 2.0 — see LICENSE for details.