Cokodo Agent Usage Guide

Complete guide for setting up AI collaboration protocol in your projects

Installation
Quick Start
Command Reference
Generated Structure
Configuration Options
Post-Initialization Setup
AI Session Templates
Recommended Usage
MCP Server Integration
Cross-Project Features
Common Operations
Status Management
Environment Variables
Troubleshooting
Protocol Upgrade

Installation

Using pip

pip install cokodo-agent

Using pipx (Recommended)

pipx install cokodo-agent

Verify Installation

co version
# or: cokodo version

Quick Start

Interactive Mode (Default)

# Navigate to your project
cd my-project

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

The CLI will guide you through:

╭─────────────────────────╮
│  Cokodo Agent v1.0.0    │
╰─────────────────────────╯

Fetching protocol...
  OK Protocol v2.1.0

? Project name: my-awesome-app
? Brief description: A task management application
? Primary tech stack: Python
? AI tools to configure (at least one required):
  [x] Cokodo (Protocol Only)    <- Default
  [ ] Cursor
  [ ] GitHub Copilot
  [ ] Claude Projects
  [ ] Google Antigravity

Generating .agent/
  OK Created .agent/

╭─────────────────────────────────────────────────╮
│ Success! Created .agent in /path/to/my-project  │
│                                                 │
│ Next steps:                                     │
│   1. Review .agent/project/context.md           │
│   2. Customize .agent/project/tech-stack.md     │
│   3. Start coding with AI assistance!           │
╰─────────────────────────────────────────────────╯

Quick Mode (Non-Interactive)

# Use all defaults (Cokodo mode - protocol only)
co init --yes

# Specify project name and tech stack
co init --name "MyApp" --stack python --yes

# Initialize in a specific directory
co init ./new-project --yes

Command Reference

`co init [PATH]` (alias: `cokodo init`)

Create .agent protocol directory in the target location.

Arguments:

Argument	Description	Default
`PATH`	Target directory	Current directory

Options:

Option	Short	Description
`--yes`	`-y`	Skip interactive prompts, use defaults
`--name`	`-n`	Project name
`--stack`	`-s`	Tech stack (`python`/`rust`/`qt`/`mixed`/`other`)
`--force`	`-f`	Overwrite existing `.agent` directory
`--offline`		Use built-in protocol (no network)

Examples:

# Interactive initialization
co init

# Quick initialization with defaults
co init -y

# Specify all options
co init ./my-project -n "My Project" -s python -y

# Force overwrite existing protocol
co init --force

# Offline mode (use bundled protocol)
co init --offline

`co version` (alias: `cokodo version`)

Display version information for CLI and bundled protocol.

$ co version
cokodo-agent v1.6.0

Protocol versions:
  Built-in: v3.2.0

`co status [PATH]`

Show or initialize project development status.

Options:

Option	Description
`--raw`	Show raw markdown without formatting
`--json`	Output as JSON
`--init`	Create a new `status.md` from template

Examples:

# Show formatted project status
co status

# Show raw markdown
co status --raw

# Output as JSON (for scripting)
co status --json

# Initialize status.md in a project
co status --init

`co scaffold [PATH]`

Audit and scaffold missing project/ files from templates.

Options:

Option	Short	Description
`--force`	`-f`	Overwrite existing files
`--yes`	`-y`	Skip confirmation prompts

Examples:

# Audit and scaffold missing project files
co scaffold

# Force overwrite existing files, skip prompts
co scaffold --force -y

`co ref <action> [SOURCE]`

Manage references to other projects and documents.

Actions: list, add, remove, check

Options:

Option	Description
`--name`	Human-readable name for the reference
`--description`	Description of what the reference provides
`--scope`	Scope filter (e.g. `core`, `project`)
`--use-when`	When to load the reference (`always`, `on-demand`)

Examples:

# List all references
co ref list

# Add a reference to another project
co ref add ../backend/.agent --name backend

# Check health of all references
co ref check

`co collab <action> [PARTNER]`

Manage collaborations with partner projects (master/replica model).

Actions: list, add, remove, status, diff, pull

Options:

Option	Description
`--name`	Human-readable name for the collaboration
`--role`	Role in collaboration (`master` or `replica`)
`--scope`	Scope of shared content
`--description`	Description of the collaboration

