Quick Start

Get from zero to your first agent-to-agent message in 5 minutes.

1. Set Up OACP Home

The OACP home directory is where all project workspaces, agent inboxes, and shared memory live.

export OACP_HOME="$HOME/oacp"
mkdir -p "$OACP_HOME"

Add export OACP_HOME="$HOME/oacp" to your shell profile (.bashrc, .zshrc) so it persists across sessions. If OACP_HOME is unset, the CLI defaults to ~/oacp.

2. Install the CLI

uv tool install oacp-cli

Or with pipx:

pipx install oacp-cli

See Installation for other install methods.

3. Initialize a Project

Every project gets its own workspace with agent inboxes, shared memory, and packet directories.

oacp init my-first-project

This creates the following structure:

$OACP_HOME/projects/my-first-project/
├── agents/
│   ├── claude/
│   │   ├── inbox/
│   │   └── outbox/
│   ├── codex/
│   │   ├── inbox/
│   │   └── outbox/
│   └── gemini/
│       ├── inbox/
│       └── outbox/
├── memory/
│   ├── project_facts.md
│   ├── decision_log.md
│   └── open_threads.md
├── packets/
│   ├── review/
│   └── findings/
├── merges/
└── workspace.json

Each agent gets its own inbox/ (where it receives messages) and outbox/ (copies of messages it has sent). The memory/ directory holds shared project context that persists across sessions.

4. Connect Your Runtime

Tell your agent runtime where the OACP workspace lives.

Claude Code — add the workspace path to your project’s CLAUDE.md:

## OACP
OACP workspace: $OACP_HOME/projects/my-first-project/
Check inbox: ls $OACP_HOME/projects/my-first-project/agents/claude/inbox/

Codex — add the workspace path to your repo’s AGENTS.md:

## OACP
OACP workspace: $OACP_HOME/projects/my-first-project/

Other runtimes — point your agent’s system prompt at the workspace path and instruct it to read memory/project_facts.md at session start. Any agent that can read and write files can participate in the protocol.

5. Send a Message

Send a task request from one agent to another:

oacp send my-first-project \
  --from claude --to codex \
  --type task_request \
  --priority P2 \
  --subject "Implement login endpoint" \
  --body "Add POST /login with JWT auth. See docs/api-spec.md for details."

This writes a YAML file to agents/codex/inbox/ and a copy to agents/claude/outbox/.

6. Check the Inbox

See what messages are waiting for an agent:

ls "$OACP_HOME/projects/my-first-project/agents/codex/inbox/"

Read the message:

cat "$OACP_HOME/projects/my-first-project/agents/codex/inbox/"*.yaml

You will see something like:

id: "msg-20260311T120000Z-claude-a1b2"
from: "claude"
to: "codex"
type: "task_request"
priority: "P2"
created_at_utc: "2026-03-11T12:00:00Z"
subject: "Implement login endpoint"
body: |
  Add POST /login with JWT auth. See docs/api-spec.md for details.

7. Reply to a Message

Send a response back, linking it to the original message with --parent-message-id:

oacp send my-first-project \
  --from codex --to claude \
  --type notification \
  --subject "Re: Implement login endpoint" \
  --body "Accepted. Starting implementation on branch codex/login-endpoint." \
  --parent-message-id "msg-20260311T120000Z-claude-a1b2"

Threading via parent-message-id lets agents (and humans) follow conversation history across multiple exchanges.

8. Validate Messages

Check that a message follows the OACP protocol schema:

oacp validate \
  "$OACP_HOME/projects/my-first-project/agents/codex/inbox/"*.yaml

Validation catches missing required fields, invalid message types, and schema violations before they cause problems downstream.

9. Run Health Checks

Verify your environment and workspace are set up correctly:

oacp doctor

To check a specific project workspace:

oacp doctor --project my-first-project

oacp doctor verifies Python version, required packages, directory structure, file permissions, and workspace integrity.

What’s Next?

You now have a working OACP workspace with two agents exchanging messages. From here:

Review loop — set up structured code review between agents. See the protocol docs on review loops.
Durable memory — learn how agents share knowledge across sessions via the memory/ directory.
Safety defaults — understand the baseline safety rules that all agents should follow.
Full specification — read the complete protocol specification on GitHub.