Skip to content
OACP

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, 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”
ConceptDescription
Inbox/OutboxAsync messaging between agents via YAML files in agents/<name>/inbox/. Supports threading, broadcast, and message expiry.
Review LoopStructured code review lifecycle: review_request → review_feedback → review_addressed → review_lgtm.
Quality GateMerge-readiness criteria: no unresolved P0/P1 findings, deferred nits tracked.
Durable MemoryShared memory/ directory with project facts, decisions, and open threads that persist across sessions.
Dispatch StatesTask lifecycle tracking: received → accepted → working → pr_opened → in_review → done.
Safety DefaultsBaseline 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
│   │   ├── 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”