cokodo-agent 1.5.0

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

Cokodo Agent

A CLI tool to generate standardized AI collaboration protocol (.agent) for your projects.

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 in the project (read-only)
co import [path]	Import rules from IDE instruction 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 journal [path]	Record a session entry to session-journal.md
co update-checksums	Update checksums in manifest.json (maintainer only)
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

---

Protocol Sources

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

Priority	Source	Description
1	GitHub Release	Latest version from repository
2	Remote Server	Backup server [reserved]
3	Built-in	Bundled version in package

Priority 1: GitHub Release
    |
    | [unavailable]
    v
Priority 2: Remote Server [reserved, not implemented]
    |
    | [unavailable]
    v
Priority 3: Built-in (offline 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:

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

Cache Location

Downloaded protocols are cached at:

• Linux/macOS: ~/.cache/cokodo/
• Windows: %LOCALAPPDATA%\cokodo\cache\

---

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