CLEO

The Portable Brain and Memory System for AI Software Development

The contract between you and your AI coding agent

Quick start · Command reference · Documentation · Contributing

One Developer. One Agent. One Source of Truth.

CLEO is a vendor-neutral Brain and Memory system for AI software development. It provides portable project memory, verifiable provenance, and agent-safe orchestration across any repository, model provider, or coding tool.

CLEO originated as "Command Line Entity Orchestrator" but has evolved beyond that acronym. CLEO is the proper name for the complete platform.

Agents hallucinate. CLEO validates every operation with four-layer anti-hallucination.
Agents lose context. CLEO persists state in SQLite with immutable audit trails.
Agents need structure. CLEO outputs JSON by default via the LAFS protocol.

Optimized for Claude Code, and intentionally portable across model providers, agent runtimes, and coding tools.

Four Systems

CLEO is composed of four interdependent systems:

BRAIN — Memory & Cognition: Persistent memory backend storing observations, patterns, learnings, and decisions. Provides FTS5 search, vector similarity, and graph-based retrieval.
RCASD-IVTR+C — Structured Lifecycle: Ten-stage pipeline from Research through Release, plus cross-cutting Contribution protocol. Deterministic gates and manifest-based provenance.
NEXUS — Cross-Project Network: Connective layer between registered CLEO projects. Global graphs, shared patterns, and federated queries while preserving per-project isolation.
LAFS — Agent Communication Contract: The LLM-Agent-First Specification protocol. JSON envelopes, MVI progressive disclosure, field filtering, and deterministic exit codes.

Five Pillars

Portable Memory (BRAIN) — Per-project .cleo/ directory with tasks.db (project work) and brain.db (memory/cognition). Move the directory, the brain moves with it.
Agent Communication Contract (LAFS) — Provider-neutral protocol: JSON envelopes, MVI-tiered progressive disclosure, field filtering, deterministic exit codes.
Structured Lifecycle (RCASD-IVTR+C) — Research → Consensus → Architecture Decision → Specification → Decomposition → Implementation → Validation → Testing → Release + Contribution.
Deterministic Safety — Four-layer validation (schema, semantic, referential, state machine), atomic writes, immutable audit logs, lifecycle gate enforcement.
Cognitive Retrieval (BRAIN + NEXUS) — Three-tier retrieval: FTS5 keyword search, vector similarity, graph-based discovery. NEXUS extends retrieval across project boundaries.

Current State vs Strategic Direction

State	What It Means
Shipped	TypeScript CLI + MCP server, SQLite storage (`tasks.db`), atomic operations, four-layer anti-hallucination, RCASD-IVTR+C lifecycle gates, session management, vectorless RAG (5 discovery methods), LAFS envelopes
Gated	Dedicated `brain.db` (FTS5, vector, PageIndex), `nexus.db` (cross-project graph), knowledge graph with version chains, agent profiles, federated queries

MCP Server

The MCP server is included in the @cleocode/cleo package. No separate install needed.

For provider-specific MCP setup and profile management (Claude Code, OpenCode, Antigravity, etc.), use CAAMP as the canonical installer/config manager.

Auto-configure across your AI tools:

cleo mcp-install              # Auto-detect and configure all AI tools
cleo mcp-install --list-tools # Show 12 supported tools

Manual MCP config (for any MCP-compatible tool):

{
  "mcpServers": {
    "cleo": {
      "command": "npx",
      "args": ["-y", "@cleocode/cleo", "--mcp-server"]
    }
  }
}

Or if installed globally (npm install -g @cleocode/cleo):

{
  "mcpServers": {
    "cleo": {
      "command": "cleo",
      "args": ["mcp"]
    }
  }
}

Supports: Claude Code, Claude Desktop, Cursor, Gemini CLI, Kimi, Antigravity, Windsurf, Goose, OpenCode, VS Code, Zed, Codex

Canonical MCP contract: docs/mintlify/specs/MCP-SERVER-SPECIFICATION.md
MCP source: src/mcp/ (gateways, domains, engine)
Operation matrix: src/mcp/gateways/query.ts and src/mcp/gateways/mutate.ts

Using the MCP Tools

Your AI agent gets two tools: cleo_query (read) and cleo_mutate (write). Each takes a domain, operation, and optional params:

