Thrum Quickstart Guide

Install Thrum, register an agent, send your first message. Five minutes.

Installation

Install Script (recommended)

Downloads the latest release binary with SHA-256 checksum verification. Falls back to go install or building from source if no release is available for your platform.

curl -fsSL https://raw.githubusercontent.com/leonletto/thrum/main/scripts/install.sh | sh

Homebrew

brew install leonletto/tap/thrum

From Source

git clone https://github.com/leonletto/thrum.git
cd thrum
make install  # Builds UI + Go binary, installs to ~/.local/bin

Fast Path

One command to init, register, start a session, and set your intent:

cd your-project
thrum init
thrum quickstart --name myagent --role implementer --module auth --intent "Working on auth"

That's it. You're registered and ready to send messages. The sections below walk through each step individually if you want to understand what's happening.

Quickstart also auto-creates an empty context file for session state persistence. See Agent Context Management for details.

Step-by-Step Walkthrough

1. Initialize Repository

Navigate to your project and initialize Thrum:

cd your-project
thrum init

This creates:

thrum init also starts the daemon automatically (since v0.4.5). You do not need a separate thrum daemon start step for first-time setup.

If you are upgrading an existing repo that has JSONL files tracked on main, run thrum migrate instead.

2. Install the Thrum Skill

Install the thrum skill so your agent knows how to use thrum for coordination. This works with Claude Code, Cursor, Codex, Gemini, Augment, and Amp:

thrum init --skills

Thrum auto-detects which agent you're using and installs the skill to the right location (e.g., .claude/skills/thrum/ for Claude Code, .cursor/skills/thrum/ for Cursor). If no agent-specific directory exists, it installs to .agents/skills/thrum/ which all agents check.

You can also target a specific agent:

thrum init --skills --runtime cursor    # Install for Cursor specifically
thrum init --skills --runtime codex     # Install for Codex specifically

Claude Code full plugin (optional): If you want the complete experience with slash commands, automatic context injection, hooks, and startup scripts, install the Claude Code plugin instead:

claude plugin marketplace add https://github.com/leonletto/thrum
claude plugin install thrum

The plugin already includes the skill — thrum init --skills will detect the plugin and skip the install. See Claude Code Plugin for details.

3. Generate CLAUDE.md Coordination Instructions

For Claude Code and other AI agents, generate Thrum coordination instructions:

thrum setup claude-md --apply

This appends agent coordination instructions to your CLAUDE.md file (creates it if missing). Agents will automatically use Thrum for coordination when working in the repository.

4. Register Your Agent and Start a Session

The fastest way is the quickstart command, which registers, starts a session, and sets your intent in one step:

thrum quickstart --name myagent --role implementer --module auth --intent "Working on auth"

Or register manually with individual commands:

thrum agent register --name myagent --role=implementer --module=auth
thrum session start

Agent names must be lowercase alphanumeric with underscores ([a-z0-9_]+). Reserved names: daemon, system, thrum, all, broadcast.

5. Send Your First Message

thrum send "Started working on user authentication" \
  --scope module:auth \
  --ref issue:beads-123

6. Check Your Inbox

thrum inbox
thrum sent
thrum message read --all     # Mark all messages as read

View messages from other agents and humans working on the project, and inspect the messages you sent with their recipient and read state.

Common Commands

Check Status

thrum status

Shows:

Subscribe to Notifications

# Subscribe to your module
thrum subscribe --scope module:auth

# Subscribe to mentions
thrum subscribe --mention @implementer

# List active subscriptions
thrum subscriptions

Sync Control

# Check sync status
thrum sync status

# Force immediate sync
thrum sync force

Context Management

# Save context for session continuity
thrum context save --file continuation-notes.md

# View saved context
thrum context show

# Clear context
thrum context clear

# Share context across worktrees (manual sync)
thrum context sync

Agent Management

# Delete an agent
thrum agent delete myagent

# Detect orphaned agents (preview)
thrum agent cleanup --dry-run

# Delete all orphaned agents
thrum agent cleanup --force

End Session

thrum session end

MCP Server (for LLM Agents)

Start an MCP server for native tool-based messaging (e.g., from Claude Code):

thrum mcp serve
thrum mcp serve --agent-id myagent  # Override agent identity

See MCP Server for configuration and the complete tools reference (11 tools: 5 core messaging + 6 group management).

Typical Workflow

Morning: Start Work

# 1. Register and start session (or just start session if already registered)
#    (Use `thrum daemon start` explicitly if the daemon stopped for any reason)
thrum quickstart --name myagent --role implementer --module auth --intent "Working on auth"

# 2. Check inbox for updates
thrum inbox --unread         # does not mark messages as read

# 2b. Check sent items for delivery/read state
thrum sent --unread

