CLEO: tasks, evidence and memory for coding agents
CLEO
A CLI for AI agents: tasks with acceptance criteria, evidence of done, cross-session memory and docs without duplicates
- 159 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The CLI changes project files, keeps memory and docs and can close tasks and cut a release from changesets
- The release command publishes changes, so run it first with --dry-run
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/cleoDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The CLI changes project files, keeps memory and docs and can close tasks and cut a release from changesets
- The release command publishes changes, so run it first with --dry-run
This is third-party code. Review the repository files before installing.
What it does
CLEO manages an agent's workflow through a single `cleo` command, and every call returns one JSON envelope on stdout, so any agent harness can read it. Work is organised as a tree: a saga, epics and tasks with acceptance criteria and dependencies, and sessions survive interruptions. A task counts as done only when its gates are proven: commits and files, test or CI runs, lint and typecheck, linked to each criterion. A pull request names its tasks with a `Closes: T003 AC1,AC2` line, an independent reviewer records a verdict per criterion, and merging on green CI closes the task. BRAIN memory keeps observations, decisions and lessons and is searchable across sessions, and `cleo briefing` prepares the start of a new session. Separate blocks cover documentation with one canonical home per doc and drift checks, the Nexus symbol graph with edit impact estimates (`cleo nexus impact`), and cutting a release from changesets with one command. The adapters cover Claude Code, Codex, Cursor, Gemini, Kimi, OpenCode and more, and the `ct-*` skills teach an agent the commands.
Who it is for. Developers and teams who hand long projects to agents and want evidence of completion rather than a bare "done".
Good fit when
- A project runs for weeks and the agent loses the thread between sessions, while you need a start-of-session briefing
- The agent reports "done" and you want task closure tied to commits, tests and CI
- The docs folder is turning into a heap of similar documents that agents keep adding to
- A release must be cut from changesets with one command after green CI
Not a fit when
- The task is a couple of files: a saga tree, acceptance criteria and sessions are overkill for a one-off fix
- You only need a code graph: for that alone a dedicated tool such as Arbor is lighter
- The team does not work through pull requests: the main CLEO path is built around them
Example request
Show what to work on next, focus task T003 and remind me which acceptance criteria and evidence it needs.Limitations
CLEO introduces its own concepts (sagas, epics, evidence gates, BRAIN, Nexus) and a process discipline, and learning takes time. Full help lives in `cleo <command> --help` and in the repository docs. Developing the project itself needs Node.js 24.16 or newer and pnpm.
The main path for closing tasks is tied to pull requests and CI. Without a PR there is the `cleo done --plan` variant with manual evidence recording. The repository is very active and versions ship often, so check command details against current help. The license is MIT.
How to disable. Remove the package with npm uninstall -g @cleocode/cleo. Project data lives in the project itself, so delete the folder created by cleo init if you want it gone.
FAQ
How do I start working with CLEO?
Install the package with `npm install -g @cleocode/cleo`, then run `cleo init` and `cleo session start` in the project. Next create a saga (`cleo saga create`), epics and tasks with `cleo add`, and `cleo next` suggests the next step.
What are evidence gates?
Conditions without which a task does not count as done: commits and files, test or CI runs, lint and typecheck. Each is tied to an acceptance criterion. `cleo done <id> --plan` shows which evidence each gate needs.
How does CLEO curb documentation sprawl?
The canonical home of a document is kept in the store, and files in `docs/` are mirrors. Before writing a new page the agent looks for an existing one (`cleo docs query`), and `cleo docs status`, `cleo docs rot` and `cleo docs doctor` show and repair drift.
Does CLEO work without a pull request?
Yes. For tasks without a PR, `cleo done T003 --plan` shows which evidence each gate needs, you record it with `cleo verify`, and `cleo complete T003` closes the task. The normal path still goes through a pull request with a `Closes: T003 AC1,AC2` line.
Which agents are supported?
CLEO returns answers in a single JSON envelope on stdout, so it fits any harness. The adapters package covers Claude Code, Codex, Cursor, Gemini, Kimi, OpenCode and more, and the `ct-*` skills package teaches an agent to use the commands.
Discussion
No questions or reviews yet.
Related
CLI toolsThe ee CLI gives agents durable local memory: rules, decisions and anti-patterns with scores and provenance
A memory and coordination layer for coding agents: specs and issues live in git while agents work in parallel
Compozy runs Claude Code, Codex and Cursor sessions: a task board, scheduled check-ins and a call to you only when needed.
An orchestrator for agents: the workflow is defined in code, every step is enforced, key points need human approval and decisions go into an immutable journal
A CLI that reads local Claude Code, Codex and Hermes sessions, finds repeated failures and stages fixes for manual review
A multi-agent harness that verifies results by artifacts: stop hooks, an independent judge and an event log for Claude Code, Codex, Cursor and more
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| CLEO: tasks, evidence and memory for coding agents (this card) | no | 159 | ||
| Taskmaster | no | not required | 28,354 | PRD-driven task management for agents, without evidence gates or a docs part |
| agentmemory | yes | not required | 30,314 | standalone agent memory with no tasks or releases |
README in short
The README frames CLEO as a work, evidence, memory and docs layer for agents. A table of areas, a quick start, a detailed documentation section, the list of repository packages and development rules cover the rest. The license is MIT.