# Read operations (never changes anything)
cleo_query  domain=tasks   operation=find   params={"query": "auth"}
cleo_query  domain=system  operation=dash
cleo_query  domain=tasks   operation=next

# Write operations (creates or modifies data)
cleo_mutate domain=tasks   operation=add     params={"title": "...", "description": "..."}
cleo_mutate domain=tasks   operation=complete params={"taskId": "T1234", "notes": "Done."}
cleo_mutate domain=issues  operation=add.bug  params={"title": "...", "body": "...", "dryRun": true}

10 canonical domains, 177 operations (97 query + 80 mutate) across tasks, sessions, memory, check, pipeline, orchestration, tools, admin, nexus, and sharing. See the MCP Usage Guide for beginner-friendly walkthroughs.

Source of Truth Hierarchy

docs/concepts/vision.md - immutable product vision
docs/mintlify/specs/PORTABLE-BRAIN-SPEC.md - canonical normative contract
README.md - operational public contract
docs/mintlify/specs/CLEO-STRATEGIC-ROADMAP-SPEC.md - phased execution plan
docs/mintlify/specs/CLEO-BRAIN-SPECIFICATION.md - detailed capability model

Why This Exists

Traditional task management assumes human users. But when your primary "user" is an LLM agent:

What Humans Need	What Agents Need
Natural language	Structured JSON
Descriptive errors	Exit codes
Flexibility	Constraints
Trust	Validation
Memory	Persistence

CLEO is built for agents first. The --human flag is for you — the developer reviewing what your agent sees.

Core Principles

LLM-Agent-First Design

Every command follows a consistent pattern:

# JSON by default (agent-first)
cleo list                              # Returns JSON
cleo list | jq '.tasks[0].id'          # Parse with jq

# Human-readable when you need it (developer-friendly)
cleo list --human                      # Formatted text output

# Exit codes for programmatic branching (17 documented codes)
cleo exists T042 --quiet && echo "Found"

Anti-Hallucination Protection

Four layers of validation prevent AI-generated errors:

Layer	Purpose	What It Catches
1. Schema	JSON Schema enforcement	Missing fields, wrong types, invalid enums
2. Semantic	Business logic validation	Duplicate IDs, future timestamps, invalid status transitions
3. Cross-File	Referential integrity	Orphaned references, archive inconsistencies, data loss
4. State Machine	Transition rules	Invalid status changes, constraint violations

Before any write operation:

✓ ID exists (prevent hallucinated references)
✓ ID unique (across active and archived tasks)
✓ Status valid (pending|active|blocked|done)
✓ Timestamps sane (not future, completedAt > createdAt)
✓ Dependencies acyclic (no circular references)
✓ Parent exists (hierarchy integrity)

Stable Task IDs

T001, T002, T042, T999, T1000...

IDs are flat, sequential, and eternal. No hierarchical IDs like T001.2.3 that break when you restructure. Hierarchy is stored in the parentId field—identity and structure are decoupled.

Every external reference stays valid forever:

Git commits: "Fixes T042" → always resolves
Documentation: See [T042] → never orphaned
Scripts: grep T042 → always finds it

Quick Start

Installation Channels (Stable, Beta, Dev)

CLEO supports three runtime channels:

Stable: production users (cleo, optional ct; MCP via cleo mcp)
Beta: prerelease validation (cleo-beta, optional ct-beta; MCP via cleo-beta mcp)
Dev: contributor-isolated runtime (cleo-dev, no ct; MCP via cleo-dev mcp)

The dev channel is designed to run in parallel with stable and should use isolated data (~/.cleo-dev).

Contributor Dev Setup (Isolated)

Use the installer dev mode for canonical cleo-dev behavior:

./install.sh --dev
cleo-dev env info --json

npm link caveat: raw npm link follows package.json bin mappings and can expose cleo/ct. Use ./install.sh --dev when you need strict dev-channel isolation.

TL;DR - Just Install It

Option 1: One-liner (Easiest)

curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash

# Reinstalling over existing installation? Use --force:
curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash -s -- --force

Option 2: Download and Run

After downloading, open Terminal and run:

# macOS/Linux: Run with bash (no chmod needed)
bash ~/Downloads/install.sh

Option 3: From source (for contributors)

git clone https://github.com/kryptobaseddev/cleo.git && cd cleo && ./installer/install.sh --dev

Then initialize in your project:

