<!-- mcp-name: io.github.dinwind/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.

---

## Installation

```bash
# 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

```bash
# 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)

```bash
$ 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

```bash
# 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

```bash
pip install "cokodo-agent[mcp]"
```

### IDE Configuration

**Cursor** (`.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "cokodo-agent": {
      "command": "co",
      "args": ["serve"]
    }
  }
}
```

**Claude Code** (`.mcp.json`):
```json
{
  "mcpServers": {
    "cokodo-agent": {
      "command": "co",
      "args": ["serve"],
      "type": "stdio"
    }
  }
}
```

**VS Code** (`.vscode/mcp.json`):
```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:

```bash
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:

```bash
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

```bash
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

```bash
# 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](LICENSE) for details.

---

## Documentation

- [Complete Usage Guide](../docs/usage-guide.md) - Detailed usage instructions
- [使用指南 (中文)](../docs/usage-guide_cn.md) - Chinese documentation
- [Agent Protocol Documentation](https://github.com/dinwind/agent_protocol)
- [Report Issues](https://github.com/dinwind/agent_protocol/issues)
