Introduction to CLEO

CLEO is a task management system designed for AI coding agents and solo developers with anti-hallucination validation

Introduction to CLEO

CLEO (Command Line Entity Orchestrator) is a task management system designed specifically for AI coding agents and solo developers. It provides enterprise-grade reliability with a focus on preventing AI-generated errors from corrupting your workflow data.

Anti-Hallucination

Every operation is validated before execution with multi-layer checks

Context Persistence

State maintained across sessions with immutable audit trails

Structured Output

JSON by default for agent consumption, human-readable when needed

Atomic Operations

All writes use temp file → validate → backup → rename pattern

Why CLEO?

Traditional task management tools weren’t designed for AI-assisted development workflows. CLEO addresses three critical challenges:

AI Hallucination Prevention

AI agents can generate syntactically valid but semantically incorrect data. CLEO’s multi-layer validation ensures:

• Schema validation at every write
• Cross-file integrity checks
• Semantic validation (no future timestamps, valid status transitions)
• Duplicate detection

Session Continuity

Development work is rarely linear. CLEO provides:

• Complete audit trails in todo-log.json
• Automatic backups before every modification
• Session management with start/end protocols
• Focus tracking for single-task discipline

Agent-First Design

Built for LLM agents from the ground up:

• JSON output by default (detects TTY vs piped)
• Exit codes for programmatic handling
• Structured error messages with fix suggestions
• Command discovery via cleo commands

Core Concepts

Tasks and Hierarchy

CLEO organizes work into a three-level hierarchy:

Epic (large scope) → Task (unit of work) → Subtask (atomic piece)

Creating Tasks

# Simple task
cleo add "Fix login bug"

# Task with hierarchy
cleo add "Auth System" --type epic --size large
cleo add "JWT Middleware" --parent T001 --type task
cleo add "Token Validation" --parent T002 --type subtask

Managing Tasks

# View tasks
cleo list
cleo list --tree          # Hierarchical view

# Complete task
cleo complete T003

# Update with notes
cleo update T001 --notes "Implemented base auth"

Sessions and Focus

CLEO enforces single-task discipline through focus management:

# Start your day
cleo session start
cleo focus set T001          # One active task at a time

# Work on task...
cleo focus note "Making progress on auth"

# End your day
cleo archive                 # Clean up completed tasks
cleo session end

Sessions persist across Claude conversations. When you start a new terminal session, resume with cleo session resume.

Data Files

CLEO maintains four core data files in your project’s .cleo/ directory:

File	Purpose
todo.json	Active tasks (source of truth)
todo-archive.json	Completed/archived tasks
todo-log.json	Immutable audit trail
config.json	Project configuration

Quick Example

# Initialize CLEO in your project
cd /path/to/your/project
cleo init

# Add your first task
cleo add "Implement user authentication" \
  --priority high \
  --labels backend,security \
  --description "Add JWT-based auth with refresh tokens"

# Set focus and start working
cleo focus set T001

# Track progress
cleo update T001 --notes "Completed JWT signing implementation"

# Complete when done
cleo complete T001

# View project status
cleo dash

Next Steps

Quick Start

Get up and running in 5 minutes

Installation

Detailed installation instructions

Project Management Guide

Learn epic/task/subtask organization

Command Reference

Complete CLI documentation