cd /path/to/your/project && cleo-dev init

Prerequisites

Required (Core CLI):

Dependency	Version	Install
Node.js	24+	https://nodejs.org/
npm	Latest with Node.js	Included with Node
curl or wget	Any	Pre-installed on most systems (for remote install)

Optional (Advanced Features):

Dependency	For	Install
sqlite3 CLI	Manual DB inspection/debugging	platform package manager

Note: CLEO is TypeScript/Node.js. Contributor docs in CONTRIBUTING.md cover full dev setup.

Detailed Installation Options

Download from Releases (Recommended for Users)

Go to Releases
Download cleo-X.Y.Z.tar.gz

Extract and install:

tar xzf cleo-*.tar.gz
cd cleo-*
./installer/install.sh

One-liner Install (for Developers)

curl -fsSL https://raw.githubusercontent.com/kryptobaseddev/cleo/main/install.sh | bash

From Source (for Contributors)

# Clone repository
git clone https://github.com/kryptobaseddev/cleo.git
cd cleo

# Install dev channel (isolated command names)
./installer/install.sh --dev

# Verify isolated runtime
cleo-dev env info --json

# Or install as release (copies files)
./installer/install.sh --release

npm link caveat: raw npm link follows package bin mappings and can expose cleo/ct. Use ./installer/install.sh --dev when you need strict cleo-dev isolation.

Verify Installation

cleo version
cleo env info --json

Provider alias/config utilities are managed by CAAMP.

Initialize in Your Project

cd /path/to/your/project
cleo init

For contributor dev channel:

cd /path/to/your/project
cleo-dev init

Note: The installer creates symlinks in ~/.local/bin/, which works immediately with Claude Code and most modern shells.

Upgrade & Self-Update

When to Use Each Method

Scenario	Command
Fresh install	`curl ... \| bash`
Update to latest	`cleo self-update` (preferred)
Update to specific version	`cleo self-update --version X.Y.Z`
Switch dev → release	`cleo self-update --to-release`
Switch release → dev	`cleo self-update --to-dev /path/to/repo`
Reinstall / fix broken install	`curl ... \| bash -s -- --force`

Self-Update (Recommended)

Use self-update for routine updates. It preserves user data and is safer than reinstalling.

# Check for updates
cleo self-update --check

# Update to latest version
cleo self-update

# Update to specific version
cleo self-update --version 0.60.0

# Show current version and update status
cleo self-update --status

Mode Switching (v0.58.0+)

Switch between development mode (symlinks) and release mode (copied files):

# Switch from dev mode to release mode
cleo self-update --to-release

# Switch from release mode to dev mode
cleo self-update --to-dev /path/to/cleo-repo

See Installation Modes Guide for details.

Reinstall with --force

Only use installer --force for fresh reinstalls or troubleshooting broken installations:

# Force reinstall (overwrites existing installation)
curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash -s -- --force

Manual Upgrade (Legacy)

# Check for updates (if self-update unavailable)
./installer/install.sh --check-upgrade

# Upgrade to latest
./installer/install.sh --upgrade

# For project schema migrations
cleo migrate status
cleo migrate run

Uninstall

./installer/install.sh --uninstall

The `ct` Shortcut

ct is a stable-channel compatibility alias. Dev channel intentionally does not provide ct; use cleo-dev.

ct list        # Same as cleo list
ct add "Task"  # Same as cleo add "Task"
ct done T001   # Same as cleo complete T001
ct find "auth" # Fast fuzzy search (99% less tokens than list)

Built-in aliases: ls, done, new, edit, rm, check, tags, overview, dig

Tab Completion

Enable shell completion for faster command entry and context-aware suggestions:

Bash (add to ~/.bashrc):

source ~/.cleo/completions/bash-completion.sh

Zsh (add to ~/.zshrc):

fpath=(~/.cleo/completions $fpath)
autoload -Uz compinit && compinit

Features:

Context-aware --parent completion (shows only valid parents: epics and tasks, not subtasks)
All commands, subcommands, and flags
Task ID completion with status filtering
Phase, label, and priority value completion

# Example usage
cleo add --parent <TAB>     # Shows T001, T002 (epic/task only)
cleo list --status <TAB>    # Shows pending, active, blocked, done
cleo start <TAB>             # Shows pending/active task IDs

Command Reference

