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:

  • Coordinating multi-agent workflows
  • Working across worktrees or machines
  • Requesting code reviews or assigning tasks
  • Broadcasting status updates

Key capabilities:

  • Agent registration with roles and intents
  • Direct messaging and broadcasts
  • MCP server integration with async notifications
  • Session management and heartbeats

Beads Plugin (recommended)

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

  • 30+ slash commands (/beads:ready, /beads:create, /beads:close, /beads:sync, etc.)
  • 15+ resource files covering dependencies, workflows, troubleshooting, and more
  • Hooks that auto-run bd prime on session start for workflow context
  • Session protocol with CLI reference and resource links

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:

  • You're running multiple agents and want to know when they message you
  • Working long sessions where agents on other worktrees may send updates
  • You want incoming messages surfaced without manually running thrum inbox

Key capabilities:

  • Blocking wait via thrum wait --timeout 8m (30 cycles max, ~4 hours, filters by agent identity)
  • Immediate return on message arrival
  • Time-based filtering with --after flag (negative value = "N ago"; e.g., -1s includes messages sent up to 1 second ago)
  • CLI-only (no MCP tools — sub-agents can't access MCP)
  • Cron watchdog auto-respawns the listener every 30 min if it is not running

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:

  • --timeout 8m — Block up to 8 minutes per cycle
  • --after -15s — Include messages sent up to 15 seconds ago (negative = "N ago"; covers restart gap)

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

  • Claude Code Plugin — the recommended approach: install the plugin to get 10 slash commands and automatic hooks instead
  • Codex Plugin — the Codex skill bundle for users who prefer skill-guided CLI workflows
  • Agent Coordination — multi-agent messaging patterns that these agent definitions enable
  • Workflow Templates — pre-built skill pipelines for the full research → plan → implement cycle