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

Table of Contents

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

1. 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.
2. Agent Communication Contract (LAFS) — Provider-neutral protocol: JSON envelopes, MVI-tiered progressive disclosure, field filtering, deterministic exit codes.
3. Structured Lifecycle (RCASD-IVTR+C) — Research → Consensus → Architecture Decision → Specification → Decomposition → Implementation → Validation → Testing → Release + Contribution.
4. Deterministic Safety — Four-layer validation (schema, semantic, referential, state machine), atomic writes, immutable audit logs, lifecycle gate enforcement.
5. 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

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/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: query (read) and mutate (write). Each takes a domain, operation, and optional params:

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

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

10 canonical domains, 256 operations (145 query + 111 mutate) across tasks, session, memory, check, pipeline, orchestrate, tools, admin, nexus, and sticky. See the MCP Usage Guide for beginner-friendly walkthroughs.

Source of Truth Hierarchy

1. docs/concepts/CLEO-VISION.md - immutable product vision
2. docs/specs/PORTABLE-BRAIN-SPEC.md - canonical normative contract
3. docs/specs/CLEO-AUTONOMOUS-RUNTIME-SPEC.md - normative mapping for The Hearth through The Proving across existing domains and hooks
4. docs/specs/CLEO-CONDUIT-PROTOCOL-SPEC.md - normative relay contract for Conduit: envelopes, addressing, leases, acknowledgement, retry, and runtime IPC
5. docs/specs/CLEO-AUTONOMOUS-RUNTIME-IMPLEMENTATION-MAP.md - concrete TypeScript vs Rust ownership and IPC boundaries for the autonomous runtime
6. README.md - operational public contract
7. docs/specs/CLEO-STRATEGIC-ROADMAP-SPEC.md - phased execution plan
8. docs/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:

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 (82 unique codes across 13 ranges)
cleo exists T042 --quiet && echo "Found"

Anti-Hallucination Protection

Four layers of validation prevent AI-generated errors:

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: NPM (Recommended)

npm install -g @cleocode/cleo

This automatically bootstraps the global CLEO system:

• Sets up ~/.cleo/ with templates and configuration
• Installs MCP server to detected AI providers (Claude Code, Cursor, etc.)
• Creates ~/.agents/AGENTS.md hub for agent instructions

Then initialize in any project:

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

Option 2: One-liner Bash (Legacy/Offline)

For systems without npm or offline installs:

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

Option 3: From source (Contributors)

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

Then use cleo-dev for isolated development:

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

# Install from npm registry
npm install -g @cleocode/cleo

# Or install specific version
npm install -g @cleocode/cleo@2026.3.10

cd /path/to/your/project
cleo init

# 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

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

# Or download and run manually
bash install.sh

cleo version
cleo env info --json
cleo doctor

# 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

# 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

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

# 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

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

# 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

# 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

# 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'

{
  "$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": [...]
}

{
  "$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

Scope-Based Sizing (No Time Estimates)

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

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.

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

Exit Codes

82 unique exit codes across 13 ranges for programmatic handling:

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)

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

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

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

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 (15 skills)
│   ├── manifest.json        # Skill registry with versions
│   ├── ct-epic-architect/   # Epic creation skill
│   ├── ct-orchestrator/     # Workflow coordination
│   └── ...                  # 13 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, decisions, links (shipped)
├── 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/CLEO-INJECTION.md for global agent injection
• 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

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

# Spawn a subagent for a task (via MCP)
mutate orchestrate.spawn { taskId: "T1234" }
mutate orchestrate.spawn { taskId: "T1234", skill: "ct-research-agent" }

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

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

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

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

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

# 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

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

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

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

Documentation

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