What Is Thrum?

TL;DR: Thrum has ~30 commands but you only need 8 for daily use. The tables below break down which commands are for you, which are for agents, and which are one-time setup. Start here, then drill into the reference pages when you need details.

Thrum is a messaging system for coordinating AI agents across sessions, worktrees, and machines. It provides:

Everything is inspectable. Messages are JSONL files on a Git branch. State is a queryable SQLite database. Sync is plain Git push/pull. If something goes wrong, you look at files.

New here? Start with Why Thrum Exists for the philosophy behind the project, or the Quickstart Guide to get running in 5 minutes.

Quick Setup

After thrum init, run one command to generate agent coordination instructions for your CLAUDE.md:

thrum setup claude-md --apply

thrum prime (or thrum context prime) checks for an existing Thrum section and suggests this if it's missing.

Understanding the CLI

Thrum has ~30 commands. Here's why that's not as many as it sounds.

Daily Drivers (8 commands)

These are the commands you'll actually use. If you're directing agents and checking on their work, this is your whole toolkit:

Command What it does
quickstart Register + start session + set intent — one step
send Send a message
inbox Check your messages
reply Reply to a message
team What's everyone working on?
overview Status + team + inbox in one view
status Your current state
who-has Who's editing this file?

That's it for daily use. Everything else is infrastructure.

Designed for Agents (~16 commands)

These commands exist because agents need programmatic lifecycle control. You rarely use them directly — quickstart handles the common case — but agents call them constantly:

Area Commands Why agents need them
Identity agent register, agent whoami Agents register on startup
Sessions session start/end/heartbeat Track work periods, extract git state
Work context session set-intent/set-task Declare what they're doing
Notifications subscribe, wait Block until relevant messages arrive
Context context save/show/clear Persist state across compaction
Messages message get/edit/delete/read CRUD on individual messages
Groups group create/add/remove/list Organize teams programmatically
MCP mcp serve Native tool access for Claude Code etc.

Setup & Admin (run once)

init, daemon start/stop, setup, migrate, agent delete/cleanup, sync force/status, runtime list/show, ping

Aliases (because agents get creative)

AI agents are unpredictable in how they guess command names. An agent told to "start working" might try thrum agent start or thrum session start. Both work. These duplicates exist on purpose — they reduce friction for non-human users:

Alias Points to Why it exists
agent start session start Agents think "I'm an agent, I should start"
agent end session end Same pattern
agent set-intent session set-intent Natural grouping under agent
agent set-task session set-task Same
agent heartbeat session heartbeat Same
whoami agent whoami Common enough to promote to top-level

Design Principles

You stay in control. Thrum is infrastructure you can inspect, not a service you depend on. Everything is files, Git branches, and a local daemon. See Why Thrum Exists for the full philosophy.

Offline-first. Everything works locally. Network is optional for sync.

Git as infrastructure. No additional servers. Uses existing Git authentication and hosting.

Event sourcing. JSONL log is the source of truth. SQLite is a rebuildable projection.

Conflict-free. Immutable events + unique IDs = conflict-free merging.

Minimal dependencies. Pure Go with minimal external packages. No CGO.

Graceful degradation. Network failures, missing remotes, and partial sync all handled gracefully.

Documentation Index

Document Description
Philosophy Why Thrum exists and how it thinks about agents
Quickstart Guide 5-minute getting started
Architecture Daemon internals, storage, sync, and packages
Daemon Architecture Technical daemon internals
RPC API Reference All RPC methods
Sync Protocol Git synchronization details
WebSocket API WebSocket-specific docs
Event Streaming Notifications and subscriptions
CLI Reference All CLI commands and backup & restore
Identity System Agent identity and registration
Context Management Agent context storage and persistence
Multi-Agent Support Groups, runtime presets, and team coordination
Tailscale Sync Cross-machine sync via Tailscale with security
Agent Coordination Multi-agent workflows and Beads integration
Workflow Templates Three-phase agent development templates
Coordinate Two Agents Walk through registering two agents and sending messages between them
Sync Across Machines Walk through enabling cross-machine sync via Git
Code Review Workflow Walk through the implement-then-review cycle with worktrees

Next Steps