cokodo-agent

Cokodo Agent

A CLI tool and MCP server for the AI Agent Collaboration Protocol (.agent). Generate, lint, sync, and serve standardized project context to any MCP-compatible IDE.

Similar to create-react-app, this tool helps you quickly set up an .agent directory with best practices for AI-assisted development.

v1.9.0+ adds spec-driven change units under .agent/project/changes/ (co change new | list | status), aligned with the planning workflow popularized by OpenSpec (proposal / specs / design / tasks). We are grateful to the OpenSpec project for the inspiration; our implementation stays Python-native and integrated with MCP and session state (status.md). See the main repo README and .agent/project/research/openspec-analysis.md for the full rationale.

v1.11.0+ (protocol 3.3.0) adds Agent Git/PR collaboration templates: project/AGENT-GIT-PR-WORKFLOW.md and project/sop/agent-git-pr-collaboration.md (PR tracks, journal.d workflow, merge gates). Run co scaffold -y on existing projects and co adapt all to refresh IDE rules. See docs/usage-guide.md § Agent Git and PR collaboration.

Installation

# Default install (CLI + MCP server support)
pip install cokodo-agent

# With network fetch (GitHub release). Omit for offline-only use.
pip install cokodo-agent[network]

# Or use pipx (recommended)
pipx install cokodo-agent
pipx install "cokodo-agent[network]"   # if you need co init to fetch from GitHub

Dependencies: Default install includes MCP support for co serve. It does not include httpx; use co init --offline or install with [network] to fetch the latest protocol from GitHub.

Quick Start

# Navigate to your project
cd my-project

# Run the generator (any of these commands work)
co init           # Short alias
cokodo init       # Full name
cokodo-agent init # Package name

# Or specify a path
co init ./new-project

Usage

Interactive Mode (Default)

$ co init

  Cokodo Agent v1.9.14
  ====================

  Fetching protocol...
    OK Protocol v3.0.0

? Project name: my-awesome-app
? Brief description: A task management web application

? Primary tech stack:
  > Python
    Rust
    Qt/C++
    Mixed
    Other

? AI tools to configure (at least one required):
  [x] Cokodo (Protocol Only)    # Default - only .agent/
  [ ] Cursor
  [ ] GitHub Copilot
  [ ] Claude Projects
  [ ] Gemini Code Assist

  Generating .agent/
  OK Created .agent/

  Success! Created .agent in /path/to/my-awesome-app

  Next steps:
    1. Review .agent/project/context.md
    2. Start coding with AI assistance!

Quick Mode

# Use defaults, skip prompts (Cokodo mode - protocol only)
co init --yes

# Specify options directly
co init --name "my-app" --stack python -y

Commands

Command	Description
co init [path]	Create .agent in target directory
co adapt <cursor|claude|copilot|cline|gemini|codex|all> [path]	Generate IDE entry files from existing .agent
co mcp snippet cline [path]	Show Cline MCP snippet path (--show prints JSON)
co mcp install cline [path]	Merge cokodo-agent into Cline MCP settings (--dry-run, --target, -y)
co detect [path]	Detect IDE instruction files (read-only)
co import [path]	Import rules from IDE files into .agent/project/
co lint [path]	Check protocol compliance
co diff [path]	Compare local .agent with latest protocol
co sync [path]	Sync local .agent with latest protocol
co upgrade [path]	Run sync -> scaffold -> adapt(existing) in one step
co context [path]	Get context files based on stack and task
co status [path]	View or update project status
co ref <action>	Manage cross-project references (list/add/remove/check/fetch/cache)
co collab <action>	Manage collaborations (list/add/remove/status/diff/pull)
co global <action>	Manage global project registry (list/info/status/search/gc/unregister)
co serve [path]	Start MCP server (add --workspace for multi-project, --global for registry)
co shared <action>	Manage the machine-wide shared MCP daemon and version store
co journal [path]	Record a session entry to session-journal.md
co journal-flush [path]	Flush fragment files into status.md (trim to cap, archive overflow)
co branch start [branch]	Fetch trunk and create a task branch (--topic, --prefix, --dry-run)
co branch cleanup [branch]	Mandatory post-merge cleanup — delete local + remote head
co git hygiene	List merged remote branches not deleted; --apply --no-dry-run to clean up
co policy <action>	Manage policy-as-code: check / install-hook / doctor
co release <action>	Release helpers: plan (derive next version) / draft-note (generate release note skeleton)
co release-docs check [path]	Gate: verify release-doc placeholders are filled for a version-governance track. Exit 0 = pass, 1 = fail, 2 = fatal.
co release-docs refresh [path]	Print the canonical agent prompt to refresh release documentation (audit or apply mode).
co prepare-release [path] --track	Move a track into release preparation (supports --auto to derive version + note)
co cut-release [path] --track	Mark a track as released after the release flow
co start-next-version [path] --track --version	Open the next working version
co open-next-version [path] --track --version	Post-release: open the next iteration draft
co update-checksums [path]	Update bundled manifest.json checksums (maintainer)
co version	Show version information

Options for co init

Option	Description
--yes, -y	Skip prompts, use defaults
--name	Project name
--stack	Tech stack (python/rust/qt/mixed/other)
--force	Overwrite existing .agent directory
--online	Fetch latest protocol from GitHub Release (default: use bundled)

Options for co lint

Option	Description
--rule, -r	Check specific rule only
--format, -f	Output format (text/json/github)

Options for co context

