Claude Code Plugin

See also: Quickstart Guide for basic Thrum setup, Codex Plugin for Codex skill-based integration, Agent Configurations for manual agent definitions, MCP Server for the native MCP transport, Multi-Agent Support for coordination patterns.

Overview

The Thrum plugin for Claude Code gives agents native access to Thrum messaging through slash commands, automatic context injection via hooks, and progressive disclosure resource docs. It replaces the manual agent definition approach (copying .md files into .claude/agents/) with a single plugin install.

What you get:

• 10 slash commands — /thrum:send, /thrum:inbox, /thrum:quickstart, and more
• Automatic context — SessionStart and PreCompact hooks run thrum prime to inject identity, team roster, inbox, and git state
• 8 resource docs — Progressive disclosure for messaging patterns, groups, identity, worktrees, and anti-patterns
• Background listener — Sub-agent template for async message monitoring

Prerequisites

Before installing the plugin, you need Thrum installed and initialized:

# Install thrum
curl -fsSL https://raw.githubusercontent.com/leonletto/thrum/main/scripts/install.sh | sh
# Or: brew install leonletto/tap/thrum
# Or: git clone https://github.com/leonletto/thrum.git && cd thrum && make install

# Initialize in your repository (v0.4.5+: init does full setup)
cd /path/to/your/repo
thrum init

thrum init (v0.4.5+) handles the full setup: prompts for runtime detection, generates CLAUDE.md coordination instructions, starts the daemon, registers your agent, and starts a session. For manual control, you can still run individual steps:

thrum setup claude-md --apply    # Generate CLAUDE.md coordination instructions

Verify the daemon is running:

thrum daemon status

Installation

From GitHub (self-hosted marketplace)

The plugin is distributed as a self-hosted marketplace. First add the marketplace, then install the plugin:

# Add the Thrum marketplace
claude plugin marketplace add https://github.com/leonletto/thrum

# Install the plugin
claude plugin install thrum

From local clone

If you've cloned the Thrum repository locally:

# Add as a local marketplace
claude plugin marketplace add /path/to/thrum

# Install the plugin
claude plugin install thrum

Verify installation

Start a new Claude Code session. The SessionStart hook should automatically run thrum prime and inject context. You'll see your agent identity, team roster, and unread messages in the session preamble.

Slash Commands

All commands live under the /thrum: namespace.

Common workflows

Start a session:

/thrum:quickstart

Prompts for role, module, and intent — or pass flags directly:

thrum quickstart --name implementer_auth --role implementer --module auth --intent "Building login flow"

Send a message:

/thrum:send

Guided prompt for recipient and message. Direct usage:

thrum send "Starting auth work" --to @coordinator
thrum send "Need review" --to @reviewers
thrum send "Heads up: breaking change" --to @everyone

Check inbox and reply:

/thrum:inbox
/thrum:reply

Hooks

The plugin configures two hooks that run automatically:

SessionStart

Runs thrum prime when a Claude Code session begins. Injects:

• Agent identity (name, role, module)
• Active team members and their intents
• Unread messages
• Git branch and status
• Daemon health

If Thrum isn't initialized, shows a friendly setup message instead of failing.

PreCompact

Runs thrum prime before context compaction. This ensures agent identity and session state survive compaction — the agent can continue working without losing track of who it is or what messages are pending.

Resource Docs

The plugin includes 8 resource documents that Claude loads on demand for deeper guidance:

MCP Server Integration

For native tool-call integration (no shell-outs), configure the Thrum MCP server in your project's .claude/settings.json:

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

This provides 11 MCP tools (10 active + 1 deprecated): 4 for core messaging (send_message, check_messages, wait_for_message, list_agents), 6 for group management (create_group, delete_group, add_group_member, remove_group_member, list_groups, get_group), and broadcast_message (deprecated — use send_message(to="@everyone") instead). See MCP Server for the full API.

Plugin vs MCP: The plugin's slash commands use the CLI (Bash(thrum:*)). The MCP server provides native tool calls. Both work — the plugin is simpler to set up, the MCP server is more efficient for high-frequency messaging. You can use both together.

Background Listener

When thrum prime runs in a Claude Code session and detects an active identity, it outputs a ready-to-use listener spawn instruction with the correct repo path. Copy and run it to start background message monitoring:

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"
)

--after -15s means include messages sent up to 1 second ago (negative = "N ago"; prevents stale replay on restart). The listener runs 6 cycles of 15 minutes each (~90 min coverage), blocks on thrum wait (no polling), returns when messages arrive, and costs ~$0.00003/cycle on Haiku. Re-arm after processing each batch. See the LISTENER_PATTERN.md resource for the full template.

Plugin vs Manual Agent Definitions

The manual agent definitions (thrum-agent.md, message-listener.md) still work and are available in toolkit/agents/ for environments that don't support plugins.

Troubleshooting

"Thrum not initialized" on session start

Run thrum init in your repository root (it starts the daemon automatically).

No context injected after plugin install

Verify the plugin is loaded: check that /thrum:prime is available as a slash command. If not, reinstall the plugin.

Messages not arriving

Check daemon status with thrum daemon status. The daemon must be running for messaging to work. Start it with thrum daemon start.

Identity conflicts in multi-worktree setups

Set THRUM_NAME environment variable to give each worktree a unique agent name. See Identity System for details.

Next Steps

• MCP Server — the MCP server the plugin configures, including the full 11-tool reference
• Codex Plugin — the equivalent skill bundle for Codex users instead of Claude Code
• Agent Coordination — practical multi-agent workflows using the slash commands and hooks this plugin provides
• Identity System — agent naming, THRUM_NAME, and multi-agent worktree setup