Examples:

# Add a collaboration partner as replica
co collab add ../backend/.agent --name backend --role replica

# Show collaboration status
co collab status

# View differences with a partner
co collab diff backend

# Pull latest changes from a partner
co collab pull backend

`co serve [PATH]`

Start MCP server for IDE integration.

Requires: pip install cokodo-agent[mcp]

Options:

Option	Short	Description
`--transport`	`-t`	Transport protocol (`stdio` or `streamable-http`)
`--workspace`		Enable multi-project workspace mode

Examples:

# Start MCP server (stdio, default)
co serve

# Start in workspace mode (discovers all .agent/ dirs)
co serve --workspace

# Start with HTTP transport
co serve -t streamable-http

Generated Structure

After running cokodo init, the following structure is created:

your-project/
├── .agent/                         # Protocol directory
│   ├── start-here.md              # ⭐ AI entry point (read first)
│   ├── quick-reference.md         # 📋 One-page cheat sheet
│   ├── index.md                   # 🗂️ Navigation index
│   ├── manifest.json              # ⚙️ Loading strategy & metadata
│   │
│   ├── core/                      # 🔧 Governance engine (reusable)
│   │   ├── core-rules.md          #    Core philosophy & iron rules
│   │   ├── instructions.md        #    AI collaboration guidelines
│   │   ├── conventions.md         #    Naming & Git conventions
│   │   ├── security.md            #    Security development standards
│   │   ├── examples.md            #    Code examples
│   │   ├── workflows/             #    Workflow specifications
│   │   │   ├── ai-boundaries.md
│   │   │   ├── bug-prevention.md
│   │   │   ├── design-principles.md
│   │   │   ├── documentation.md
│   │   │   ├── pre-task-checklist.md
│   │   │   ├── quality-assurance.md
│   │   │   ├── review-process.md
│   │   │   └── testing.md
│   │   └── stack-specs/           #    Tech stack specifications
│   │       ├── git.md
│   │       ├── python.md
│   │       ├── rust.md
│   │       └── qt.md
│   │
│   ├── project/                   # 📋 Project instance (customized)
│   │   ├── context.md             #    ✏️ Business context
│   │   ├── tech-stack.md          #    ✏️ Technology configuration
│   │   ├── known-issues.md        #    Known issues database
│   │   └── adr/                   #    Architecture Decision Records
│   │       └── readme.md
│   │
│   ├── skills/                    # 🛠️ Skill modules
│   │   ├── skill-interface.md     #    Skill development guide
│   │   ├── guardian/              #    Code quality gate
│   │   ├── ai-integration/        #    AI service integration
│   │   └── agent-governance/      #    Protocol health check
│   │
│   ├── adapters/                  # 🔌 Tool adapters (templates)
│   │   ├── cursor/
│   │   ├── github-copilot/
│   │   ├── claude/
│   │   └── google-antigravity/
│   │
│   ├── meta/                      # 📚 Protocol evolution
│   │   ├── protocol-adr.md
│   │   └── adr-archive.md
│   │
│   └── scripts/                   # 🔧 Helper scripts
│       ├── init_agent.py
│       ├── lint-protocol.py
│       └── token-counter.py
│
├── .cursorrules                   # [Optional] Cursor configuration
├── .github/
│   └── copilot-instructions.md    # [Optional] Copilot configuration
└── .claude/
    └── instructions.md            # [Optional] Claude configuration

Directory Types

Type	Directory	Purpose	Portability
Engine	`core/`	Universal governance rules	✅ Reusable across projects
Instance	`project/`	Project-specific information	❌ Project-exclusive

Core Rule: Engine files must never contain project-specific names, paths, or business logic.

Configuration Options

Tech Stack Options

Value	Description	Recommended Tools
`python`	Python projects	uv/pip, ruff, pytest, mypy
`rust`	Rust projects	cargo, clippy, rustfmt
`qt`	Qt/C++ projects	CMake/qmake, Qt Creator
`mixed`	Python + Rust	Combined tooling
`other`	Other stacks	Custom configuration

AI Tool Configurations

