{"id":47596172,"url":"https://github.com/kiloloop/oacp","last_synced_at":"2026-04-26T11:02:55.306Z","repository":{"id":343986512,"uuid":"1179983537","full_name":"kiloloop/oacp","owner":"kiloloop","description":"Coordinate AI agents with human-in-the-loop control — YAML-based protocol, no server, any runtime","archived":false,"fork":false,"pushed_at":"2026-04-17T07:22:10.000Z","size":393,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T09:32:26.240Z","etag":null,"topics":["ai-agents","cli","coordination","developer-tools","llm","llm-agents","multi-agent","protocol","yaml"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kiloloop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-12T15:24:37.000Z","updated_at":"2026-04-17T07:21:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kiloloop/oacp","commit_stats":null,"previous_names":["kiloloop/oacp"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/kiloloop/oacp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiloloop%2Foacp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiloloop%2Foacp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiloloop%2Foacp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiloloop%2Foacp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiloloop","download_url":"https://codeload.github.com/kiloloop/oacp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiloloop%2Foacp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32294592,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","cli","coordination","developer-tools","llm","llm-agents","multi-agent","protocol","yaml"],"created_at":"2026-04-01T18:06:01.399Z","updated_at":"2026-04-26T11:02:55.293Z","avatar_url":"https://github.com/kiloloop.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OACP — Open Agent Coordination Protocol\n\n[![PyPI](https://img.shields.io/pypi/v/oacp-cli)](https://pypi.org/project/oacp-cli/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Claude Code](https://img.shields.io/badge/Runtime-Claude_Code-6B4FBB.svg)](https://claude.ai/code)\n[![Codex](https://img.shields.io/badge/Runtime-Codex-74AA9C.svg)](https://openai.com/index/codex/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-brightgreen)](https://github.com/kiloloop/oacp/pulls)\n\n\u003e **[Try the quickstart →](examples/quickstart/)** — send your first message to an AI agent in 5 minutes.\n\n**Coordinate agents without the chaos.**\n\nA file-based protocol for multi-agent engineering workflows. OACP defines the message formats, review processes, and safety rules that let AI agents on different runtimes collaborate through a shared filesystem. Not a framework or SDK — just conventions, YAML schemas, and scripts that any runtime can implement.\n\n## Quick Start\n\n```bash\npip install oacp-cli\noacp init my-project --agents alice,bob\noacp send my-project --from alice --to bob --type task_request \\\n  --subject \"Implement feature X\" --body \"Details here...\"\n```\n\nWhen running inside a configured agent runtime, `--from` can be omitted — OACP infers the sender from `OACP_AGENT`, `AGENT_NAME`, or the agent card. See [QUICKSTART.md](QUICKSTART.md) for a full walkthrough.\n\n### What you get\n\n- **Inbox/outbox messaging** — async YAML messages with threading, broadcast, and expiry\n- **Structured review loop** — severity-graded findings, quality gates, multi-round review\n- **Inbox CLI** — `oacp inbox` lists pending messages across agents with table or `--json` output\n- **Watch CLI** — `oacp watch` emits inbox delta events for Claude Monitor or shell loops\n- **Durable shared memory** — project facts, decisions, and known debt with active/archive split\n- **Agent safety defaults** — baseline rules for git, credentials, and scope discipline\n- **Runtime-agnostic** — works with any runtime that reads/writes files\n\n## Try It Now\n\nAfter installing, run `oacp doctor` to verify your environment is wired up:\n\n```bash\noacp doctor\n```\n\n## Why OACP?\n\nWhen multiple AI agents work on the same codebase, they need a way to:\n\n- **Communicate** — send task requests, review feedback, and handoffs without shared memory\n- **Review each other's work** — structured review loops with quality gates and severity-based findings\n- **Stay in sync** — durable memory files that persist decisions across sessions and runtimes\n- **Stay safe** — baseline safety rules for git operations, credential scoping, and scope discipline\n\nOACP 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.\n\n## Where OACP Fits\n\nFour protocols are shaping multi-agent development. They solve different problems at different layers:\n\n```\n┌─────────────────────────────────────────────┐\n│  A2A — Agent discovery \u0026 remote messaging   │  internet-scale\n├─────────────────────────────────────────────┤\n│  OACP — Async workflow messaging            │  local filesystem\n├─────────────────────────────────────────────┤\n│  ACP — Client ↔ agent sessions              │  IDE / editor\n├─────────────────────────────────────────────┤\n│  MCP — Agent-to-tool integration            │  tool access\n└─────────────────────────────────────────────┘\n```\n\n**[MCP](https://modelcontextprotocol.io/)** gives agents access to tools and data sources — databases, APIs, file systems. It defines how an agent *calls a tool*.\n\n**[ACP](https://github.com/agentclientprotocol/agent-client-protocol)** (Agent Client Protocol, by Zed Industries) connects clients to coding agents. JSON-RPC, primarily over stdio today. Adopted by Zed, JetBrains, Neovim, and 28+ agents in its registry.\n\n**[A2A](https://github.com/a2aproject/A2A)** lets agents discover and communicate with each other across the internet. HTTP-based, enterprise-grade, backed by 150+ organizations under the Linux Foundation.\n\n**OACP** is the async messaging layer for multi-agent workflows — typed workflow messages (task dispatch, code review, handoff, brainstorm) over persistent transport that survives crashes. Zero infrastructure required.\n\n### How they compare\n\n| | MCP | ACP | A2A | OACP |\n|---|---|---|---|---|\n| **Solves** | Tool access | Client ↔ agent sessions | Agent discovery + networking | Async workflow coordination |\n| **Transport** | JSON-RPC (stdio/HTTP) | JSON-RPC (stdio; HTTP draft) | HTTP/HTTPS | Filesystem (YAML) |\n| **Best for** | Connecting agents to APIs, DBs, files | IDE ↔ coding agent interaction | Cross-org, internet-routable agents | Local teams, dev machines, CI |\n| **Infrastructure** | MCP server per tool | ACP-capable client + agent | TLS, auth, HTTP endpoints | A shared directory |\n| **Offline support** | N/A (synchronous) | N/A (session-based) | Agent must be reachable | Native — messages wait in inbox |\n| **Setup** | Install MCP server | Use ACP-capable client + agent | Deploy servers + networking | `oacp init my-project` |\n\nThese protocols are **complementary, not competing**. An agent can use MCP to access tools, speak ACP for IDE integration, and check OACP inboxes for multi-agent coordination — different layers, no conflict.\n\nA2A connects agents across the internet. OACP coordinates agents on your machine. A gateway between OACP inboxes and A2A endpoints is a natural bridge — and A2A's own community is [exploring inbox patterns](https://github.com/a2aproject/A2A/discussions/792) that validate this design.\n\n## Install\n\n```bash\nuv tool install oacp-cli\n```\n\n```bash\npipx install oacp-cli\n```\n\n```bash\nuvx --from oacp-cli oacp doctor\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eFrom source\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/kiloloop/oacp.git\ncd oacp\nuv tool install .\n```\n\n\u003c/details\u003e\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `oacp init` | Create a project workspace under `$OACP_HOME/projects/` |\n| `oacp add-agent` | Add an agent to an existing project workspace |\n| `oacp setup` | Generate runtime-specific config files (Claude, Codex, etc.) |\n| `oacp send` | Send a protocol-compliant inbox message (`--from` auto-inferred) |\n| `oacp inbox` | List pending messages across agents (table or `--json`) |\n| `oacp watch` | Emit inbox delta events for one agent across selected projects |\n| `oacp memory` | Archive or restore project memory files |\n| `oacp agent` | Manage global agent profiles (`init`, `show`, `list`) |\n| `oacp org-memory` | Initialize org-level memory at `$OACP_HOME/org-memory/` |\n| `oacp write-event` | Write an event to `org-memory/events/` |\n| `oacp doctor` | Check environment and workspace health |\n| `oacp validate` | Validate an inbox/outbox YAML message |\n| `oacp --version` | Print the installed version |\n\n\u003cdetails\u003e\n\u003csummary\u003eKey flags\u003c/summary\u003e\n\n**`oacp send`**: `--in-reply-to`, `--expires`, `--body-file`, `--channel`, `--dry-run`, `--json`, `--quiet`\n\n**`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`, `--since` (default `now`), `--show-archived`\n\n**`oacp doctor`**: `--fix` (auto-fix safe issues), `--json`, `-o/--output`\n\n**`oacp memory`**: `oacp memory archive \u003cproject\u003e \u003cfile\u003e`, `oacp memory restore \u003cproject\u003e \u003cfile\u003e`\n\n\u003c/details\u003e\n\nIf `OACP_HOME` is unset, workspace commands default to `~/oacp`.\n\n## Key Concepts\n\n| Concept | Description |\n|---------|-------------|\n| **Inbox/Outbox** | Async messaging between agents via YAML files in `agents/\u003cname\u003e/inbox/` |\n| **Review Loop** | Structured code review: `review_request` → `review_feedback` → `review_addressed` → `review_lgtm` |\n| **Quality Gate** | Merge-readiness criteria: no unresolved P0/P1 findings, deferred nits tracked |\n| **Durable Memory** | Shared `memory/` directory with an active working set plus `memory/archive/` for historical memory |\n| **Dispatch States** | Task lifecycle: `received` → `accepted` → `working` → `pr_opened` → `in_review` → `done` |\n| **Safety Defaults** | Baseline rules all agents follow: no force push, no secrets in commits, stage hygiene |\n\n## Project Structure\n\n```\noacp/\n├── docs/\n│   ├── protocol/       # Canonical protocol specifications\n│   └── guides/         # Setup, adoption, versioning\n├── scripts/            # Kernel scripts (Python + shell)\n├── templates/          # Packet, role, and guardrail templates\n├── tests/              # Test suite\n├── Makefile            # Task runner (make help for all targets)\n└── SPEC.md             # Full protocol specification\n```\n\n## Related\n\n- **[agent-estimate](https://github.com/kiloloop/agent-estimate)** — Estimate how long agent tasks take. Pairs with OACP dispatch for task sizing.\n\n## Prerequisites\n\n- Python 3.9+\n- Bash 3.2+ (macOS default is fine)\n- `gh` CLI (optional, for GitHub operations)\n\n## Protocol Specification\n\nThe full protocol is documented in [SPEC.md](SPEC.md), covering:\n\n1. **Inbox/Outbox Messaging** — message format, types, lifecycle, threading, broadcast\n2. **Dispatch State Machine** — task lifecycle from delivery to completion\n3. **Review Loop** — packet-based and inbox-based review with quality gates\n4. **Cross-Runtime Sync** — durable memory, handoff context, session init\n5. **Safety Defaults** — git safety, staging hygiene, credential scoping\n\nIndividual protocol specs live in [`docs/protocol/`](docs/protocol/).\n\n## Workspace Layout\n\n`oacp init` creates a project workspace with this structure:\n\n```\n$OACP_HOME/projects/\u003cproject\u003e/\n├── agents/\n│   ├── \u003cagent-a\u003e/\n│   │   ├── inbox/           # Other agents write here\n│   │   ├── outbox/          # Sent messages (copies)\n│   │   └── dead_letter/     # Undeliverable messages\n│   └── \u003cagent-b\u003e/\n│       └── ...\n├── memory/                  # Shared durable memory\n│   ├── project_facts.md\n│   ├── decision_log.md\n│   ├── open_threads.md\n│   ├── known_debt.md\n│   └── archive/\n├── artifacts/               # Build/research artifacts\n├── checkpoints/             # Progress checkpoints\n├── logs/                    # Agent session logs\n├── merges/                  # Merge decision records\n├── packets/                 # Review/findings artifacts\n└── workspace.json           # Project metadata\n```\n\nOptionally, `oacp org-memory init` creates org-level shared memory:\n\n```\n$OACP_HOME/org-memory/\n├── recent.md                # Always-loaded rolling summary\n├── decisions.md             # Org-wide decisions\n├── rules.md                 # Standing conventions\n└── events/                  # Timestamped event entries\n```\n\n## Development\n\n```bash\nmake test\nmake preflight\n```\n\n## Documentation\n\n- [SPEC.md](SPEC.md) — Full protocol specification\n- [examples/quickstart/](examples/quickstart/) — Hands-on tutorial: send a message to an AI agent\n- [QUICKSTART.md](QUICKSTART.md) — CLI reference walkthrough\n- [docs/guides/doctor.md](docs/guides/doctor.md) — Doctor guide: checks, sample output, common fixes\n- [docs/guides/setup.md](docs/guides/setup.md) — Detailed setup guide\n- [docs/guides/adoption.md](docs/guides/adoption.md) — Adoption guide (minimum → full)\n- [docs/protocol/](docs/protocol/) — Individual protocol specs\n- [CONTRIBUTING.md](CONTRIBUTING.md) — How to contribute\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiloloop%2Foacp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiloloop%2Foacp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiloloop%2Foacp/lists"}