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