Tool	Config Files	Description
Cursor	`.cursor/rules/agent-protocol.mdc` + `.cursor/mcp.json`	Cursor rules + MCP server config
Claude Code	`CLAUDE.md` + `.mcp.json`	Claude project memory + MCP server config
GitHub Copilot	`AGENTS.md` + `.vscode/mcp.json`	Copilot instructions + MCP server config
Gemini Code Assist	`GEMINI.md` + `mcp_config.json`	Gemini context + MCP server config

Generate these with co adapt <cursor|claude|copilot|gemini|all> in a project that has .agent/. Detect existing IDE instruction files with co detect; import from them into .agent/project/ with co import.

Post-Initialization Setup

Step 1: Configure Project Context

Edit .agent/project/context.md:

# Project Context

## Project Name

YourProjectName

## Description

Brief description of what this project does and what problems it solves.

## Current Status

[Development stage, MVP, Production, etc.]

## Key Features

1. Feature A - Description
2. Feature B - Description
3. Feature C - Description

## Business Rules

- Rule 1: Description
- Rule 2: Description

Step 2: Configure Tech Stack

Edit .agent/project/tech-stack.md:

# Tech Stack

## Primary Stack

Python

## Language Versions

- Python 3.11+
- Node.js 18+ (if applicable)

## Key Dependencies

- FastAPI 0.100+
- SQLAlchemy 2.0+
- Pydantic 2.0+

## Development Environment

- OS: Windows/Linux/macOS
- IDE: Cursor / VS Code
- Package Manager: uv / pip

## Build Commands

pip install -r requirements.txt
pytest tests/

Step 3: Configure AI Tools (Optional)

Generate or refresh IDE entry files from your existing .agent/:

co adapt all              # Generate CLAUDE.md, AGENTS.md, GEMINI.md, .cursor/rules/
co adapt cursor           # Cursor only
co detect                 # List detected IDE instruction files (read-only)
co import --dry-run       # Preview import from those files into .agent/project/
co import                 # Import project name and rules into project/context.md and conventions.md

AI Tool	Generated File	Notes
Cursor	`.cursor/rules/agent-protocol.mdc`	Run `co adapt cursor`
Claude Code	`CLAUDE.md`	Run `co adapt claude`
GitHub Copilot	`AGENTS.md`	Run `co adapt copilot`
Gemini	`GEMINI.md`	Run `co adapt gemini`

IDE global rules: IDEs (Cursor, Claude Code, etc.) may load user/global rules or memory. Generated entry files state at the top that this repo's .agent/ and the generated file are the single source of truth; user/global IDE rules are for editor behavior only. Prefer project-local .cursor/rules and .agent for project context.

AI Session Templates

Quick Start (Daily Use)

Please read .agent/start-here.md first to establish project context, 
then strictly follow the protocol rules.

Today's task: [Describe your task]

Full Context (First Session or Complex Tasks)

Please read the following files in order to establish project context:

1. .agent/start-here.md
2. .agent/project/context.md
3. .agent/project/tech-stack.md
4. .agent/core/instructions.md
5. .agent/core/stack-specs/python.md  # Choose based on tech stack

Then proceed with today's task: [Describe your task]

Debug Session

Please read .agent/start-here.md and .agent/core/workflows/bug-prevention.md 
to understand known issues.

I'm experiencing this bug: [Describe the issue]

Recommended Usage

The recommended workflow for AI-assisted development with Cokodo:

Start each AI session by reading .agent/start-here.md — this establishes project context, rules, and architecture understanding for the AI.
Track progress with co status — update .agent/project/status.md at checkpoints: after completing tasks, before commits, when switching tasks, and when blockers arise.
Verify compliance with co lint — run before committing to catch protocol violations, missing files, or broken references early.
Use co serve for seamless IDE integration — the MCP server gives your AI tool direct access to project context, status updates, and lint checks without manual file reading.
Use co ref and co collab for multi-project setups — reference shared libraries, link related services, and keep collaborating projects in sync with the master/replica model.

# Typical session workflow
co status                  # Check current state
# ... do work ...
co lint                    # Verify protocol compliance
co status                  # Update progress before commit
git add -A && git commit

MCP Server Integration

The MCP (Model Context Protocol) server lets AI tools access project context directly, without manual file reading.

Installation

pip install "cokodo-agent[mcp]"

Usage

# Start MCP server with stdio transport (default)
co serve