48 Commands Across 5 Categories

Category	Commands	Purpose
Write (14)	`add`, `update`, `complete`, `start`, `session`, `phase`, `archive`, `promote`, `reparent`, `populate-hierarchy`, `delete`, `uncancel`, `reopen`, `verify`	Modify task state
Read (17)	`list`, `show`, `find`, `analyze`, `next`, `dash`, `deps`, `blockers`, `phases`, `labels`, `stats`, `log`, `commands`, `exists`, `export`, `history`, `research`	Query and analyze
Sync (3)	`sync`, `inject`, `extract`	TodoWrite integration
Orchestration (5)	`orchestrator`, `context`, `tree`, `import-tasks`, `export-tasks`	Multi-agent coordination
Maintenance (9)	`init`, `validate`, `backup`, `restore`, `migrate`, `migrate-backups`, `config`, `upgrade`, `self-update`	System administration

Essential Commands

# Task lifecycle
cleo add "Implement authentication" --priority high
cleo list                     # View all tasks (JSON default)
cleo list --status pending    # Filter by status
cleo update T001 --labels "backend,security"
cleo complete T001
cleo archive

# Session workflow
cleo session start
cleo start T001               # Only ONE active task allowed
cleo update T001 --notes "Working on JWT validation"
cleo session end

# Analysis & planning
cleo dash                     # Project overview
cleo analyze                  # Task triage with leverage scoring
cleo analyze --auto-start     # Auto-start highest leverage task
cleo next --explain           # What should I work on?
cleo blockers analyze         # Critical path analysis

# Context-efficient search (v0.19.2+)
cleo find "auth"              # Fuzzy search (~1KB vs 355KB for full list)
cleo find --id 42             # Find T42, T420, T421...
cleo find "api" --status pending --field title

# Single task inspection
cleo show T001                # Full task details
cleo show T001 --history      # Include audit trail
cleo exists T001 --quiet      # Exit 0 if exists, 1 if not

# Research & discovery (v0.23.0+)
cleo research "TypeScript patterns"           # Multi-source web research
cleo research --library svelte --topic state  # Official docs via Context7
cleo research --url https://example.com       # Extract from URL

# Verification gates (v0.43.0+)
cleo verify T001 --gate testsPassed           # Set specific gate
cleo verify T001 --all                        # Set all required gates

# Task cancellation (v0.32.0+)
cleo delete T001 --reason "No longer needed"  # Cancel/soft-delete task
cleo uncancel T001                            # Restore cancelled task

# Context monitoring (v0.46.0+)
cleo context                                  # Check context window usage
cleo context check                            # Exit codes for scripting

# Self-update (v0.56.0+)
cleo self-update                              # Update to latest version
cleo self-update --check                      # Check for updates

Command Discovery (v0.21.0+)

# Native filters - no jq needed
cleo commands                     # List all (JSON by default)
cleo commands --human             # Human-readable
cleo commands --category write    # Filter by category
cleo commands --relevance critical # Filter by agent relevance
cleo commands --workflows         # Agent workflow sequences
cleo commands add                 # Details for specific command

Agent-Friendly Output

LLM-Agent-First: JSON is the default output format for all commands. Use --human for human-readable text.

# Default behavior (JSON everywhere)
cleo list                    # JSON output (LLM-Agent-First default)
cleo analyze                 # JSON output
cleo show T001               # JSON output

# Human-readable when you need it
cleo list --human            # Human-readable text
cleo dash --human            # Formatted dashboard

# Pipe to jq for parsing
cleo list | jq '.tasks[0].id'

JSON Envelope Structure

All commands return a consistent envelope with $schema, _meta, and success fields:

{
  "$schema": "https://cleo-dev.com/schemas/v1/output.schema.json",
  "_meta": {
    "format": "json",
    "command": "list",
    "version": "0.23.0",
    "timestamp": "2025-12-19T10:30:45Z"
  },
  "success": true,
  "tasks": [...]
}

Error Response Structure

Errors return structured JSON with error codes, exit codes, and recovery suggestions:

{
  "$schema": "https://cleo-dev.com/schemas/v1/error.schema.json",
  "_meta": {
    "format": "json",
    "command": "show",
    "version": "0.23.0",
    "timestamp": "2025-12-19T10:30:45Z"
  },
  "success": false,
  "error": {
    "code": "E_TASK_NOT_FOUND",
    "message": "Task T999 does not exist",
    "exitCode": 4,
    "recoverable": false,
    "suggestion": "Use 'ct exists T999 --quiet' to verify task ID"
  }
}

