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.
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.
| System | Purpose |
|---|---|
| BRAIN | Memory that does not decay — observations, patterns, and learnings persisted across sessions with semantic search |
| LOOM | The lifecycle that governs all work — 9-stage RCASD-IVTR+C pipeline from idea to shipped release |
| NEXUS | The network between projects — cross-repo coordination, shared patterns, federated intelligence |
| LAFS | The common tongue — every response wrapped in a structured envelope that any LLM provider can parse |
- 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 Circle of Ten domains
- Multi-Provider Support: Works with Claude Code, OpenCode, Cursor, Gemini, Codex, and more
This monorepo contains 11 packages organized in a 4-layer architecture:
| Layer | Package | Purpose |
|---|---|---|
| Foundation | @cleocode/contracts |
Domain types, interfaces, and contracts — zero-dependency type SSoT |
| Foundation | @cleocode/lafs |
Language-Agnostic Feedback Schema — canonical error envelope protocol |
| Protocol | @cleocode/adapters |
Provider adapters for Claude Code, OpenCode, Cursor, Gemini, Codex, Kimi |
| Protocol | @cleocode/agents |
Subagent templates and LOOM lifecycle protocol definitions |
| Protocol | @cleocode/skills |
Pre-built skills and capabilities for development workflows |
| Protocol | @cleocode/cant |
CANT protocol parser with napi-rs Rust binding |
| Feature | @cleocode/caamp |
Central AI Agent Managed Packages — unified provider registry and MCP management |
| Feature | @cleocode/runtime |
Long-running process layer (polling, SSE, heartbeat) |
| Kernel | @cleocode/core |
Business logic SDK — tasks, sessions, memory, orchestration, lifecycle |
| Product | @cleocode/cleo |
Command-line interface — thin wrapper over core |
| Product | @cleocode/cleo-os |
Batteries-included distribution with CANT bridge and TUI extensions |
# Install globally for CLI access
npm install -g @cleocode/cleo
# Or the batteries-included distribution
npm install -g @cleocode/cleo-oscd my-project
cleo init# 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- Node.js >= 24.0.0
- pnpm >= 10.30.0 (package manager)
git clone https://github.com/kryptobaseddev/cleo.git
cd cleo
pnpm install
pnpm build
pnpm test# Type checking (project references)
pnpm typecheck
# Linting and formatting
pnpm biome check --write .
# Run tests
pnpm test┌─────────────────────────────────────────────────────────────┐
│ @cleocode/cleo + @cleocode/cleo-os │
│ CLI Product Layer │
│ 89 commands • dispatch routing • output formatting │
└────────────────────────────┬────────────────────────────────┘
│
┌────────────────────────────┴────────────────────────────────┐
│ @cleocode/core │
│ Business Logic Kernel │
│ Tasks • Sessions • Memory • Orchestration • Lifecycle │
│ Validation • Intelligence • Nexus • Release • Agents │
└────────────────────────────┬────────────────────────────────┘
│
┌──────────────────────┼──────────────────────┐
│ │ │
┌─────┴──────┐ ┌────────────┴────────────┐ ┌─────┴──────┐
│ adapters │ │ caamp • cant • runtime │ │ agents │
│ (providers)│ │ (protocols & features) │ │ skills │
└────────────┘ └─────────────────────────┘ └────────────┘
│
┌────────────────────────────┴────────────────────────────────┐
│ @cleocode/contracts + @cleocode/lafs │
│ Types • Interfaces • Error Protocol │
│ Zero-dependency foundation │
└─────────────────────────────────────────────────────────────┘
- 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
- 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
- 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
- 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
- Claude Code integration with statusline sync
- OpenCode, Cursor, Gemini, Codex, Kimi adapters
- Extensible adapter architecture via CAAMP
CLEO organizes all work through ten canonical domains — the houses where work gets done:
| Domain | House | What Happens Here | Key Commands |
|---|---|---|---|
tasks |
The Smiths | Work is forged — create, track, complete | add, find, show, complete, deps, tree |
session |
The Scribes | The living present — context that survives | start, end, resume, briefing, checkpoint |
memory |
The Archivists | Knowledge that does not decay | observe, memory-brain, sync, sticky |
check |
The Wardens | Integrity stands guard | validate, verify, compliance, doctor |
pipeline |
The Weavers | The lifecycle threads forward | release, lifecycle, phases, promote |
orchestrate |
The Conductors | Agents move in concert | orchestrate, consensus, contribution, dash |
tools |
The Artificers | Capabilities are crafted | skills, providers |
admin |
The Keepers | The realm stays healthy | config, backup, migrate, grade |
nexus |
The Wayfinders | Projects find each other | nexus, remote, push, pull, snapshot |
sticky |
The Catchers | Quick capture before the thought escapes | sticky |
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests (
pnpm test) - Commit with conventional commits (
feat:,fix:,docs:, etc.) - Push to your fork
- Open a Pull Request
- TypeScript with strict mode enabled
- Biome for linting and formatting
- Conventional commit messages
- Comprehensive test coverage with Vitest
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
If CLEO helps your workflow, consider supporting development:
MIT License - see LICENSE for details.