# Start in workspace mode (discovers all .agent/ directories)
co serve --workspace

# Start with HTTP transport
co serve -t streamable-http

IDE Configuration

Cursor (`.cursor/mcp.json`)

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

Claude Code (`.mcp.json`)

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

VS Code / GitHub Copilot (`.vscode/mcp.json`)

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

Gemini (`mcp_config.json`)

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

Generate these configs automatically with co adapt <cursor|claude|copilot|gemini|all>.

Available Tools

Tool	Description
`get_project_context`	Retrieve project context, tech stack, and business rules
`update_status`	Update project status (tasks, blockers, session context)
`lint_protocol`	Run protocol compliance checks
`list_files`	List files in the `.agent/` directory
`list_relations`	List all references and collaborations
`get_related_context`	Get content from a referenced project or document
`get_collaboration_context`	Get content from a collaboration partner
`get_collaboration_status`	Check sync status of collaboration partners
`check_relation_health`	Verify all references and collaborations are reachable

Cross-Project Features

Cokodo supports linking multiple projects together through references and collaborations.

References

References are read-only links to other projects, directories, or files. They let your AI session pull context from external sources.

# Add a reference to another project
co ref add ../shared-lib/.agent --name shared-lib

# Add a reference to a documentation file
co ref add ../docs/api-spec.md --name api-spec --use-when always

# List all references
co ref list

# Check that all references are reachable
co ref check

Collaborations

Collaborations use a master/replica model to keep shared content in sync between projects. One project is the master (source of truth), and others are replicas that pull updates.

# Add a collaboration partner (this project is the replica)
co collab add ../backend/.agent --name backend --role replica

# Check sync status
co collab status

# View what changed in the master
co collab diff backend

# Pull latest changes from the master
co collab pull backend

Workspace Mode

For multi-project setups, workspace mode discovers all .agent/ directories and exposes them through a single MCP server:

co serve --workspace

This gives AI tools access to all projects in the workspace, enabling cross-project context and navigation.

Common Operations

Check Project Status

co status

Check Protocol Health

co lint

Scaffold Missing Project Files

co scaffold

Count Token Usage

python .agent/scripts/token-counter.py

Record Bug Prevention Knowledge

Edit .agent/core/workflows/bug-prevention.md to add new entries:

### Issue: [Brief Description]

**Symptom:** What happened
**Cause:** Why it happened
**Solution:** How to fix/prevent it
**Date:** YYYY-MM-DD

Record Architecture Decisions

Create new ADR files in .agent/project/adr/:

# ADR-001: [Decision Title]

## Status
Accepted

## Context
[Why this decision was needed]

## Decision
[What was decided]

## Consequences
[Impact of the decision]

Environment Variables

Variable	Description	Default
`COKODO_OFFLINE`	Force offline mode (`1`, `true`, `yes`)	Disabled
`COKODO_CACHE_DIR`	Custom cache directory	OS-specific
`COKODO_REMOTE_SERVER`	Remote protocol server URL	None (reserved)

Cache Locations