Option	Description
--stack, -s	Tech stack (python/rust/qt/mixed)
--task, -t	Task type (coding/testing/review/documentation/bug_fix)
--output, -o	Output format (list/paths/content)

Options for co journal

Option	Description
--title, -t	Session title (e.g., "Feature X implementation")
--completed, -c	Completed items (comma-separated)
--debt, -d	Technical debt items (comma-separated)
--decisions	Key decisions made (comma-separated)
--interactive, -i	Interactive mode with prompts

Options for co journal-flush

Option	Description
--cap	Max items to keep in status.md (default: 5)
--for-release	Archive all items under a version header (e.g. v1.9.15)
--dry-run	Preview changes without writing files

MCP Server

cokodo-agent includes a built-in MCP (Model Context Protocol) server that exposes .agent/ project context to any compatible IDE. MCP support is included in the default install (pip install cokodo-agent); no extra step required.

IDE Configuration

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "cokodo-agent": {
      "command": "co",
      "args": ["serve", "--shared-launcher"]
    }
  }
}

Claude Code (.mcp.json):

{
  "mcpServers": {
    "cokodo-agent": {
      "command": "co",
      "args": ["serve", "--shared-launcher"],
      "type": "stdio"
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "cokodo-agent": {
      "command": "co",
      "args": ["serve", "--shared-launcher"],
      "type": "stdio"
    }
  }
}

Generated IDE configs now use co serve --shared-launcher by default so multiple IDE sessions can share one machine-wide daemon while still talking stdio locally.

Shared Runtime Management

co shared start
co shared status
co shared install-version 1.9.14
co shared use-version 1.9.14
co shared import-runtime C:/Python311/python.exe

Available Tools

Tool	Description
get_project_context	Get context files based on stack and task type
update_status	Update project status with tasks, blockers, context
lint_protocol	Run protocol compliance check
list_files	List all .agent/ files with loading layers
list_relations	List cross-project references and collaborations
get_related_context	Read content from references (local or remote)
get_collaboration_context	Get shared content from collaboration partners
get_collaboration_status	Check collaboration sync status
fetch_remote_references	Fetch/refresh remote git references
check_relation_health	Verify all relationships are accessible
list_global_projects	List all cokodo projects registered on this machine
get_global_project_context	Get context files from any registered project by name or ID
get_global_project_status	Get status.md from any registered project
global_search	Search across all registered projects by keyword (name/stack/status)

Workspace Mode

Serve multiple projects from a parent directory:

co serve --workspace /path/to/workspace

Adds workspace-level tools: list_workspace_projects, workspace_get_context, workspace_get_status, workspace_read_file, workspace_list_relations, workspace_health_check.

Global Registry Mode

Serve all cokodo projects registered on this machine, without needing to be inside a specific project directory:

co serve --global

Projects are registered automatically each time any co command is run inside a directory that has .agent/. No manual registration needed.

Global Project Registry

cokodo-agent maintains a local registry of all cokodo projects at ~/.cokodo/cokodo.db (SQLite). Registration is automatic — run any co command in a project to register it.

Registry Commands

co global list                  # List all registered projects
co global info <name>           # Show full details for a project
co global status <name>         # Show status.md for a project
co global search <keyword>      # Search by name, stack, or status
co global gc                    # Remove stale entries (deleted projects)
co global unregister <name>     # Remove a project from registry

Cross-project Context via MCP

When the MCP server is running (any mode), the AI can query all registered projects:

list_global_projects            → discover all projects on this machine
get_global_project_context      → load .agent/ context from any project
get_global_project_status       → read status.md from any project
global_search "keyword"         → find projects by name, stack, or status

Protocol Sources

The tool fetches the latest protocol from multiple sources with fallback:

Priority	Source	Description
1	GitHub Release	Latest version from repository
2	Built-in	Bundled version in package

Generated Structure

Cokodo Mode (Default)

Only generates .agent/ directory:

my-project/
+-- .agent/                     # Protocol directory
    +-- start-here.md           # * Entry point
    +-- quick-reference.md      # Cheat sheet
    +-- core/                   # Governance rules
    +-- project/                # Project-specific (customized)
    +-- skills/                 # Skill modules
    +-- adapters/               # Tool adapter templates
    +-- scripts/                # Helper scripts

With AI Tool Adapters

Run co adapt <tool> (or co adapt all) in a project that already has .agent/. Generated files follow each IDE’s official spec:

For the most common post-upgrade flow, use co upgrade -y to sync .agent/, scaffold any newly required project/ files, and refresh the IDE adapters already present in the repo.

Tool	Generated File
Cursor	.cursor/rules/agent-protocol.mdc (YAML frontmatter)
Claude Code	CLAUDE.md (project root)
GitHub Copilot	AGENTS.md (project root)
Gemini Code Assist	GEMINI.md (project root, supports @file imports)

Configuration

Environment Variables

Variable	Description
COKODO_OFFLINE	Force offline mode (1 or true)
COKODO_CACHE_DIR	Custom cache directory
COKODO_HOME_DIR	Custom home directory (default: ~/.cokodo/)

Cache Location

Downloaded protocols and the project registry are stored at:

• All platforms: ~/.cokodo/ (cache at ~/.cokodo/cache/)
• Existing ~/.cache/cokodo/ is migrated automatically on first run

Development

# Clone repository
git clone https://github.com/dinwind/agent_protocol.git
cd agent_protocol/cokodo-agent

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

License

MIT License - see LICENSE for details.

Documentation

• Complete Usage Guide - Detailed usage instructions
• 使用指南 (中文) - Chinese documentation
• Agent Protocol Documentation
• Report Issues