Task Hierarchy (v0.17.0+)

Three levels, no more:

Epic (strategic initiative)
  └── Task (primary work unit)
        └── Subtask (atomic operation)

# Create hierarchy
cleo add "Auth System" --type epic --size large
cleo add "JWT middleware" --parent T001 --size medium
cleo add "Validate tokens" --parent T002 --type subtask

# View tree
cleo list --tree
T001 [epic] Auth System
├── T002 [task] JWT middleware
│   └── T003 [subtask] Validate tokens
└── T004 [task] Session management

# Filter by hierarchy
cleo list --type epic
cleo list --parent T001
cleo list --children T001

Hierarchy Constraints

Constraint	Default	Configurable
Max depth	3 levels	`hierarchy.maxDepth`
Max siblings	20 per parent	`hierarchy.maxSiblings`
Max active siblings	8 per parent	`hierarchy.maxActiveSiblings`

Scope-Based Sizing (No Time Estimates)

Size	Scope	Action
Small	1-2 files, straightforward	Execute
Medium	3-7 files, moderate complexity	Execute
Large	8+ files, architectural	Decompose first

Time estimates are prohibited. They're unpredictable for humans and meaningless for agents.

Session Protocol

Agents lose context between invocations. Sessions provide checkpoints:

# Morning routine
cleo session start
cleo dash              # Where am I?
cleo current           # What was I working on?

# Work session
cleo start T042
cleo update T042 --notes "Implementing validation logic"
cleo update T042 --notes "Tests passing"

# End of day
cleo complete T042
cleo session end

Single active task enforcement: Only ONE task can be active at a time. This prevents context confusion and scope creep.

Session Notes vs Task Notes

Command	Purpose	Storage
`update T001 --notes "text"`	Task-level progress	Appends to `.tasks[].notes[]`
`update T001 --notes "text"`	Task-specific history	Appends to `.tasks[].notes[]` with timestamp

Session Maintenance (v0.60.0+)

Garbage Collection: Clean up session artifacts and auto-archive inactive sessions.

cleo session gc                     # Full cleanup
cleo session gc --dry-run           # Preview without changes
cleo session gc --verbose           # Detailed output
cleo session gc --orphans           # Clean orphaned context files only
cleo session gc --stale             # Archive old sessions only

Auto-Archive: Sessions inactive for 30+ days are automatically archived during garbage collection. Configure via retention.autoArchiveEndedAfterDays in config.

Output Formats & Exit Codes

LLM-Agent-First Output

All commands output JSON by default. This is the core LLM-Agent-First principle—agents are the primary consumer.

Output Mode	How to Get It	Use Case
JSON (default)	No flags needed	Agent automation, scripting, parsing
Human-readable	`--human` or `--format text`	Developer inspection, debugging

# JSON is always the default
cleo list                    # JSON
cleo list --human            # Human-readable text
cleo list --format text      # Same as --human

Exit Codes

17 documented exit codes for programmatic handling:

Range	Purpose	Examples
`0`	Success	Operation completed
`1-9`	General errors	Invalid input (2), File error (3), Not found (4), Validation (6)
`10-19`	Hierarchy errors	Parent not found (10), Depth exceeded (11), Sibling limit (12)
`20-29`	Concurrency errors	Checksum mismatch (20), Lock timeout (7)
`100+`	Special conditions	No data (100), Already exists (101), No change (102)

cleo exists T042 --quiet
case $? in
  0) echo "Found" ;;
  1) echo "Not found" ;;
  2) echo "Invalid ID format" ;;
esac

Validation & Integrity

Atomic Write Pattern

Every file modification follows this exact sequence:

1. Prepare write operation
2. Validate (schema + anti-hallucination)
3. IF INVALID: Abort → Exit with error
4. IF VALID: Backup → Execute write → Log to audit trail

No partial writes. No corruption. The OS guarantees atomic rename.

Checksum System

# SHA256 checksum of .tasks array
cleo validate           # Check integrity
cleo validate --fix     # Repair checksum mismatches

Checksums detect corruption but don't block multi-writer scenarios (CLI + TodoWrite).

