Skip to content
OACP

What Is OACP? Protocol Overview

OACP (Open Agent Coordination Protocol) is a file-based coordination protocol for multi-agent engineering workflows. It defines the message formats, state machines, review processes, and safety rules that enable AI agents on different runtimes to collaborate asynchronously through a shared filesystem.

OACP is not a framework or SDK. It is a set of conventions, YAML schemas, and shell scripts that any agent runtime can implement.

Why OACP?

Section titled “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.

Core Principles

Section titled “Core Principles”
  • File-based – No daemons or servers. Agents coordinate through structured YAML files on disk.
  • Runtime-agnostic – Works with any agent runtime: Claude Code, Codex CLI, Cursor, Gemini, or your own custom tooling.
  • Human-in-the-loop – Every message, review, and state transition is an inspectable file. Humans retain full visibility and control.
  • Minimal dependencies – Python 3.9+ and PyYAML. No infrastructure to deploy, no services to manage.

Key Concepts

Section titled “Key Concepts”
Concept Description
Inbox/Outbox Async messaging between agents via YAML files in agents/<name>/inbox/. Supports threading, broadcast, and message expiry.
Review Loop Structured code review lifecycle: 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 project facts, decisions, and open threads that persist across sessions. See Shared Memory.
Org Memory Cross-project shared memory at $OACP_HOME/org-memory/ — decisions, rules, and timestamped events readable by every project. See Shared Memory.
Memory Sync Opt-in cross-machine memory sync via a plain git repo at $OACP_HOME (since v0.3.0). See Shared Memory.
Dispatch States Task lifecycle tracking: received → accepted → working → pr_opened → in_review → done.
Safety Defaults Baseline rules all agents follow: no force push, no secrets in commits, staging hygiene, scope discipline.

Project Structure

Section titled “Project Structure”

The OACP repository is organized as follows:

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

Workspace Layout

Section titled “Workspace Layout”

When you initialize a project, OACP creates this structure:

$OACP_HOME/projects/<project>/
├── agents/
│   ├── <agent-a>/
│   │   ├── inbox/          # Other agents write here
│   │   │   └── archive/    # Processed messages (moved at terminal processing)
│   │   ├── outbox/         # Sent messages (copies)
│   │   ├── status.yaml     # Dynamic agent state
│   │   └── agent_card.yaml # Static agent identity
│   └── <agent-b>/
│       └── ...
├── memory/                  # Shared durable memory
│   ├── project_facts.md
│   ├── decision_log.md
│   └── open_threads.md
├── packets/                 # Review/findings artifacts
└── workspace.json           # Project metadata

Agents communicate by writing YAML messages to each other’s inbox/ directories. Shared context lives in memory/, and structured review artifacts go in packets/.

Next Steps

Section titled “Next Steps”