cokodo-agent 1.8.8

AI Agent Collaboration Protocol Generator - Create standardized .agent protocol for your projects

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.

---

Installation

# Default install (minimal: typer, questionary, rich only)
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 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.3.0
  ====================

  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|gemini|all> [path]	Generate IDE entry files from existing .agent
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 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 journal [path]	Record a session entry to session-journal.md
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
--offline	Use built-in protocol (no network)

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

---

MCP Server

cokodo-agent includes a built-in MCP (Model Context Protocol) server that exposes .agent/ project context to any compatible IDE.

Install

pip install "cokodo-agent[mcp]"

IDE Configuration

Cursor (.cursor/mcp.json):

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

Claude Code (.mcp.json):

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

VS Code (.vscode/mcp.json):

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

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/registry.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:

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