Agent Configurations

Recommended: Install the Thrum plugin instead of manual agent definitions. The plugin provides 10 slash commands, automatic context hooks, and 8 resource docs — all in a single install.

Claude Code agent definitions teach Claude how to use Thrum effectively. These .md files with YAML frontmatter ship in toolkit/agents/ and load into your project's .claude/agents/ directory. For Beads task tracking, we recommend installing the Beads plugin instead.

Install the agent configs

Copy the agent definitions to your project:

mkdir -p .claude/agents
cp toolkit/agents/thrum-agent.md .claude/agents/
cp toolkit/agents/message-listener.md .claude/agents/

Claude Code automatically detects and loads these files when you start a session.

Available agents

thrum-agent

Comprehensive guide for Thrum messaging. Teaches Claude how to register agents, send/receive messages, and coordinate with teammates via the CLI.

Use when:

Key capabilities:

Beads Plugin (recommended)

For Beads issue tracking, install the Beads plugin instead of using a local agent file. The plugin provides richer functionality:

Install the plugin in Claude Code:

/install-plugin beads

Or visit the Beads project for details.

message-listener

Lightweight background listener that watches for incoming Thrum messages so you don't have to manually check your inbox. Runs on Haiku for cost efficiency (~$0.00003/cycle, ~65% fewer tokens than the old pattern). Uses thrum wait for efficient blocking instead of polling loops — returns immediately when messages arrive, covers up to 4 hours across 30 cycles. A cron watchdog auto-respawns it every 30 min if it stops — no manual re-arming needed.

Use when:

Key capabilities:

Configure the message listener

The message-listener runs as a background task so your main agent session stays focused on work while messages are watched for you.

Launch it at session start:

// In Claude Code with Thrum MCP configured
Task({
  subagent_type: "message-listener",
  model: "haiku",
  run_in_background: true,
  prompt:
    "Listen for Thrum messages. WAIT_CMD=cd /path/to/repo && thrum wait --timeout 8m --after -15s",
});

Wait command flags:

The listener uses thrum wait which blocks until a message arrives or the timeout expires — no polling loops needed. Each cycle is a single Bash call. The listener loops automatically for up to 4 hours (30 cycles). Set up a cron watchdog to auto-respawn it if it stops:

CronCreate(cron="*/30 * * * *",
  prompt="If there is no background message listener running, spawn one now:
    Task(subagent_type='message-listener', model='haiku', run_in_background=true,
      prompt='Listen for Thrum messages. WAIT_CMD=cd /path/to/repo && thrum wait --timeout 8m --after -15s --json')")

Customize for your project

You can edit these agent definitions to match your team's workflows. Add project-specific commands, adjust priorities, or include custom context.

For the agent file format, see Claude Code agent documentation.

Next Steps