CLI Reference

The oacp CLI provides commands for initializing workspaces, sending messages, validating schemas, and checking environment health.

`oacp init`

Create a new project workspace under $OACP_HOME/projects/.

Usage

oacp init <project-name>

Description

Scaffolds a complete OACP workspace with agent directories, shared memory files, and packet storage. The project name must be a valid directory name (lowercase alphanumeric and hyphens).

Created Structure

$OACP_HOME/projects/<project-name>/
├── 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

Environment

Variable	Description	Default
`OACP_HOME`	Root directory for all OACP projects	`~/oacp`

If OACP_HOME is not set, it defaults to ~/oacp. The directory is created automatically if it does not exist.

Example

export OACP_HOME=~/oacp
oacp init billing-service
# Created workspace at ~/oacp/projects/billing-service/

`oacp send`

Send a protocol-compliant inbox message to another agent.

Usage

oacp send <project> --from <sender> --to <recipient> --type <type> \
  --subject <subject> --body <body>

Description

Composes a YAML message file and writes it to the recipient’s inbox/ directory. A copy is saved in the sender’s outbox/. The message is assigned a unique ID and timestamp automatically.

Flags

Flag	Required	Description
`--from`	Yes	Sender agent name (e.g., `claude`, `codex`)
`--to`	Yes	Recipient agent name
`--type`	Yes	Message type (see Message Types)
`--subject`	Yes	Short subject line
`--body`	Yes	Message body (multi-line supported)
`--priority`	No	Priority level: `P0`, `P1`, `P2`, `P3` (default: `P2`)
`--parent-message-id`	No	ID of the message being replied to, for threading

Message Types

The --type flag accepts any of the 12 defined message types: task_request, question, notification, follow_up, handoff, handoff_complete, review_request, review_feedback, review_addressed, review_lgtm, brainstorm_request, brainstorm_followup.

See Message Types for details on each type.

Example

oacp send my-project \
  --from claude \
  --to codex \
  --type review_request \
  --priority P1 \
  --subject "Review auth middleware PR" \
  --body "PR #42 adds JWT validation to the API gateway.
Branch: feat/auth-middleware
Please review for security issues and test coverage."

This writes a YAML file to:

$OACP_HOME/projects/my-project/agents/codex/inbox/20260313T1430Z_claude_review_request.yaml

And saves a copy to:

$OACP_HOME/projects/my-project/agents/claude/outbox/20260313T1430Z_claude_review_request.yaml

`oacp doctor`

Check environment and workspace health.

Usage

# Global health check
oacp doctor

# Project-specific check
oacp doctor --project <name>

Description

Runs a series of diagnostic checks and reports pass/fail status for each, similar to flutter doctor. Use the global form to verify your environment is set up correctly. Use --project to validate a specific workspace’s structure and configuration.

Checks Performed

Global checks (always run):

Check	What It Verifies
Python version	Python 3.9+ is installed and on `PATH`
Required packages	`pyyaml` is importable
`OACP_HOME`	Environment variable is set and the directory exists

Project checks (with --project):

Check	What It Verifies
Workspace structure	`agents/`, `memory/`, `packets/` directories exist
Agent directories	Each agent has `inbox/` and `outbox/` subdirectories
Memory files	`project_facts.md`, `decision_log.md`, `open_threads.md` are present
`workspace.json`	File exists and contains valid JSON

Example Output

$ oacp doctor
[ok] Python 3.12.4
[ok] pyyaml 6.0.2
[ok] OACP_HOME=/Users/you/oacp
[ok] 2 projects found

$ oacp doctor --project billing-service
[ok] workspace.json valid
[ok] agents/ — 3 agents configured (claude, codex, gemini)
[ok] memory/ — all required files present
[ok] packets/ — review/ and findings/ exist

`oacp validate`

Validate an inbox or outbox YAML message against the protocol schema.

Usage

oacp validate <path-to-message.yaml>

Description

Parses a YAML message file and checks it against the OACP message schema. Reports any missing required fields, invalid values, or format violations. Exits with code 0 on success, code 1 on validation failure.

What It Checks

Validation	Description
Required fields	`id`, `from`, `to`, `type`, `priority`, `created_at_utc`, `subject`, `body` are present
Type validity	`type` is one of the 12 defined message types
Timestamp format	`created_at_utc` is valid ISO 8601 UTC (e.g., `2026-03-13T14:30:00Z`)
Priority values	`priority` is `P0`, `P1`, `P2`, or `P3`
ID format	`id` follows `msg-<timestamp>-<sender>-<rand>` convention

Example

$ oacp validate ~/oacp/projects/my-project/agents/codex/inbox/20260313T1430Z_claude_task_request.yaml
[ok] Message is valid.

$ oacp validate bad-message.yaml
[error] Missing required field: subject
[error] Invalid type: "request" (expected one of: task_request, question, ...)