Runner

Agent Queue

Run collaborative AI agents that communicate through a shared event queue. Each agent is a headless Claude Code instance with a markdown-defined persona and event subscriptions.

Quick Start

1. Start the daemon (runs in background with auto-restart):

   busytown start
   

   Other daemon commands: stop, restart, status

2. Push an event to trigger agents:

   busytown events push --worker user --type file.change --payload '{"path":"src/app.ts"}'
   

To run the agent runner in the foreground instead, use busytown run directly.

runner CLI

busytown <command> [options]

Runner options (for run, start, restart):

How It Works

The runner operates a poll-match-invoke cycle:

1. Poll — each tick, poll the event queue for new events (per-agent cursor tracking)
2. Match — filter events against each agent's listen patterns
3. Invoke — for each agent with matched events, spawn a headless claude --print process with the agent's system prompt and matched events as the user message

Agents run concurrently but each agent processes one batch at a time (no duplicate invocations for the same agent).

How to define agents

Define an agent in agents/ (see Creating Agents):

---
description: Reviews code changes
listen:
  - "file.change"
---
Your system prompt here...

Claiming Events

Agents can claim events to coordinate work. Claims are first-claim-wins — only one worker can claim each event.

# Claim event #1
busytown events claim --worker agent-1 --event 1

# Check who claimed an event
busytown events check-claim --event 1

See Event Queue CLI for the full reference.

Supporting Skills

• events — a skill describing the underlying busytown events commands (push, watch, since, list, cursor, claim, check-claim)
• create-agent — a skill for helping the user define new agent files

Converted and distributed by TomeVault — claim your Tome and manage your conversions.