AI Agent Collaboration Protocol

What does cokodo-agent do?

cokodo-agent (co) is a CLI + convention directory .agent/ that turns “how AI collaborates, what it remembers, and which rules it codes by” into versionable, syncable, checkable project assets.

| Problem | Approach | |---------|----------| | AI “forgets” every new chat | Single entry point: start-here.md, status.md, MCP for on-demand context | | Each IDE has its own rules | co adapt generates Cursor / Claude / Copilot / Gemini / Codex entry files once; the protocol stays in .agent/ only | | Spec and implementation drift | v1.9+ uses co change to manage “proposal → tasks → archive” under project/changes/, SDD-style like OpenSpec, with co lint checks |

In short: Ship protocol + session state + optional SDD change units inside the repo, wired by Python and co serve; it does not replace the IDE, it fixes “project-level context.”

cokodo-agent vs OpenSpec

The two can be used together; cokodo keeps SDD inside .agent/ and is oriented toward “one repo, one toolchain.”

| Aspect | OpenSpec | cokodo-agent | |--------|----------|--------------| | Focus | Align on “what to build” before coding (change units + living specs) | Align on “who the project is, where it stands” (protocol + cross-session state) | | Changes/workflow | changes/ → propose → apply → archive; slash commands | co change new \| apply \| list \| archive; same model as status.md and MCP | | Living specs | openspec/specs/ as first-class | .agent/project/specs/ + optional merge on archive | | MCP | Officially no MCP | co serve / co serve --workspace; IDE queries context, status, changes | | Protocol upgrade | Manual template follow-up | co diff / co sync; project/ is not overwritten | | Multi-IDE | AGENTS.md + per-IDE slash commands | co adapt cursor\|claude\|copilot\|gemini\|codex\|all | | Runtime | Node.js 20.19+ | Python 3.10+ | | Cross-project | Single-repo oriented | co ref / co collab / global registration |

Relationship: OpenSpec excels at spec and change-unit expression and community workflow; cokodo-agent excels at session continuity, MCP, protocol versioning, and one flow for all IDEs. From v1.9, cokodo includes SDD change units; see OpenSpec comparison research and ADR-009 for tradeoffs. Thanks to OpenSpec (Fission-AI) for the inspiration.

Common scenarios and co commands (concise)

Install and version

pipx install cokodo-agent          # or pip install cokodo-agent
# MCP is included; use co serve for IDE integration
co version

New project setup

cd your-repo
co init                    # interactive: create .agent/
co init -y --tools all     # non-interactive + generate all IDE entry files
# then edit .agent/project/context.md, tech-stack.md

Existing .agent/, only add or refresh IDE entry files

co adapt cursor            # or claude / copilot / gemini / codex / all
co detect                  # see which IDE files already exist in the repo

Align protocol with repo .agent/

co diff                    # compare with remote/bundled protocol
co sync -y                 # upgrade core etc., keep project/
co lint                    # compliance + changes-structure (when using change units)

One feature, spec-driven (SDD)

co change new feature-x           # skeleton: proposal / specs / design / tasks
co change appl

... [View full README on GitHub](https://github.com/dinwind/agent_protocol#readme)