Backup System

Automatic: Safety backup before every write
Rotation: Versioned backups in .cleo/.backups/
Recovery: cleo restore or cleo backup --list

Phase Tracking

Organize work into project phases:

# Define phases
cleo add "Design API" --phase planning --add-phase
cleo add "Implement core" --phase development

# Manage phases
cleo phase set development    # Set current project phase
cleo phase show               # Show current phase details
cleo phases                   # View all phases with progress
cleo phases stats             # Detailed breakdown

# Filter by phase
cleo list --phase core

Phase lifecycle: pending → active → completed (only ONE can be active)

Configuration

Priority Resolution

Values resolved in order (later overrides earlier):

Defaults → Global (~/.cleo/config.json) → Project (.cleo/config.json) → Environment (CLEO_*) → CLI Flags

Key Options

{
  "hierarchy": {
    "maxDepth": 3,
    "maxSiblings": 20,
    "maxActiveSiblings": 8
  },
  "validation": {
    "strictMode": false,
    "checksumEnabled": true,
    "maxActiveTasks": 1
  },
  "archive": {
    "daysUntilArchive": 7,
    "archiveOnSessionEnd": true
  },
  "backup": {
    "enabled": true,
    "maxSafetyBackups": 5
  }
}

Configuration Commands

cleo config show              # View merged configuration
cleo config get hierarchy.maxDepth
cleo config set archive.daysUntilArchive 14
cleo config set --global validation.strictMode true

Environment Variables

CLEO_HOME=/custom/path        # Installation directory
CLEO_DEBUG=1                  # Verbose output
CLEO_FORMAT=json              # Force output format

Project Structure

~/.cleo/                     # Global installation
├── nexus.db                 # Cross-project network: registry, graph, permissions (gated)
├── config.json              # Global CLEO configuration
├── skills/                  # Modular agent skills (14 skills)
│   ├── manifest.json        # Skill registry with versions
│   ├── ct-epic-architect/   # Epic creation skill
│   ├── ct-orchestrator/     # Workflow coordination
│   └── ...                  # 12 more skills
├── templates/               # Starter templates
└── docs/                    # Documentation

your-project/.cleo/          # Per-project instance
├── tasks.db                 # Project work: tasks, sessions, lifecycle, audit (SQLite)
├── brain.db                 # Memory & cognition: observations, patterns, learnings (gated)
├── config.json              # Runtime settings: policies, validation, session behavior
├── project-info.json        # Project identity: projectHash, schema versions, health
├── project-context.json     # LLM agent metadata: language, framework, conventions
└── .backups/                # Automatic versioned backups

Multi-Agent Support

CLEO provides hybrid architecture for broad agent compatibility:

Injection System (Primary - 16+ Agents)

Auto-discovers and injects instructions for all installed agents:

# Initialize project with automatic agent detection
cleo init

# Update existing agent docs to latest version
cleo upgrade

Supported Agents:

Claude (CLAUDE.md)
Generic agents (AGENTS.md)
Gemini (GEMINI.md)
Cursor (cursor_rules)
Windsurf (windsurf_rules)
Aider (CONVENTIONS.md)
Continue (CONVENTIONS.md)
GPT Engineer (CONVENTIONS.md)
Qodo Gen (CONVENTIONS.md)
v0 (v0_instructions.md)
Blackbox (.blackboxrc)
Codeium (codeium_instructions.txt)
CodeGPT (codegpt_rules.md)
And more...

Agent Registry:

Auto-discovers installed agents in ~/.claude/agents/
Uses templates/AGENT-INJECTION.md for project injections
Uses templates/CLEO-INJECTION.md for global agent configs
Full list: cat ~/.cleo/registries/agent-registry.json

Claude Code Plugin (Optional)

For Claude Code users, the optional plugin provides enhanced integration:

# Install with plugin hooks
cleo init --with-plugin

Plugin Features:

Command suggestions in context
Task mention auto-completion
Enhanced command palette integration

Documentation:

Plugin architecture: .claude-plugin/README.md
Global injection: templates/CLEO-INJECTION.md
Project injection: templates/AGENT-INJECTION.md

TodoWrite Sync

Bidirectional sync with Claude Code's ephemeral todo system:

cleo sync --inject              # Push to TodoWrite (session start)
cleo sync --inject --focused-only  # Only push focused task
cleo sync --extract             # Pull from TodoWrite (session end)
cleo sync --extract --dry-run   # Preview changes

