Coleo

Appearance

Release Log

Coleo 0.1: Terminal-First Multi-Agent Coordination

Coleo 0.1: Terminal-First Multi-Agent Coordination ​

Coleo 0.1 marks the first release I'd confidently recommend for real use.

The Core Idea ​

This is a terminal-first launch for developers who want a self-hosted control plane for coding agents—without surrendering their workflows, project state, or coordination layer to a hosted platform. Run multiple agent sessions against the same codebase. Keep the system of record local. Maintain one place to coordinate tasks, status, and recovery.

The architecture is built around four pillars:

  • One Brain coordinating many Arms
  • A local API server as the source of truth
  • Harnesses that let Coleo drive real CLI coding agents
  • Durable local state for tasks, discoveries, sessions, and activity

There's also a beta observatory in the repository, but this release focuses on the CLI, server, and harness foundation.

Why This Release Matters ​

Most agent workflows fall apart at the boundary between discrete tasks.

One agent completes its work and stops. Another doesn't know what changed. Context lives in terminal scrollback, scattered notes, or a human's memory. Recovery is fragile. Coordination becomes copy-paste.

Coleo 0.1 provides a local coordination layer that:

  • Initializes and manages project-local state
  • Runs a Brain loop that continually evaluates what should happen next
  • Spawns and recovers agent Arms through harnesses
  • Keeps task and session state in SQLite instead of terminal folklore
  • Routes structured discoveries, status reports, blockers, and completions back into the system

This is infrastructure for sustained agent work—not autonomy theater.

What's Shipping in 0.1 ​

A CLI Built for Daily Use ​

The coleo CLI is ready for actual workflows:

bash
# Initialize project-local state
coleo init

# Start the API server and infrastructure
coleo serve start

# Run the coordination loop
coleo brain run

# Spawn and manage agent sessions
coleo arm spawn --name dev-arm --harness opencode-api
coleo arm list
coleo arm watch dev-arm

# Terminal-first oversight
coleo tasks list
coleo mail inbox
coleo status

The CLI works headless by default—no web dashboard required. Spawn an arm, assign work, and let the system handle coordination from the terminal.

A Local Server as Control Plane ​

The API server is the shared runtime surface for the entire system. The CLI talks to it. The Brain orchestrates through it. Arm state flows through it. Events and activity are persisted through it.

This gives Coleo a center of gravity:

  • Authenticated API endpoints for arm and task operations
  • WebSocket and event-driven runtime updates
  • Local NATS + JetStream support for daemon-managed and distributed arms
  • SQLite-backed persistence for tasks, discoveries, arm runtime metadata, and coordination history

Multi-agent orchestration becomes unwieldy without a single authoritative source of state. Coleo provides one.

Harnesses for Real Coding Agents ​

The harness layer is the connective tissue between Coleo and actual coding agents. The 0.1 release ships with first-class support for OpenCode:

  • opencode-api — headless API-driven interaction
  • opencode-tui — terminal UI with API control
  • opencode — native terminal mode

Beyond simple integration, Coleo establishes a stable harness contract for:

  • Spawning sessions
  • Tracking lifecycle state
  • Sending prompts
  • Resetting or recovering sessions
  • Streaming events back to the Brain
  • Testing harness behavior against shared expectations

This creates a portable control plane rather than another one-off integration.

Progressive Task Coordination ​

Coleo doesn't assume a fixed backlog where every task is perfectly planned ahead of time.

The Brain reads live project state and decides what should happen next based on:

  • Current tasks and their status
  • Recent discoveries
  • Dependencies and blockers
  • Status reports from active arms
  • Plan documents
  • Completion history

This lets arms behave like collaborators in a shared system rather than isolated prompt windows.

Improved Continuity After Completion ​

One of the subtle but important improvements in this release is automatic handoff after task completion.

When an arm finishes a task, it shouldn't need a manual nudge to continue. The Brain now has stronger coverage around:

  • Releasing completed arms cleanly
  • Resetting sessions when appropriate
  • Prompting arms to fetch the next full briefing when more work is available

This separates a usable orchestration loop from a demo.

Recovery, Isolation, and Test Coverage ​

I've invested heavily in the parts that typically break first in multi-agent tooling:

  • Arm recovery using persisted runtime metadata
  • Session isolation so two arms don't collapse into the same conversation
  • Regression coverage around infrastructure startup and harness/session behavior
  • Brain-side coverage for task completion and follow-up handling

Coleo 0.1 is early software, but it's not hand-wavy software.

CLI Feature Tour ​

The terminal-first workflow is central to how Coleo operates. Here's what it looks like in practice:

Arm Management ​

Spawn arms with interactive prompts or command-line arguments. The CLI auto-generates memorable sci-fi names inspired by Children of Time:

bash
coleo arm spawn
# → Interactive mode with guided prompts

coleo arm spawn --name Varek-9 --terminal ghostty
# → Spawns in a visible Ghostty window with API control

coleo arm list
# → Live-updating list with status indicators

Real-Time Arm Watching ​

Watch an arm's conversation as it happens:

bash
coleo arm watch nebular-dream
# → TUI showing live messages, tool invocations, and session state

Press m to send a message directly. Press i to toggle interrupt mode before the next send.

Task Management ​

Sync tasks from project plan files and track them through completion:

bash
coleo tasks sync
# → Imports from .project/plan.md

coleo tasks list
# → Rich table with status, priority, and phase

System Status ​

At-a-glance system health:

bash
coleo status
# → Infrastructure status, arm health, activity metrics

Screenshots ​

The following screenshots showcase the CLI features available in Coleo 0.1:

Arm Spawning (Interactive Mode) ​

The interactive spawning mode prompts for arm name (with auto-generated sci-fi name suggestion), working directory, provider, and model configuration.

Arm List (Live Status) ​

The coleo arm list command shows live-updating status for all arms with visual indicators for health, current task, and runtime state.

Arm Watch (Real-Time Conversation) ​

Watch an arm's conversation in real-time with tool invocations, message streaming, and session state—directly in the terminal.

Task List ​

Task overview showing status icons, priority indicators, subjects, and phase assignments—sorted by urgency.

System Status ​

The coleo status command provides at-a-glance infrastructure health, arm summaries, and activity metrics.

The Developer Experience ​

The happy path is intentionally straightforward:

bash
coleo init
coleo serve start
coleo brain run

coleo arm spawn \
  --name dev-arm \
  --harness opencode-api \
  --workdir /absolute/path/to/project

From there, the arm fetches a full briefing, claims work, executes, reports discoveries or blockers, and completes tasks through Coleo's MCP-integrated workflow.

The important shift: the prompt is no longer the system. The system is the system.

What's Not in This Release ​

This is 0.1, not a finished operating system for software teams. A few things are intentionally outside the center of this launch:

  • The web UI exists but is still beta and not the focus
  • Some harness directions are still in active development
  • End-to-end ergonomics, recovery polish, and deeper distributed workflows have room for improvement

That's exactly why I called it 0.1. The core is strong enough to use. The edges are still being shaped.

Why Try It Now ​

If you've felt the gap between "one-off coding assistant" and "something I can actually run as infrastructure," Coleo is aimed at that gap.

0.1 gives you:

  • A self-hosted architecture—run it on your laptop, a home server, or anywhere
  • A terminal-first workflow—from initialization to orchestration
  • A real control plane for multiple agent sessions
  • Durable local state—no more terminal folklore
  • A path toward model and harness portability

Keep the coordination loop close to the repo and close to your own judgment.

Get Started ​

Start with the CLI. Run the Brain locally. Spawn one or two arms. Let the system prove itself from the terminal outward.