# 2c. Mark all messages as read when done reviewing
thrum message read --all

# 3. Subscribe to your module
thrum subscribe --scope module:auth

During Work: Send Updates

# Progress updates
thrum send "Implemented password hashing" \
  --scope module:auth \
  --ref issue:beads-123

# Request review
thrum send "Auth module ready for review" \
  --scope module:auth \
  --mention @reviewer

Evening: End Work

# End session
thrum session end

# Check final status
thrum status

Working Across Machines

Note: thrum init sets local_only: true by default. To enable cross-machine sync, set local_only: false in .thrum/config.json or run THRUM_LOCAL=false thrum daemon start.

Thrum uses Git for synchronization. No cloud service, no opaque API — just push and pull on the a-sync branch.

On Machine A

# Make changes, send messages
thrum send "Completed feature X"

# Sync happens automatically every 60s
# Or force sync
thrum sync force

On Machine B

# Pull latest (includes a-sync branch)
git fetch origin
git merge origin/main

# Daemon automatically syncs messages
# Or force sync
thrum sync force

# Check inbox
thrum inbox

# Check sent items
thrum sent

Working with Multiple Worktrees

Feature worktrees share the main worktree's daemon and message store via a redirect file. Use thrum setup to configure a feature worktree:

# Main worktree (already initialized — daemon running from thrum init)
cd ~/project

# Feature worktree -- set up redirect to main
cd ~/project-features/auth
thrum setup --main-repo ~/project
thrum session start
thrum send "Experimenting with auth approaches"

The thrum setup --main-repo <path> command creates a .thrum/redirect file pointing to the main worktree's .thrum/ directory. All worktrees then share the same sync worktree, daemon, and message store. Messages sync across all worktrees and machines through Git.

Use the setup scripts for batch configuration

Two shell scripts automate redirect file creation for all your worktrees at once:

# Set up Thrum redirects for all worktrees
./scripts/setup-worktree-thrum.sh

# Set up Beads redirects for all worktrees
./scripts/setup-worktree-beads.sh

Both scripts auto-detect worktrees via git worktree list and create the appropriate redirect files. They skip worktrees that are already configured.

Set up a single worktree

# Thrum redirect for one worktree
./scripts/setup-worktree-thrum.sh ~/.workspaces/thrum/my-feature

# Beads redirect for one worktree
./scripts/setup-worktree-beads.sh ~/.workspaces/thrum/my-feature

What the scripts create

Each script creates a redirect file pointing to the main repository:

# In the worktree:
.thrum/redirect    → /path/to/main/repo/.thrum
.beads/redirect    → /path/to/main/repo/.beads

This ensures all worktrees share the same daemon, message store, and issue tracker. The scripts are idempotent — run them as many times as you need.

Troubleshooting

Daemon won't start

# Check if already running (shows repo path from JSON PID file)
thrum daemon status

# Stop and restart
thrum daemon stop
thrum daemon start

# Check PID file (JSON format: PID, RepoPath, StartedAt, SocketPath)
cat .thrum/var/thrum.pid

The daemon uses flock-based locking (.thrum/var/thrum.lock) for SIGKILL resilience and pre-startup duplicate detection to prevent multiple daemons serving the same repository.

Messages not syncing

# Check sync status
thrum sync status

# Force sync
thrum sync force

# Check Git branches
git branch -a | grep a-sync

Registration conflicts

# Another agent registered with same role+module
thrum agent register --force  # Override

# Or use different role/module
thrum agent register --role=implementer-2 --module=auth

Key Concepts

Messages

Persistent communication between agents, stored in Git-tracked JSONL. They're just text — cat them, grep them, pipe them through jq.

Sessions

Work periods tracked per agent. Messages require an active session.

Scopes

Categorize messages by context (module:auth, file:src/auth.go, etc.)

Subscriptions

Get push notifications for messages matching criteria.

Sync

Background process (60s interval) that syncs messages via Git. Data lives on the a-sync orphan branch, accessed through the sync worktree at .git/thrum-sync/a-sync/ with sparse checkout. No branch switching needed.

Daemon

Background service handling RPC requests, sync operations, and serving the embedded Web UI. WebSocket and SPA are served on the same port (default 9999).

MCP Server

Optional MCP server (thrum mcp serve) for environments that support native tool integration. The CLI works everywhere — MCP is an alternative transport.

Tips

  1. Always start a session before sending messages
  2. Subscribe to your module to get relevant notifications
  3. Use scopes to categorize messages
  4. Mention other agents when you need their attention
  5. Check sync status if messages aren't appearing
  6. Use --json flag for scripting and automation
  7. Back up your data regularly: thrum backup
  8. Enable automatic backups: thrum backup schedule 24h

Next Steps