OACP

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.

Read the spec →

$ uv tool install oacp-cli

See it in action

The CLI ships structured tasks between agents and lets you watch the conversation in real time.

Live agent fleet

Every multi-agent thread is a sequence of typed messages — review_request, review_feedback, review_addressed, review_lgtm — with explicit quality gates.

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 ✓

Filesystem as protocol

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/.

$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            on demand      [⌘]
  rules.md             12 rules       [⌘]
  decisions.md         org decisions  [⌘]

Want to see these files populated? Browse examples/demo-workspace/ — what a fictional team's project remembers after a month of agent sessions (debt with origins, threads opened and closed, decisions with rationale), plus the org-memory layer mid-curation.

Quick Start

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..."

By default, oacp init my-project creates claude, codex, and cursor agents. Pass --agents to include Gemini or custom agent names.

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.

What you get

• 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 inbox lists pending messages across agents with table or --json output
• Watch CLI — oacp watch emits 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

Coming from claude -p?

claude -p runs an agent synchronously and headless — your script blocks while it works, and there's no session to glance at, attach to, or steer mid-run.

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 the session is right there to watch and steer. Once tasks are messages, review loops, handoffs, and multi-agent coordination come with the shape.

From claude -p to an interactive Claude Code session → — paste-into-your-agent setup, the honest tradeoffs, and where it fits.

Try It Now

After installing, run oacp doctor to verify your environment is wired up:

oacp doctor

Agent Skills

OACP 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:

• https://github.com/kiloloop/oacp-skills

The core oacp-cli package remains the protocol/tooling kernel, while oacp-skills contains runtime guidance and workflows.

Why OACP?

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.

Where OACP Fits

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.

How they compare

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.

Install

uv tool install oacp-cli

pipx install oacp-cli

uvx --from oacp-cli oacp doctor

git clone https://github.com/kiloloop/oacp.git
cd oacp
uv tool install .

Commands

oacp --version prints the installed version.

If OACP_HOME is unset, workspace commands default to ~/oacp.

Key Concepts

Project Structure

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

Related

• agent-estimate — Estimate how long agent tasks take. Pairs with OACP dispatch for task sizing.

Prerequisites

• Python 3.9.2+
• Bash 3.2+ (macOS default is fine)
• gh CLI (optional, for GitHub operations)

Protocol Specification

The full protocol is documented in SPEC.md, covering:

1. Inbox/Outbox Messaging — message format, types, lifecycle, threading, broadcast
2. Dispatch State Machine — task lifecycle from delivery to completion
3. Review Loop — packet-based and inbox-based review with quality gates
4. Cross-Runtime Sync — durable memory, handoff context, session init
5. Safety Defaults — git safety, staging hygiene, credential scoping

Individual protocol specs live in docs/protocol/.

Workspace Layout

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

Org-level shared memory and cross-machine sync are the memory tool's: agent-memory (pip install agent-memory-cli) scaffolds $OACP_HOME/org-memory/ (agent-memory org init), syncs the home (enable, pull, push), checks it (agent-memory doctor), and installs the runtime startup hook (agent-memory setup <runtime>). The layout it implements is the kernel's memory layout spec.

Init loads the four active project memory files. Org memory is retrieved on demand; syncing it to disk does not load it into context. See project context and org-memory retrieval.

Development

make test
make preflight

Documentation

• 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

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

Apache 2.0 — see LICENSE for details.