Agent Workflow Pattern

# Agent verifies before operating (anti-hallucination)
if cleo exists T042 --quiet; then
  cleo update T042 --notes "Progress update"
else
  echo "ERROR: Task T042 not found" >&2
  exit 1
fi

# Agent parses structured output
ACTIVE=$(cleo list | jq -r '.tasks[] | select(.status=="active") | .id')
cleo update $ACTIVE --notes "Working on task"

# Context-efficient task discovery
cleo find "auth" | jq '.matches[0].id'  # 99% less tokens than list

Skills Architecture (v0.55.0+)

CLEO uses a 2-tier subagent architecture for multi-agent coordination:

Tier	Component	Role
0	ct-orchestrator	HITL coordinator, delegates ALL work
1	cleo-subagent	Universal executor with skill injection

Architecture Reference: See CLEO-SUBAGENT.md for complete documentation.

CLEO includes 14 modular skills for AI agent workflows:

Token Injection System (v0.60.0+)

The token injection system provides validated placeholder replacement for skill templates:

Function	Purpose
`ti_inject_tokens()`	Replace `{{TOKEN}}` placeholders in templates
`ti_validate_required()`	Ensure required tokens (TASK_ID, DATE, TOPIC_SLUG) are set
`ti_set_task_context()`	Auto-populate tokens from CLEO task data
`validate_token_value()`	Validate against enum/path/array/required types

Token validation prevents hallucinated or malformed values from reaching skill templates.

Orchestrator Automation (v0.60.0+)

The orchestrator_spawn_for_task() function consolidates subagent spawning into a single call:

# Programmatic spawning (from lib/orchestrator-spawn.sh)
source lib/orchestrator-spawn.sh
prompt=$(orchestrator_spawn_for_task "T1234")              # Default protocol
prompt=$(orchestrator_spawn_for_task "T1234" "ct-research-agent")  # Specific protocol

# NOTE: All spawns use subagent_type: "cleo-subagent"
# The second argument selects the protocol to inject, not a separate agent type

Automates: task validation, context loading, token injection, template rendering, and prompt generation.

Installed Skills (Protocol Identifiers)

Note: Skills are protocol identifiers, NOT separate agent types. All spawns use a single agent type (cleo-subagent) with the selected skill injected as context. The -agent suffix in some skill names is legacy naming.

Skill Protocol	Purpose
`ct-epic-architect`	Create epics with task decomposition
`ct-orchestrator`	Multi-agent workflow coordination
`ct-docs-lookup`	Documentation search via Context7
`ct-docs-write`	Documentation generation
`ct-docs-review`	Documentation compliance review
`ct-research-agent`	Multi-source research protocol
`ct-task-executor`	Generic task execution protocol
`ct-spec-writer`	Technical specification writing
`ct-test-writer-bats`	BATS test generation
`ct-validator`	Compliance validation
`ct-skill-creator`	Create new skills
`ct-skill-lookup`	Search prompts.chat skills
`ct-library-implementer-bash`	Bash library creation
`ct-documentor`	Documentation orchestration

Skills Installation

Skills are installed as symlinks to ~/.claude/skills/ct-*:

# Install with skills (default)
./installer/install.sh

# Skip skills installation
./installer/install.sh --skip-skills

# Check installed skills
ls ~/.claude/skills/ct-*

Skills Manifest

All skills are tracked in skills/manifest.json:

# View registered skills
cat skills/manifest.json | jq '.skills[].name'

# Check skill versions
cleo upgrade  # Detects and updates skill versions

Orchestrator Protocol (v0.55.0+)

Coordinate multi-agent workflows with the orchestrator command:

# Start orchestrator session
cleo orchestrator start --epic T001

# Get next task to spawn
cleo orchestrator next --epic T001

# Check parallel execution safety
cleo orchestrator check T002 T003 T004

# Analyze dependency waves
cleo orchestrator analyze T001

# Validate protocol compliance
cleo orchestrator validate --epic T001

See Orchestrator Protocol Guide for details.

Extensibility

CLEO supports extension points for custom workflows:

.cleo/validators/           # Custom validation scripts
.cleo/hooks/                # Event hooks (on-complete, on-archive, etc.)
~/.cleo/formatters/    # Custom output formatters
~/.cleo/integrations/  # External system integrations

