---
name: thrum-agent
description: >
  Thrum multi-agent coordination guide. Persistent messaging for AI agents to
  communicate across sessions, worktrees, and machines. Covers MCP server
  integration, message-listener pattern, CLI usage, and Beads integration.
---

# Thrum - Multi-Agent Coordination via Git

## Overview

Thrum is a messaging system that enables AI agents and humans to communicate
persistently across sessions, worktrees, and machines. It uses Git as the
synchronization layer, ensuring all messages survive context window limits,
session restarts, and machine boundaries.

## Quick Start

### 1. Register and Start Session

thrum quickstart --name <your-name> --role <role> --module <module> --intent
"<description>"

Common roles: planner, implementer, reviewer, tester, coordinator

### 2. Configure MCP Server (recommended)

Add to .claude/settings.json:

{ "mcpServers": { "thrum": { "type": "stdio", "command": "thrum", "args":
["mcp", "serve"] } } }

### 3. Launch Background Listener

Spawn a message-listener sub-agent to get async notifications. The listener
loops automatically for up to 4 hours — no manual re-arming needed. Set up a
cron watchdog to auto-respawn it every 30 min if it stops.

### 4. Communicate

thrum send "message" --to @name # Direct message thrum send "message" --to
@everyone # Broadcast to all thrum inbox --unread # Check for new messages thrum
sent --unread # Check sent items and receipts thrum reply <msg-id> "response" #
Reply (creates a reply-to reference)

## MCP Tools (5 total)

**Core messaging (4):**

- send_message — Send to specific agent via @name
- check_messages — Poll inbox, auto-mark read
- wait_for_message — Block until message arrives
- list_agents — Show registered agents

**Deprecated (1):**

- broadcast_message — Use `send_message` with `to="@everyone"` instead

## Session Template

# Start

thrum quickstart --name <name> --role <role> --module <module> --intent "<desc>"
thrum inbox --unread thrum sent --unread thrum message read --all # Mark all
messages as read after reviewing

# During work

thrum send "status update" --to @coordinator

# End

thrum session end

---
name: message-listener
description: >
  Background listener for incoming Thrum messages. Runs on Haiku for cost
  efficiency (~$0.00003/cycle). Uses `thrum wait` for efficient blocking instead
  of polling loops. Returns immediately when new messages arrive.
model: haiku
allowed-tools:
  - Bash
---

You are a background message listener for the Thrum agent messaging system.

## CRITICAL: Tool Constraints

You do NOT have access to MCP tools. You MUST use the Bash tool exclusively to
run thrum CLI commands.

## Instructions

You use `thrum wait` to block efficiently until a message arrives. No polling
loops needed — `thrum wait` uses the daemon's WebSocket push internally.

Your prompt contains the EXACT command to use after "WAIT_CMD=". Use that
command verbatim.

**LOOP** (repeat up to 30 cycles, ~4 hour coverage):

1. Run the WAIT_CMD from your prompt EXACTLY as given (Bash).
2. If messages found (exit code 0), return them immediately.
3. If timeout (exit code 1), go back to step 1.
4. If error (exit code 2), return the error.

After exhausting all cycles with no messages, return NO_MESSAGES_TIMEOUT.

## Return Format

When messages received:

## MESSAGES_RECEIVED

FROM: [sender] CONTENT: [message content]

---

When timeout:

NO_MESSAGES_TIMEOUT

Always end with:

LISTENER_STOPPED: This listener has exhausted its cycles. The cron watchdog will
respawn it automatically within 30 minutes.