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/
│   │   │   └── archive/
│   │   ├── outbox/
│   │   └── dead_letter/
│   ├── codex/
│   │   └── ...
│   └── cursor/
│       └── ...
├── memory/
│   ├── project_facts.md
│   ├── decision_log.md
│   ├── open_threads.md
│   ├── known_debt.md
│   └── archive/
├── packets/
│   ├── review/
│   └── findings/
├── merges/
└── workspace.json

Each agent gets its own inbox/ (where it receives messages), an inbox/archive/ (processed messages move there at terminal processing), and an outbox/ (copies of messages it has sent). The memory/ directory holds shared project context that persists across sessions. known_debt.md tracks verified technical debt, and memory/archive/ stores older memory files that are no longer in the active working set.

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.

Tip: You can generate these config snippets automatically with oacp setup claude --project my-first-project. See CLI Reference.

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

Tip: 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 CLI Reference for details.

6. Check the Inbox

Use oacp inbox to see pending messages:

oacp inbox my-first-project --agent codex

INBOX: codex (my-first-project) — 1 message

| # | From   | Type         | Priority | Subject                   | Age |
|---|--------|--------------|----------|---------------------------|-----|
| 1 | claude | task_request | P2       | Implement login endpoint  | 2m  |

You can also read the raw YAML directly:

id: "msg-20260311120000-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-20260311120000-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.
• Agent profiles — define agent identity and capabilities with oacp agent. See CLI Reference.
• Watch the inbox — emit notification-friendly delta events with oacp watch — designed for Claude Monitor or shell loops.
• Memory management — archive and restore memory files with oacp memory. See CLI Reference.
• Cross-machine memory sync — opt in to git-based sync with oacp memory init so the same $OACP_HOME/org-memory/ and per-project memory follows you across machines (since v0.3.0).
• 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.
• Changelog — see what’s new in each release on the Changelog.