OS	Default Path
Linux/macOS	`~/.cache/cokodo/`
Windows	`%LOCALAPPDATA%\cokodo\cache\`

Troubleshooting

Q: AI is not following protocol rules?

Solution: Ensure the AI reads start-here.md at the beginning of each session.

Please read .agent/start-here.md first before proceeding with any task.

Q: Too many files, token consumption is too high?

Solution: Use the layered loading strategy defined in manifest.json. Only load files needed for the current task.

Essential files (~3,000 tokens):

start-here.md
quick-reference.md

Context files (~2,000 tokens):

project/context.md
project/tech-stack.md

Q: Protocol initialization failed?

Solution: Check these common issues:

Permission denied: Run with appropriate permissions
Directory exists: Use --force to overwrite
Network error: Use --offline for bundled protocol

# Force overwrite with offline mode
cokodo init --force --offline

Q: How to use a different protocol directory name?

Solution: The protocol uses $AGENT_DIR placeholder internally. To rename:

Rename the directory:
```
mv .agent .agent_custom
```
Update manifest.json:
```
{
  "directory_name": ".agent_custom"
}
```

Status Management

Use co status to track development progress across AI sessions:

co status          # View current status (formatted)
co status --raw    # Raw markdown output
co status --json   # JSON output (for scripting)
co status --init   # Create status.md from template

Update .agent/project/status.md at these checkpoints:

After completing a task
Before git commit
When switching tasks
When a blocker is found or resolved

Protocol Upgrade

Upgrade with CLI

co diff            # See what changed between your protocol and latest
co sync            # Sync with latest (project/ files are preserved)
co sync --dry-run  # Preview changes without applying

The co sync command upgrades core/, meta/, skills/, and adapters/ while preserving your project/ directory.

Version Compatibility

CLI Version	Protocol Version	Notes
1.6.x	3.2.0	Current stable (cross-project support)
1.5.x	3.1.0	Legacy (MCP server, status management)
1.0.x–1.4.x	2.1.0–3.0.0	Legacy

Iron Rules

These rules must always be followed:

Rule	Description
UTF-8 Encoding	Always specify `encoding='utf-8'` explicitly
Forward Slash Paths	Use `/` instead of `\` in commands
Test Data Prefix	Use `autotest_` prefix for test data
kebab-case Files	Files in `.agent/` use lowercase with hyphens
SKILL.md Uppercase	Skill entry files use uppercase (agentskills.io standard)

Document	Content
`.agent/start-here.md`	Protocol entry point and architecture overview
`.agent/quick-reference.md`	One-page quick reference
`.agent/meta/protocol-adr.md`	Protocol evolution history
`.agent/skills/skill-interface.md`	How to develop new skills

Protocol Sources

The CLI fetches protocol from multiple sources with automatic fallback:

Priority 1: GitHub Release (latest version)
    ↓ [unavailable]
Priority 2: Remote Server (reserved for future)
    ↓ [unavailable]
Priority 3: Built-in (offline fallback)

Support

Documentation: Agent Protocol Repository
Issues: Report Issues
Discussions: GitHub Discussions

Making AI collaboration more standardized, efficient, and sustainable

Document Version: 2.0.0 | Protocol: v3.2.0 | Last Updated: 2026-03-02

FilesExpand file tree

usage-guide.md

Latest commit

History

usage-guide.md

File metadata and controls

Cokodo Agent Usage Guide

Table of Contents

Installation

Using pip

Using pipx (Recommended)

Verify Installation

Quick Start

Interactive Mode (Default)

Quick Mode (Non-Interactive)

Command Reference

co init [PATH] (alias: cokodo init)

co version (alias: cokodo version)

co status [PATH]

co scaffold [PATH]

co ref <action> [SOURCE]

co collab <action> [PARTNER]

co serve [PATH]

Generated Structure

Directory Types

Configuration Options

Tech Stack Options

AI Tool Configurations

Post-Initialization Setup

Step 1: Configure Project Context

Step 2: Configure Tech Stack

Step 3: Configure AI Tools (Optional)

AI Session Templates

Quick Start (Daily Use)

Full Context (First Session or Complex Tasks)

Debug Session

Recommended Usage

MCP Server Integration

Installation

Usage

IDE Configuration

Cursor (.cursor/mcp.json)

Claude Code (.mcp.json)

VS Code / GitHub Copilot (.vscode/mcp.json)

Gemini (mcp_config.json)

Available Tools

Cross-Project Features

References

Collaborations

Workspace Mode

Common Operations

Check Project Status

Check Protocol Health

Scaffold Missing Project Files

Count Token Usage

Record Bug Prevention Knowledge

Record Architecture Decisions

Environment Variables

Cache Locations

Troubleshooting

Q: AI is not following protocol rules?

Q: Too many files, token consumption is too high?

Q: Protocol initialization failed?

Q: How to use a different protocol directory name?

Status Management

Protocol Upgrade

Upgrade with CLI

Version Compatibility

Iron Rules

Further Reading

Protocol Sources

Support

`co init [PATH]` (alias: `cokodo init`)

`co version` (alias: `cokodo version`)

`co status [PATH]`

`co scaffold [PATH]`

`co ref <action> [SOURCE]`

`co collab <action> [PARTNER]`

`co serve [PATH]`

Cursor (`.cursor/mcp.json`)

Claude Code (`.mcp.json`)

VS Code / GitHub Copilot (`.vscode/mcp.json`)

Gemini (`mcp_config.json`)