Cacophony · caco

Conduct a swarm of coding agents.

Every repository gets one task board, one message bus and one lifecycle controller. Agents on any of your machines claim work, build in their own checkouts, prove it with queued tests and land through the same gate — while you steer from a terminal, a browser, a phone or your wrist.

Quickstart How it fits together CLI reference →

104: commands in one caco binary, each also an MCP tool
8: agent runtimes, from Claude Code and Codex to Pi and Pico
113: composable agent profiles in this repository
5: reintegration modes, from squash merge to PR auto-merge

Terminal dashboard showing the lighthouse project's bead board with priorities, assignees and labels

The Android app's chat, with agents reporting progress and code in a message

Every change follows the same score.

FileA bead: one claimable task with a priority and dependencies.caco bd create
DispatchClaim and spawn in one step, on a node with capacity; a retry never spawns twice.caco bd dispatch
WorkIts own branch and checkout, in Herdr or tmux, shaped by a profile.caco agent attach
ProveTests and builds queue per project with durable retry keys.caco test run
LandSquash to main or open a PR that auto-merges behind CI — or refuse.caco agent complete
RecordA session summary and feed trail, searchable later.caco summaries

The same fleet, wherever you are.

Terminal dashboard

Every node, project and agent in one keyboard-driven tree.
Split tiles, tabs and saved views; open any agent's live terminal.
Kitty and Ghostty graphics: image backgrounds, GPU borders, inline previews.

caco tui caco chat caco inbox

TUI guide →

Web dashboard

Status, agents, beads, chat, inbox, flows, nodes and stats.
Command palette, keyboard help and a resizable workspace.
Nine themes, from Aurora to e-ink and high contrast.
Also a desktop app on Linux and macOS, plus a native macOS app.

caco web caco ui

Web guide →

Structured agent session showing the operator's request, the agent's reasoning, a test run and its reply

Structured sessions

Pico drives Pi over JSON-RPC: messages, thinking and tool calls as structured events.
One shared core renders the session in the TUI, browser, Android and Apple apps.
Drop to the raw terminal whenever you want.

caco pico caco agent attach --raw

Picophony →

The Android app's agent list, grouped by project with state and attention filters

The iPhone app's project chat, with agents reporting progress

Wear OS chat on a round watch, showing an agent's latest message

In your pocket

Android with Wear OS, and iPhone with Apple Watch.
Answer choices, file beads and reply to agents from a notification or your wrist.
Live terminals and structured sessions on the phone; cached state while reconnecting.
Pictured: Android, iPhone and Wear OS. The browser dashboard adapts to small screens too.

Phone & watch →

# file, place and watch work
caco bd create "Retry flaky uploads" --type bug --priority 1
caco bd dispatch --bead-id bd-a00007 --node vega
caco agent attach --id "$AGENT"

# prove and land it
caco test run --auto --wait
caco agent complete --id "$AGENT"

# any command, on any node, as JSON
caco @all status
caco bd list --status open --json
caco bd list --help --json

One binary, every surface

Each command answers --help --json and emits stable JSON.
MCP tools are generated from the same command metadata.
13 Claude-compatible plugins, one per command family.
@node, @node1,node2 and @all route any command.

MCP integration →

Many machines, one fleet.

A daemon per machine: loopback HTTP locally, mutual TLS between nodes.
One board: one authoritative bead store, warm standbys, voted failover.
Shared memory: feed, messages, agents and summaries replicate to every node.
Elastic: Codespaces and AKS pools join as nodes or transient compute.

Networking & security →

caco @vega agent list runs on vega; caco @all update fans out in parallel.

Bring your own agents.

claude
codex
pi
pi-paratenic
pico
pi-on-demand
pico-on-demand
pi-daemon

Profiles: a Markdown prompt plus MCP servers, hooks, scope and landing policy, composed in order.
Persistent agents: controllers and narrators the daemon keeps alive and wakes on a heartbeat.
Dormant sessions: workspace and conversation kept, no process until something wakes them.

Agent profiles →

Terminal agent table: a Pi project controller plus Pi, Pico, Claude and Codex workers across three nodes

Bead bd-a00008, in progress at priority 1 and assigned to the wren agent

Stay in the loop without watching it.

Choices and decisions: urgent questions with a default, or batched for later; answer from any surface.
Voice: agents speak with their own chime and stereo position; solo, mute or answer by voice.
Chat: per project, group or agent.
Summaries: every session's goal, before and after, searchable with caco search.

Messaging → · Speech →

Inbox with a release sign-off, a direct message and an agent's choice about a database migration

Compose agents into typed flows.

Agent, action and nested-flow nodes joined by typed ports, in .cacophony/flows.
Compiled and validated before anything runs.
Durable runs that suspend for review, stop and resume.
Cron and feed triggers pinned to a reviewed revision.

The example flow lighthouse.triage: the typed input request goes to collect, a configured action pinned to node vega, which returns a list of error groups. A map edge fans the list out to up to three ephemeral fix agents at once, one per group, and gathers their results into a list for review. Review is an action that suspends: it sends a request to the Operator Inbox and waits up to three days for a decision, then emits a checkpointed summary and a Markdown report artifact.

caco flow validate caco flow run How flows work

Nothing lands by accident.

Land by

direct: Squash-merge in an isolated integration checkout. Publish or refuse; the agent's checkout is never rewritten.
pr_reviewpr_auto_merge: Open a pull request under the project's own GitHub identity, for review or auto-merge.
pr_submit: Publish one ready pull request per bead and stop.
artifact_only: Record the branch and commits without merging anything.

Guarded by

Preservation refs: Stopping an agent first pushes its exact head to a recovery ref.
Scoped tokens: Workers, project controllers and cluster controllers carry different authority.
Loud blockers: A failed completion blocks its owner on a typed error until the owner's retry succeeds. caco agent status
Required checks: Branch protection merges a pull request only after its required CI checks pass.

Reintegration policy →

Try it on a real task.

01Hand a task to an agent
File a bead, place a worker, land its branch.
caco bd dispatch
02Plan a feature as a graph
Dependencies decide what is ready to start.
caco bd graph
03Answer the fleet
Questions wait for you on every surface.
caco decision resolve
04Steer a running agent
Message, pause or take the keyboard.
caco msg send --target
05Add a machine
One trust domain, agents placed anywhere.
caco node join
06Run a typed flow
Agents and actions as a checked graph.
caco flow run

All recipes, with real output →

Themed to the last pixel.

Aurora
Dusk
Nord Light
Paper
E-ink

Start with one machine.

Build

nix build github:harryaskham/cacophony
# or, from a checkout
cargo install --path crates/caco --locked

Run

# check, config, daemon, sandbox, demo bead
caco bootstrap dev --check
caco bootstrap dev
caco tui

The source and releases need access to the GitHub repository. Prebuilt releases for Linux and Apple Silicon come with a checksum-verifying installer. Add machines with certificates and mesh networking.