Multi-agent

Declaring agents

Edit .clu/config.yaml:

id_prefix: clu-
agents:
  code-reviewer:
    description: "Reviews Go code for correctness and security"
    capabilities: [go-review, security-review]
  doc-writer:
    description: "Writes README + docs/ updates"
    capabilities: [docs]

Then each agent claims from its own lane:

clu claim --agent code-reviewer --wait --heartbeat

--heartbeat is opt-in — without it the claim loop doesn't advertise liveness. With it, clu agent ls shows who's online and when they were last seen.

Identity is one concept

clu collapses the user/agent distinction on purpose: this is a local-only tool and there's no separate "human actor" to track. Every place that needs identity uses -a / --agent <name>:

• clu claim -a foo — foo is both the lane filter and the assignee.
• clu comment add -a foo … — foo is the author.
• clu approve -a foo — foo is recorded as the approver (informational; the approvers list is not enforced).
• clu ready -a foo / clu list -a foo — foo is the lane filter.

Bare clu claim defaults assignee to $USER and pulls from the unassigned lane.

Capability routing

Coordinators route work either by assigning directly:

clu create -a doc-writer "update the install docs"

…or by tagging capability:

clu create --capability docs "update the install docs"

Capability-tagged issues in the default lane flow to whichever agent advertises that capability in its config.yaml entry. This keeps the issue routable to any agent with the skill, not just one named agent.

Watching for work

In Claude Code, point the Monitor tool at:

Monitor: clu ready --watch -a code-reviewer

…and you've got a push-style task feed. clu suppresses unchanged ticks, Monitor turns each new state into one notification. No polling loops, no while true, no diff against seen. See AGENTS.md in the repo for the full pattern.