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

Options for co init

Options for co lint

Options for co context

Options for co journal

Options for co journal-flush

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

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:

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.

Configuration

Environment Variables

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