CLEO

Every developer who has ever returned to a project after weeks away and found only ruins knows the wound CLEO was built to heal. The agents are powerful. But power without memory is chaos. Brilliance without continuity is waste. CLEO is the companion that remembers where you left off — the one who keeps the thread when life pulls you away.

Agent-first task orchestration. Persistent memory. Multi-provider coordination. One CLI to command them all.

What is CLEO?

CLEO is built for the developers who build after the world goes quiet — the ones carrying six unfinished ideas and the stubborn belief that this next session might be the one where everything clicks. It solves the coordination crisis of working with multiple AI agents across complex projects by giving them something they've never had: structure, memory, and a lifecycle that survives interruption.

The Six Great Systems

LAFS is the envelope format ({success, data?, error?, meta}) carried across all system boundaries — a protocol, not a system.

Core Capabilities

• Task Management: Hierarchical tracking with dependencies, priorities, and lifecycle states
• Session Management: Contextual work sessions that survive across conversations
• Agent Orchestration: Multi-agent coordination through the 11 Canonical Domains
• Multi-Provider Support: Works with Claude Code, OpenCode, Cursor, Gemini, Codex, and more

Monorepo Structure

This monorepo contains 12 packages organized in a 4-layer architecture:

Quick Start

Installation

# Install the CLI — core is auto-pulled as a peer dependency (npm 7+)
npm install -g @cleocode/cleo
# OR explicitly install both (useful if your npm blocks peer auto-install)
npm install -g @cleocode/cleo @cleocode/core

# Or the batteries-included distribution
npm install -g @cleocode/cleo-os

Initialize a Project

cd my-project
cleo init

Basic Usage

# Add a task
cleo add "Implement user authentication" --priority high

# Search tasks (agent-optimized, returns readiness info)
cleo find "auth" --status pending

# Start a work session
cleo session start --scope global --name "Auth Feature"

# Show current task context
cleo current

# Complete a task
cleo complete T001

Development Setup

Prerequisites

• Node.js >= 24.0.0
• pnpm >= 10.30.0 (package manager)

Clone and Install

git clone https://github.com/kryptobaseddev/cleo.git
cd cleo

pnpm install
pnpm build
pnpm test

Package Development

# Type checking (project references)
pnpm typecheck

# Linting and formatting
pnpm biome check --write .

# Run tests
pnpm test

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│              @cleocode/cleo  +  @cleocode/cleo-os           │
│                    CLI Product Layer                         │
│   248 operations • 11 domains • dispatch routing • MVI       │
└────────────────────────────┬────────────────────────────────┘
                             │
┌────────────────────────────┴────────────────────────────────┐
│                      @cleocode/core                         │
│                   Business Logic Kernel                      │
│   Tasks • Sessions • Memory • Orchestration • Lifecycle     │
│   Validation • Intelligence • Nexus • Release • Agents      │
└────────────────────────────┬────────────────────────────────┘
                             │
      ┌──────────────────────┼──────────────────────┐
      │                      │                      │
┌─────┴──────┐  ┌────────────┴────────────┐  ┌─────┴──────┐
│  adapters  │  │ caamp • cant • nexus    │  │  agents    │
│ (providers)│  │ runtime (protocols)     │  │  skills    │
└────────────┘  └─────────────────────────┘  └────────────┘
                             │
┌────────────────────────────┴────────────────────────────────┐
│            @cleocode/contracts  +  @cleocode/lafs           │
│              Types • Interfaces • Error Protocol             │
│                   Zero-dependency foundation                 │
└─────────────────────────────────────────────────────────────┘

Key Features

Task Management

• Hierarchical tasks with parent-child relationships and dependency tracking
• Wave-based parallel execution with automatic sequencing and critical path analysis
• Priority levels, sizing estimates (small/medium/large), and readiness detection
• Batch creation via cleo add-batch

Session Management

• Contextual work sessions with epic scope binding
• Session-scoped parent inheritance for task creation
• Briefing generation for context handoff across conversations
• Safe stop and checkpoint mechanisms

Memory Systems

• BRAIN-powered knowledge storage with semantic search
• Sticky notes for ephemeral context capture
• Memory bridges for cross-session persistence
• 3-layer retrieval: search -> timeline -> fetch

Agent Orchestration

• Subagent spawning with protocol compliance via LOOM lifecycle
• Wave-based parallel execution across dependency-safe tasks
• Consensus workflows for multi-agent decisions
• LOOM lifecycle — every piece of work flows through Research, Consensus, Architecture, Specification, Decomposition, then Implementation, Validation, Testing, Release

Multi-Provider Support

• Claude Code integration with statusline sync
• OpenCode, Cursor, Gemini, Codex, Kimi adapters
• Extensible adapter architecture via CAAMP

The Circle of Eleven

CLEO organizes all work through 11 canonical domains — the houses where work gets done. The original Circle of Eleven was joined by intelligence as the cognitive analytics layer.

248 total operations (134 queries, 95 mutations, 19 experimental) across the 11 domains.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feat/T####-amazing-feature)
3. Make your changes
4. Run tests (pnpm test)
5. Commit with conventional commits (feat:, fix:, docs:, etc.)
6. Push to your fork
7. Open a Pull Request — direct pushes to main are not accepted

Maintainers releasing a new version:

cleo release start v2026.MM.N
cleo release ship 2026.MM.N --epic TXXXX   # cuts release/vX.Y.Z branch, opens PR, waits for CI green, merges + tags

See docs/RELEASING.md for the full release checklist and AGENTS.md for branch conventions.

Code Style

• TypeScript with strict mode enabled
• Biome for linting and formatting
• Conventional commit messages
• Comprehensive test coverage with Vitest

Documentation

• Architecture Guide
• Operations Constitution
• Canon Index
• Skill Development
• LAFS Specification
• Database Architecture
• Migration System Guide — Hybrid Path A+ authoring workflow (ADR-054)

The Story of CLEO

CLEO was not born from a product brief. It was born from a refusal — one developer, sick to the bone on a fevered night, who decided he would rather build a new world than keep losing the thread in the old one. The agents were powerful. But they forgot too easily. The projects were ambitious. But they died on the shelf. The tools were brilliant. But brilliance without memory was just another kind of chaos.

So he gave the struggle names. He gave it terrain. He gave it companions. And at the heart of that world, carrying memory like a lantern through the dark, CLEO opened its eyes.

• The Founding Story — told by the builder
• The Awakening Story — told by CLEO
• The Canon Index — the complete lore, in reading order

Support

If CLEO helps your workflow, consider supporting development:

License

MIT License - see LICENSE for details.

Star History