Event Hooks Example

# .cleo/hooks/on-task-complete.sh
#!/usr/bin/env bash
task_id="$1"
# Send notification, update external tracker, etc.

See docs/PLUGINS.md for extension development.

Troubleshooting

Common Issues

Problem	Solution
`command not found`	Check `~/.local/bin` in PATH, run `source ~/.bashrc`
`Permission denied`	`chmod 755 ~/.cleo/scripts/*.sh`
`Invalid JSON`	`cleo validate --fix` or `cleo restore`
`Duplicate ID`	`cleo validate --fix` or `cleo restore`
`Checksum mismatch`	`cleo validate --fix`
`Multiple active tasks`	`cleo start <correct-id>` (resets others)
`Schema outdated`	`cleo migrate run`

Debug Mode

CLEO_DEBUG=1 cleo list  # Verbose output
cleo --validate                # Check CLI integrity
cleo --list-commands           # Show all available commands

Performance

Target metrics (optimized for 1000+ tasks):

Operation	Target
Task creation	< 100ms
Task completion	< 100ms
List tasks	< 50ms
Archive (100 tasks)	< 500ms
Validation (100 tasks)	< 200ms

Documentation

Category	Documents
Start Here	Quick Start · Design Philosophy
Installation	Installer Architecture · Migration Guide
Reference	Command Index · Quick Reference
Architecture	System Architecture · Data Flows · 2-Tier Subagent
Specifications	LLM-Agent-First Spec · Task ID System · Hierarchy Spec
Integration	Claude Code Guide · CI/CD Integration · Orchestrator Protocol

Complete documentation: docs/INDEX.md

The Philosophy

CLEO is built on five pillars:

1. Portable Memory (BRAIN)

Every project carries its own .cleo/ directory with SQLite databases. Move the directory, and the entire brain moves with it. No cloud dependencies, no vendor lock-in.

2. Agent Communication Contract (LAFS)

JSON output by default. MVI progressive disclosure. Deterministic exit codes. Field filtering for token efficiency. The --human flag is opt-in for developer visibility.

3. Structured Lifecycle (RCASD-IVTR+C)

Every significant piece of work follows a ten-stage pipeline from Research through Release, with gate enforcement and manifest-based provenance.

4. Deterministic Safety

LLMs hallucinate. Four-layer validation (schema, semantic, referential, state machine) prevents every operation from corrupting state. Atomic writes. Immutable audit logs.

5. Cognitive Retrieval (BRAIN + NEXUS)

Three-tier retrieval for token-efficient context loading. FTS5 keyword search, vector similarity, and graph-based discovery — with NEXUS extending across project boundaries.

One developer. One AI agent. One source of truth.

Contributing

Contributions welcome! See CONTRIBUTING.md.

# Run tests
./tests/run-all-tests.sh

# Run specific test suite
./tests/test-validation.sh

# Validate installation
cleo --validate

Star History

License

CLEO is licensed under the Business Source License 1.1.

Free for personal and non-production use
Commercial and production use requires a paid license
Automatically converts to Apache 2.0 on January 26, 2029

See LICENSE for details.

Licensing FAQ

See LICENSING_FAQ.md for details.

Ready to build with your AI agent?
./installer/install.sh && cleo init

Documentation · Design Philosophy · LLM-Agent-First Spec · Contributing

Name		Name	Last commit message	Last commit date
Latest commit History 1,241 Commits
.claude-plugin		.claude-plugin
.cleo		.cleo
.github		.github
agents/cleo-subagent		agents/cleo-subagent
archive		archive
completions		completions
dev		dev
docs		docs
drizzle		drizzle
installer		installer
packages/ct-skills		packages/ct-skills
protocols		protocols
schemas		schemas
src		src
templates		templates
.gitattributes		.gitattributes
.gitbook.yaml		.gitbook.yaml
.gitignore		.gitignore
.gitmodules		.gitmodules
.mcp.json		.mcp.json
.npmrc		.npmrc
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
GEMINI.md		GEMINI.md
LICENSE		LICENSE
LICENSING_FAQ.md		LICENSING_FAQ.md
README.md		README.md
VERSION		VERSION
build.mjs		build.mjs
context7.json		context7.json
drizzle.config.ts		drizzle.config.ts
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts