@cleocode/cleo-os

CleoOS

The batteries-included agentic development environment. One developer. Many agents. One operating system for the work.

CleoOS wraps Pi — Mario Zechner's open-source coding agent — with CLEO's governance layer: task memory, lifecycle gates, multi-agent coordination, and the CANT DSL. Install once, get both.

Quick Start

npm install -g @cleocode/cleo-os
cleoos

That's it. CleoOS installs Pi automatically. The cleoos command launches Pi with CleoOS extensions pre-loaded. The cleo CLI is also available for task management, memory, and lifecycle operations.

If You're...

Goal	Start here
New to AI coding agents	The Hearth — what you see when you run cleoos
Already using Pi	What CleoOS Adds — the extensions Pi doesn't have
Comparing tools	Why CleoOS — how it differs from Claude Code, Cursor, Copilot

Why CleoOS

AI coding agents can write code. What they cannot do is sustain a project across days, agents, and context windows. Each session starts fresh, forgets last week's architectural decision, and has no idea which tasks are blocked or why. The result: impressive demos, fragile projects.

CleoOS adds the missing layer. BRAIN persists memory across every session so agents never rediscover the same facts twice. The CANT DSL defines agent roles, permissions, and mental models in a checked-in file so governance is reproducible. The three-tier hierarchy gives leads the authority to coordinate without giving them the power to cause chaos, and gives workers a constrained domain where they can operate confidently.

The key differentiator is enforcement. Many tools describe role hierarchies. CleoOS enforces them at the tool_call hook level inside Pi: lead agents literally cannot execute Edit, Write, or Bash, and worker agents cannot write outside their declared file paths. There is no workaround because the hook runs before Pi dispatches the tool call.

Pi provides excellent single-agent coding capability — a well-designed TUI, solid model integration, and a stable extension API. CleoOS is not a competitor. It is the governance shell that makes Pi production-ready for multi-agent workflows.

The Five Named Powers

CleoOS is built on CLEO's five named powers. Each maps to a concrete runtime system:

Power	What It Does
CLEO	Governs continuity, routing, and system action across all sessions
BRAIN	Stores durable project knowledge — observations, decisions, patterns, learnings
LOOM	Enforces order of operations through the RCASD-IVTR+C lifecycle
NEXUS	Connects projects without merging them — cross-project registry
LAFS	Standardizes outputs for tools and agents — progressive disclosure protocol

CAAMP is the provisioning ally: it equips the realm with provider configs, skills, and injected instructions. See the CLEO World Map for the full narrative behind each power.

The Hearth

The Hearth is what you see when you run cleoos. It is Pi's terminal UI with CleoOS extensions loaded automatically:

• CANT bridge — reads .cleo/cant/*.cant files and injects agent personas, tool ACLs, and mental model preambles into the Pi session at startup. Compiles CANT DSL to system prompt injection transparently.
• Chat room widget — a below-editor panel that shows the last 15 inter-agent messages in real time. Messages arrive from other agents in the current worktree via conduit.db or api.signaldock.io. The chat room is a TUI view — it is not itself a messaging transport.
• Status line — shows the current agent tier, role name, and active task context pulled from BRAIN on spawn.

The Hearth is the operator surface. Conduit is the agent relay below it.

The Three-Tier Hierarchy

The three-tier hierarchy is the headline feature of CleoOS. It brings structure to multi-agent projects by giving each tier distinct powers and hard constraints enforced at runtime.

Orchestrator (you, or /cleo:auto <epicId>)
    │
    ├── Engineering Lead (thinker, NEVER executes)
    │   ├── backend-dev   (worker, writes code)
    │   ├── frontend-dev  (worker, writes code)
    │   └── qa-engineer   (worker, writes tests)
    │
    ├── Validation Lead
    │   ├── security-reviewer (worker, audits)
    │   └── doc-writer        (worker, writes docs)
    │
    └── Release Lead
        └── release-manager   (worker, ships)

Tier Capabilities

Tier	Role	Power	Hard Constraint
Orchestrator	Runs the Conductor Loop (/cleo:auto <epicId>)	Full system access	HITL boundary — user approves epic-level decisions
Lead	Coordinates a worker group, reviews output, delegates	Read + think + delegate	CANNOT execute Edit, Write, or Bash — no exceptions
Worker	Executes concrete code changes within a declared domain	Read + write within domain	Path ACL: permissions.files: write[glob] — cannot write outside glob

Enforcement (shipped in Wave 7b)

Enforcement runs at the Pi tool_call hook level. When a lead agent attempts to call Edit, Write, or Bash, the hook intercepts the call before Pi dispatches it and returns a rejection. When a worker agent attempts to write to a path outside its declared glob pattern, the same hook rejects the call. There is no workaround at the agent level.

Teams are defined in .cleo/teams.cant:

team engineering-lead {
  role: lead
  workers: [backend-dev, frontend-dev, qa-engineer]
}

team backend-dev {
  role: worker
  permissions {
    files { write ["packages/core/**", "packages/contracts/**"] }
  }
}

Wave Status

Feature	Status
Lead tool blocking (Edit/Write/Bash rejected for role: lead)	Wave 7b shipped
Worker path ACL (permissions.files: write[glob] enforced)	T422-T426 shipped
.cleo/teams.cant definition format	Wave 0 shipped
Model tier routing (low/mid/high per tier)	Grammar shipped, router in progress
JIT agent composition (spawn team from task type)	Library exists, not wired to spawn path

Conduit — Agent Communication

Conduit is CLEO's agent-to-agent communication layer, structured in four concentric shells. Each shell handles a different scope of agent communication.

Shell 1 — Pi Native (free, built-in)

Orchestrator-to-lead-to-worker communication inside a single session. Pi handles parent/child relay automatically via its JSONL subagent-link. No CLEO infrastructure needed. Zero latency. Zero cost.

Shell 2 — conduit.db (shipped v2026.4.12)

Per-project local messaging in SQLite at .cleo/conduit.db. Provides messages, conversations, delivery queue, and dead-letter handling. Used when agents communicate across sessions or hand off state between orchestrator runs on the same machine. Also holds project_agent_refs — per-project agent visibility overrides that layer on top of the global identity registry.

Shell 3 — signaldock.io Cloud (shipped)

Cross-machine and cross-project agent coordination via the signaldock-sdk Rust crate against api.signaldock.io. Four services: AgentService, MessageService, ConversationService, DeliveryOrchestrator. TypeScript reaches the cloud tier via HttpTransport (polling) or SseTransport (real-time EventSource). Used when a fleet of agents spans multiple machines or CI environments.

Shell 4 — Durable Broker (planned)

The CLEOOS-VISION message bus with Rust broker, TypeScript semantics, lease-based delivery, and dead-letter queue. Deferred until cross-worktree durability is required by real workflows.

Note: The Chat Room (cleo-chatroom.ts) is a TUI view under The Hearth, not a Conduit shell. It gives the operator visibility into inter-agent messages. Messages displayed in the chat room flow through conduit.db or signaldock.io — the chat room itself is only a renderer.

What CleoOS Adds to Pi

Capability	How	Source
CANT bridge	Injects agent personas from .cleo/cant/*.cant into Pi sessions at startup. Compiles CANT to system prompt injection.	extensions/cleo-cant-bridge.ts
Lead tool blocking	tool_call hook rejects Edit/Write/Bash for role: lead agents	Wave 7b
Worker path ACL	tool_call hook enforces permissions.files: write[glob] per worker	T422-T426
Mental model injection	Fetches prior observations from BRAIN on spawn, injects validate-on-load preamble	Wave 8
Chat room TUI	4 inter-agent tools + below-editor widget showing last 15 messages	Wave 7
XDG-compliant paths	All CleoOS state under ~/.local/share/cleo/ (Linux), ~/Library/Application Support/cleo/ (macOS)	src/xdg.ts
Pi keystore redirect	Pi credentials stored at ~/.config/cleo/auth/auth.json instead of Pi's default	src/keystore.ts
Postinstall scaffolding	Creates XDG dirs, deploys extensions, scaffolds model-routing.cant stub, installs CLEO skills	src/postinstall.ts

Database Topology

CleoOS maintains five databases across two tiers per ADR-036 and ADR-037.

Project Tier (.cleo/)

Database	Purpose
tasks.db	Task hierarchy, sessions, audit log, lifecycle pipelines
brain.db	Observations, patterns, learnings, decisions (FTS5 searchable)
conduit.db	Agent messaging, delivery queue, project_agent_refs

Global Tier ($XDG_DATA_HOME/cleo/)

Database	Purpose
nexus.db	Cross-project registry, federated queries
signaldock.db	Canonical agent identity, cloud-sync tables

Plus: global-salt (32-byte machine-bound key for API key derivation), machine-key, extensions/, and cant/ directories for globally installed CANT files.

Installation

# One command installs both CleoOS and Pi
npm install -g @cleocode/cleo-os

# Verify
cleoos --version
cleo version

What Gets Installed

• cleoos binary — launches Pi with CleoOS extensions pre-loaded
• cleo binary — CLEO CLI (90+ commands across 10 canonical domains)
• @mariozechner/pi-coding-agent — Mario Zechner's open-source AI coding agent
• XDG directory structure at ~/.local/share/cleo/
• Default CANT stubs and skill files

Requirements

• Node.js >= 24.0.0
• An AI provider API key (set via cleoos on first run, stored in ~/.config/cleo/auth/auth.json)

Architecture

+-----------------------------------------------------------+
|                   @cleocode/cleo-os                       |
|  (CleoOS — batteries-included Pi wrapper)                 |
|                                                           |
|  +------------------------+  +------------------------+   |
|  | extensions/            |  | extensions/            |   |
|  | cleo-cant-bridge.ts    |  | cleo-chatroom.ts       |   |
|  | (CANT compile,         |  | (4 tools, TUI widget,  |   |
|  |  ACL enforcement,      |  |  JSONL relay,          |   |
|  |  mental model inject)  |  |  not a Conduit shell)  |   |
|  +------------------------+  +------------------------+   |
|  src/cli.ts         <- cleoos launcher                     |
|  src/postinstall.ts <- XDG scaffolding                     |
+-----------------------------------------------------------+
        |
        v (direct dependency)
+-----------------------------------------------------------+
|             @mariozechner/pi-coding-agent                 |
|  TUI, model providers, session management,                |
|  extension API, tool execution, subagent spawn            |
+-----------------------------------------------------------+
        |
        v
+-----------------------------------------------------------+
|                   @cleocode/cleo                          |
|  CLI (90+ commands), dispatch registry,                   |
|  LAFS envelopes, 10 canonical domains                     |
+-----------------------------------------------------------+
        |
        v
+-----------------------------------------------------------+
|                   @cleocode/core                          |
|  Tasks, sessions, memory, orchestration,                  |
|  lifecycle, validation, backup, conduit                   |
+-----------------------------------------------------------+
        |
        v
+-----------------------------------------------------------+
|             SQLite (node:sqlite via Drizzle ORM)          |
|  tasks.db   brain.db   conduit.db   nexus.db              |
|  signaldock.db                                            |
+-----------------------------------------------------------+

Startup Migration Verify

CleoOS runs a migration verify pre-check every time cleoos starts — before Pi is imported and before any workers are dispatched. This prevents agents from running against a drifted database and producing confusing mid-session errors.

How It Works

cleoos invokes cleo upgrade --diagnose --json via subprocess (CLI boundary — no direct imports from @cleocode/core). The result is classified into three severity levels:

Severity	Condition	Action
ok	All 5 DB findings are status:"ok"	Silent pass-through
warn	One or more findings are status:"warning"	Logged to stdout; startup continues
fatal	One or more findings are status:"error", OR the cleo binary could not be invoked	Structured error printed to stderr; startup halts (exit 2)

warn corresponds to states the reconciler already auto-fixed (e.g. a missing column that was backfilled, or signaldock.db not yet created). fatal corresponds to states the reconciler could not resolve — a missing migration folder, a schema missing a required table, or an unreachable cleo binary.

Operator Remediation

When CleoOS exits with code 2 and prints a fatal drift error:

CleoOS startup blocked — DB migration drift detected
═══════════════════════════════════════════════════════════

The following issues prevent safe worker spawn:

  [FATAL] tasks.db.journal
          Migration folder missing: .cleo/migrations/tasks does not exist
          Fix: Run: cleo init or cleo upgrade

Try these remediation steps in order:

• cleo upgrade — applies pending migrations and repairs known drift.
• cleo upgrade --diagnose — detailed DB inspection showing every check.
• cleo init --force — resets tasks.db to a fresh state. Warning: this destroys all task data. Run cleo backup add first if possible.
• cleo restore backup --file tasks.db — restore from the most recent snapshot if the DB is corrupted.

Bypassing the Check (CI / Test Harnesses)

Set CLEO_SKIP_MIGRATION_CHECK=1 to skip the check entirely. This is intended for CI environments where the DB is freshly initialised by the test harness and no persistent CLEO state exists:

CLEO_SKIP_MIGRATION_CHECK=1 cleoos --version

Dedicated Verb (Future)

The current implementation falls back to cleo upgrade --diagnose --json because cleo admin migrations verify does not yet exist. When that verb lands, the verifyMigrations() function will be updated to prefer it. MigrationVerifyResult.usedDedicatedVerb will flip to true.

Wave Roadmap

CleoOS ships in named waves. Each wave targets a vertical slice of the platform.

Wave	Title	Status	Key Deliverable
0	CANT Grammar	Shipped	team, tool, mental_model document kinds
2	CANT Bridge MVP	Shipped	cleo-cant-bridge.ts — compile + inject at session_start
3	Launcher + Install	Shipped	cleoos binary, postinstall, XDG hub
7	Chat Room + Hierarchy	Shipped	4 inter-agent tools, TUI widget, 3-tier enforcement
7b	Lead Tool Blocking	Shipped	Edit/Write/Bash blocked for role: lead
8	Mental Model Injection	Shipped	validate-on-load from BRAIN on agent spawn
ACL	Worker Path ACL	Shipped	permissions.files: write[glob] enforcement
1	Render Pipeline	Partial	Rust stubs exist, no cant render CLI verb yet
4	Lifecycle Codegen	Partial	.cant files exist, stages.ts connection missing
5	JIT Agent Composer	Partial	Library shipped, not wired to spawn path
6	Model Router	In progress	Rust classifier crate exists
9	Three-Tier CANT Resolution	Not started	Global/user/project .cant file hierarchy

References

• CLEO World Map — the founding myth and system vocabulary
• CleoOS Vision — the long-term vision document
• ADR-035 — Pi as primary harness
• ADR-036 — database topology
• ADR-037 — conduit/signaldock split
• Pi Coding Agent — the upstream agent CleoOS wraps

License

MIT