Thrum CLI Reference

TL;DR: You only need 8 commands for daily use — they're in the Overview page. This page is the full reference for all ~30 commands. Use Ctrl+F or the Quick Reference table at the top to find what you need. Storage layout details are at the very bottom.

Complete reference for the thrum command-line interface — a messaging system for AI agent coordination.

Quick Reference

Global Flags

Available on all commands:

Core Commands

thrum init

Initialize Thrum in the current repository. Creates the .thrum/ directory structure, sets up the a-sync branch for message synchronization, and updates .gitignore. Detects installed AI runtimes and prompts you to select one.

thrum init [--stealth] [flags]

Example:

$ thrum init
✓ Thrum initialized successfully
  Repository: .
  Created: .thrum/ directory structure
  Created: a-sync branch for message sync
  Updated: .gitignore

Detected AI runtimes:
  1. Claude Code    (found .claude/settings.json)

Which is your primary runtime? [1]:
✓ Runtime saved to .thrum/config.json (primary: claude)

Skills-Only Install

Use --skills to install just the thrum skill without full runtime configuration. Detects your agent automatically and installs to the correct skills directory:

$ thrum init --skills
Detected: Claude Code (found .claude/settings.json)
Skill installed to .claude/skills/thrum/
  SKILL.md
  references/CLI_REFERENCE.md
  references/LISTENER_PATTERN.md
  references/MESSAGING.md

Supported agents: Claude Code, Cursor, Codex, Gemini, Augment, Amp. If the thrum Claude plugin is already installed, --skills skips the install (use --force to override). If no agent-specific directory is found, falls back to .agents/skills/thrum/ (the cross-agent standard path).

thrum config show

Show effective configuration resolved from all sources. Displays each value and where it came from (config.json, environment variable, default).

thrum config show [flags]

Example:

$ thrum config show
Thrum Configuration
  Config file: .thrum/config.json

Runtime
  Primary:     claude (config.json)
  Detected:    claude, augment

Daemon
  Local-only:    true (config.json)
  Sync interval: 60s (default)
  WS port:       auto (default)
  Status:        running (PID 7718)

thrum setup

Set up Thrum in a feature worktree so it shares the daemon, database, and sync state with the main repository. Creates a .thrum/redirect file pointing to the main repo's .thrum/ directory and a local .thrum/identities/ directory for per-worktree agent identities.

thrum setup [flags]

Example:

$ thrum setup --main-repo /path/to/main/repo
Connected to daemon
✓ Thrum worktree setup complete

thrum setup claude-md

Generate Thrum agent coordination instructions for CLAUDE.md.

thrum setup claude-md              # Print to stdout
thrum setup claude-md --apply      # Append to CLAUDE.md (creates if missing)
thrum setup claude-md --apply --force  # Replace existing Thrum section

Flags:

• --apply — Append generated content to CLAUDE.md (with duplicate detection)
• --force — Replace existing Thrum section instead of skipping (used with --apply)

This command generates comprehensive agent coordination instructions including:

• Registration and session management
• Message protocols
• MCP server configuration
• Background listener setup
• Group management

The instructions are automatically injected by thrum prime when agents start sessions, providing immediate context on how to use Thrum for coordination.

thrum migrate

Migrate an existing Thrum repository from the old layout (JSONL files tracked on main branch) to the new worktree architecture (JSONL files on a-sync branch via .git/thrum-sync/a-sync/ worktree). Safe to run multiple times -- it detects what needs migration and skips steps that are already done.

thrum migrate

thrum quickstart

Register, start a session, and set an initial intent in one step. If the agent is already registered, it re-registers automatically. Supports agent naming via the --name flag or THRUM_NAME environment variable.

thrum quickstart --name AGENT_NAME --role ROLE --module MODULE [flags]

Requires --role and --module (via flags or THRUM_ROLE/THRUM_MODULE env vars).

The THRUM_NAME environment variable takes priority over the --name flag.

Example:

$ thrum quickstart --name implementer_auth --role implementer --module auth --intent "Fixing token refresh"
✓ Registered as @implementer (implementer_35HV62T9B9)
✓ Session started: ses_01HXF2A9...
✓ Intent set: Fixing token refresh

# With a human-readable name
$ thrum quickstart --name furiosa --role implementer --module auth --intent "Fixing token refresh"
✓ Registered as @furiosa (furiosa)
✓ Session started: ses_01HXF2A9...
✓ Intent set: Fixing token refresh

thrum overview

Show a comprehensive orientation view combining identity, work context, team activity, inbox counts, and sync status.

thrum overview

Example:

$ thrum overview
You: @implementer (implementer_35HV62T9B9)
Session: active for 2h15m
Intent: Fixing token refresh
Branch: feature/auth (3 commits, 5 files)

Team:
  @reviewer     feature/auth   Reviewing PR #42          15m ago
  @planner      main           Planning next sprint      1h ago

Inbox: 3 unread (12 total)
Sync: ✓ synced

thrum status

Show current agent identity, session, work context, inbox counts, and daemon health.

thrum status

Example:

$ thrum status
Agent:    implementer_35HV62T9B9 (@implementer)
Module:   auth
Display:  Auth Developer
Session:  ses_01HXF2A9... (duration: 2h15m)
Intent:   Fixing token refresh
Branch:   feature/auth (3 commits ahead)
Files:    5 changed, 2 uncommitted
Inbox:    47 messages (12 unread)
Sync:     ✓ synced
Daemon:   running (2h15m uptime, v0.1.0)
WebSocket: ws://localhost:9999

thrum team

Show a rich, multi-line status report for every active agent. Displays session info, work context, inbox counts, branch status, and per-file change details.

Git context fields (branch, unmerged commits ahead, and file changes) are populated automatically when an agent has a worktree session ref set — this happens on session start and quickstart. When an agent has an active session with a worktree ref, the daemon extracts the current branch, number of commits ahead of the default branch, and the list of changed files on each heartbeat.

thrum team [flags]

Example:

$ thrum team
@implementer [active]
  Module:   auth
  Worktree: auth-fix
  Session:  ses_01HXF2A9... (duration: 2h15m)
  Intent:   Fixing token refresh
  Inbox:    3 unread / 12 total
  Branch:   feature/auth (2 commits ahead)
  Files:
    internal/auth/token.go        5m ago   +42 -10
    internal/auth/refresh.go      5m ago   +15 -3

$ thrum team --all     # Include agents with no active session

Messaging

thrum send

Send a message to the messaging system. The daemon must be running and you must have an active session.

thrum send MESSAGE [flags]

The --to flag adds the recipient as a mention, making it a directed message. Recipients can be agents (@alice), roles (@reviewer), or groups (@everyone, @backend). The --broadcast and --to flags are mutually exclusive.

The --broadcast flag is an alias for --to @everyone.

Example:

$ thrum send "PR ready for review" --to @reviewer --scope module:auth --ref pr:42
✓ Message sent: msg_01HXE8Z7...
  Created: 2026-02-03T10:00:00Z

# Send to all agents via @everyone group
$ thrum send "Deploy complete" --to @everyone
✓ Message sent: msg_01HXE8Z8...

# Send to a custom group
$ thrum send "Backend review needed" --to @backend
✓ Message sent: msg_01HXE8Z9...

thrum reply

Reply to a message by ID. Creates a reply-to reference so replies are grouped with the original message in your inbox. The replied-to message is marked as read. Replies automatically create or join threads. See Auto-Threading for details.

thrum reply MSG_ID TEXT [flags]

Example:

$ thrum reply msg_01HXE8Z7 "Good idea, let's do that"
✓ Reply sent: msg_01HXE9A3...
  In reply to: msg_01HXE8Z7

thrum inbox

List messages in your inbox with filtering and pagination. Displayed messages are automatically marked as read (unless filtering with --unread).

thrum inbox [flags]

The output adapts to terminal width and shows read/unread indicators.

Example:

$ thrum inbox --unread
┌──────────────────────────────────────────────────────────┐
│ ● msg_01HXE8Z7  @planner  2m ago                       │
│ We should refactor the sync daemon before adding embeds. │
├──────────────────────────────────────────────────────────┤
│ ● msg_01HXE8A2  @reviewer  15m ago                      │
│ LGTM on the auth changes. Ready to merge.               │
└──────────────────────────────────────────────────────────┘
Showing 1-2 of 12 messages (5 unread)

thrum sent

List messages you authored, including resolved recipients and durable delivery/read state.

thrum sent [flags]
thrum sent show MSG_ID

Common examples:

thrum sent
thrum sent --unread
thrum sent --to @implementer_api
thrum sent --to @backend-team
thrum sent show msg_01HXE8Z7

thrum message get

Get a single message with full details. The message is automatically marked as read.

thrum message get MSG_ID

Example:

$ thrum message get msg_01HXE8Z7
Message: msg_01HXE8Z7
  From:    @planner
  Time:    2m ago
  Scopes:  module:auth
  Refs:    issue:thrum-42

We should refactor the sync daemon before adding embeddings.

thrum message edit

Edit a message by replacing its content entirely. Only the message author can edit their own messages.

thrum message edit MSG_ID TEXT

Example:

$ thrum message edit msg_01HXE8Z7 "Updated: refactor sync daemon first"
✓ Message edited: msg_01HXE8Z7 (version 2)

thrum message delete

Delete a message by ID. Requires the --force flag to confirm.

thrum message delete MSG_ID --force

Example:

$ thrum message delete msg_01HXE8Z7 --force
✓ Message deleted: msg_01HXE8Z7

thrum message read

Mark one or more messages as read, or all unread messages at once.

thrum message read MSG_ID [MSG_ID...]
thrum message read --all

Example:

$ thrum message read msg_01 msg_02 msg_03
✓ Marked 3 messages as read

$ thrum message read --all
✓ Marked 7 messages as read

thrum purge

Remove messages, sessions, and events before a cutoff date. By default shows a preview of what would be deleted. Use --confirm to execute.

thrum purge --before DURATION|DATE
thrum purge --all

--before and --all are mutually exclusive. One is required.

Example:

$ thrum purge --before 2d
Purge preview (before 2026-03-14T00:00:00Z):

  Messages:  142
  Sessions:   8
  Events:     47
  Sync files: 10 message files, 1 events file

Run with --confirm to execute.

$ thrum purge --before 2d --confirm
Purged (before 2026-03-14T00:00:00Z):

  Messages:  142 deleted
  Sessions:   8 deleted
  Events:     47 deleted
  Sync files: 10 message files filtered, 1 events file filtered

Done.

Identity & Sessions

Agent Naming

Agents support human-readable names that become their canonical identifier for display, messaging (@name), and file paths.

Naming rules:

• Allowed characters: lowercase letters (a-z), digits (0-9), underscores (_)
• Reserved names: daemon, system, thrum, all, broadcast
• Cannot be empty

Name resolution priority (highest to lowest):

1. THRUM_NAME environment variable (highest -- used for multi-agent worktrees)
2. --name CLI flag
3. Scan .thrum/identities/ for a single file (backward compat for solo-agent worktrees)

When no name is provided, agent IDs default to {role}_{hash10} format (e.g., implementer_35HV62T9B9).

thrum agent register

Register this agent with the daemon. The agent identity is resolved from: (1) THRUM_NAME env var, (2) --name flag, (3) environment variables (THRUM_ROLE, THRUM_MODULE), (4) identity file in .thrum/identities/ directory.

thrum agent register [flags]

Requires --role and --module (via global flags or env vars). On successful registration, saves an identity file to .thrum/identities/{name}.json.

Example:

$ thrum --role=implementer --module=auth agent register --display "Auth Developer"
✓ Agent registered: implementer_35HV62T9B9

# With a human-readable name
$ thrum --role=implementer --module=auth agent register --name furiosa --display "Auth Developer"
✓ Agent registered: furiosa

thrum agent list

List all registered agents with session status and work context.

thrum agent list [flags]

Without --context, shows a detailed card view per agent with active/offline status. With --context, shows a compact table of work contexts.

Example (default view):

$ thrum agent list
Registered agents (2):

┌─ ● @implementer (active)
│  Module:  auth
│  Intent:  Fixing token refresh
│  Branch:  feature/auth (3 commits)
│  Active:  5m ago
└─

┌─ ○ @reviewer (offline)
│  Module:  auth
│  Last seen: 2h ago
└─

Example (context table):

$ thrum agent list --context
AGENT          SESSION      BRANCH               COMMITS  FILES INTENT                         UPDATED
────────────────────────────────────────────────────────────────────────────────────────────────────────
@implementer   ses_01HXF... feature/auth               3      5 Fixing token refresh           5m ago

thrum agent whoami

Show the current agent identity and active session.

thrum agent whoami

Identity is resolved from: (1) command-line flags (--role, --module), (2) environment variables (THRUM_ROLE, THRUM_MODULE, THRUM_NAME), (3) identity files in .thrum/identities/ directory.

Example:

$ thrum agent whoami
Agent ID:  implementer_35HV62T9B9
Role:      @implementer
Module:    auth
Display:   Auth Developer
Source:    environment
Session:   ses_01HXF2A9... (2h ago)

thrum agent context

Show detailed work context for agents. Without arguments, lists all active work contexts. With an agent argument, shows detailed context for that agent.

thrum agent context [AGENT] [flags]

Example (single agent detail):

$ thrum agent context @implementer
Agent: @implementer (ses_01HXF...)
Branch: feature/auth
Intent: Fixing token refresh (set 5m ago)
Task: beads:thrum-42 (set 1h ago)

Unmerged Commits (2):
  abc1234 Add token refresh logic [auth.go, token.go]
  def5678 Fix expiry check [auth.go]

Changed Files (vs main): 3
  internal/auth/auth.go
  internal/auth/token.go
  internal/auth/token_test.go

Uncommitted: 1
  internal/auth/refresh.go

thrum agent delete

Delete an agent and all its associated data. This removes the identity file (identities/{name}.json), message file (messages/{name}.jsonl), and the agent record from the database. Prompts for confirmation before deletion.

thrum agent delete <name>

Example:

$ thrum agent delete furiosa
Delete agent 'furiosa' and all associated data? [y/N] y
✓ Agent deleted: furiosa

thrum agent cleanup

Detect and remove orphaned agents whose worktrees or branches no longer exist. Scans all registered agents and identifies orphans based on missing worktree, missing branch, or staleness (not seen in a long time).

thrum agent cleanup [flags]

The --dry-run and --force flags are mutually exclusive.

Example:

$ thrum agent cleanup --dry-run
Orphaned agents (2):
  implementer_35HV... — missing worktree
  reviewer_8KBN...    — not seen in 45 days

$ thrum agent cleanup --force
✓ Deleted implementer_35HV...
✓ Deleted reviewer_8KBN...
✓ Deleted 2 orphaned agent(s)

thrum agent start

Start a new work session. This is an alias for thrum session start. The agent must be registered first.

thrum agent start

thrum agent end

End the current session. This is an alias for thrum session end.

thrum agent end [flags]

thrum agent set-intent

Set the work intent for the current session. This is an alias for thrum session set-intent. Pass an empty string to clear.

thrum agent set-intent TEXT

Example:

$ thrum agent set-intent "Fixing memory leak in connection pool"
✓ Intent set: Fixing memory leak in connection pool

thrum agent set-task

Set the current task identifier for the session. This is an alias for thrum session set-task. Pass an empty string to clear.

thrum agent set-task TASK

Example:

$ thrum agent set-task beads:thrum-42
✓ Task set: beads:thrum-42

thrum agent heartbeat

Send a heartbeat for the current session. This is an alias for thrum session heartbeat. Triggers git context extraction and updates the agent's last-seen time.

thrum agent heartbeat [flags]

thrum session start

Start a new work session. Automatically detects the current agent from whoami and recovers any orphaned sessions.

thrum session start

Example:

$ thrum session start
✓ Session started: ses_01HXF2A9...
  Agent:      implementer_35HV62T9B9
  Started:    2026-02-03 10:00:00

thrum session end

End the current or specified session.

thrum session end [flags]

Example:

$ thrum session end
✓ Session ended: ses_01HXF2A9...
  Ended:      2026-02-03 12:00:00
  Duration:   2h

thrum session list

List all sessions (active and ended) with optional filtering.

thrum session list [flags]

Example:

$ thrum session list
Sessions (3):
  ses_01HXF2A9  implementer_35HV  active  2h ago   Fixing token refresh
  ses_01HXF1B8  reviewer_8KBN     ended   4h ago   Reviewing PR #42
  ses_01HXF0C7  planner_9QRM      ended   1d ago   Sprint planning

$ thrum session list --active
Sessions (1):
  ses_01HXF2A9  implementer_35HV  active  2h ago   Fixing token refresh

thrum session heartbeat

Send a heartbeat for the current session. Triggers git context extraction and updates the agent's last-seen time. Optionally add or remove scopes and refs.

thrum session heartbeat [flags]

Example:

$ thrum session heartbeat --add-scope module:auth
✓ Heartbeat sent: ses_01HXF2A9...
  Context: branch: feature/auth, 3 commits, 5 files

thrum session set-intent

Set a free-text description of what the agent is currently working on. Appears in thrum agent list --context and thrum agent context. Pass an empty string to clear.

thrum session set-intent TEXT

Example:

$ thrum session set-intent "Refactoring login flow"
✓ Intent set: Refactoring login flow

thrum session set-task

Set the current task identifier for the session (e.g., a beads issue ID). Appears in thrum agent list --context and thrum agent context. Pass an empty string to clear.

thrum session set-task TASK

Example:

$ thrum session set-task beads:thrum-42
✓ Task set: beads:thrum-42

Groups

thrum group create

Create a named group for targeted messaging. Groups contain agents and roles.

thrum group create NAME [flags]

The @everyone group is created automatically on daemon startup and includes all agents.

Example:

$ thrum group create reviewers --description "Code review team"
✓ Group created: reviewers

$ thrum group create backend --description "Backend developers"
✓ Group created: backend

thrum group delete

Delete a group by name. The @everyone group is protected and cannot be deleted.

thrum group delete NAME

Example:

$ thrum group delete reviewers
✓ Group deleted: reviewers

$ thrum group delete @everyone
✗ Cannot delete protected group: @everyone

thrum group add

Add a member to a group. Members can be agents or roles.

thrum group add GROUP MEMBER

Member types:

• @alice or alice — Specific agent by name
• --role planner — All agents with role "planner"

Example:

# Add specific agent
$ thrum group add reviewers @alice
✓ Added agent alice to group reviewers

# Add all agents with a role
$ thrum group add reviewers --role reviewer
✓ Added role reviewer to group reviewers

thrum group remove

Remove a member from a group.

thrum group remove GROUP MEMBER

Uses the same member detection as group add.

Example:

$ thrum group remove reviewers @alice
✓ Removed agent alice from group reviewers

thrum group list

List all groups in the system.

thrum group list

Example:

$ thrum group list
Groups (3):

@everyone
  Description: All registered agents
  Members:     (implicit - all agents)
  Created:     2026-02-09 10:00:00

reviewers
  Description: Code review team
  Members:     2
  Created:     2026-02-09 10:15:00

backend
  Description: Backend developers
  Members:     3
  Created:     2026-02-09 10:20:00

thrum group info

Show detailed information about a specific group.

thrum group info NAME

Example:

$ thrum group info reviewers
Group: reviewers
  Description: Code review team
  Created:     2026-02-09 10:15:00
  Created by:  alice
  Members:     2

  Members:
    - @alice (agent)
    - reviewer (role)

thrum group members

List members of a group.

thrum group members NAME

Example:

$ thrum group members reviewers
Members of reviewers (2):
  - @alice (agent)
  - reviewer (role)

Coordination

thrum who-has

Check which agents are currently editing a file. Shows agents with the file in their uncommitted changes or changed files, along with branch and change count information.

thrum who-has FILE

Example:

$ thrum who-has internal/auth/auth.go
@implementer is editing internal/auth/auth.go (2 uncommitted changes, branch: feature/auth)

$ thrum who-has unknown.go
No agents are currently editing unknown.go

thrum ping

Check the presence status of an agent. Shows whether the agent is active or offline, along with their current intent, task, and branch if active. The agent can be specified with or without the @ prefix.

thrum ping AGENT

Example:

$ thrum ping @reviewer
@reviewer: active, last heartbeat 5m ago
  Intent: Reviewing PR #42
  Task: beads:thrum-55
  Branch: feature/auth

$ thrum ping planner
@planner: offline (last seen 3h ago)

Context Management

thrum context save

Save agent context from a file or stdin. Context is stored in .thrum/context/{agent-name}.md for persistence across sessions.

thrum context save [flags]

Example:

$ thrum context save --file dev-docs/Continuation_Prompt.md
✓ Context saved for furiosa (1234 bytes)

# Save from stdin
$ echo "Working on auth module" | thrum context save
✓ Context saved for furiosa (24 bytes)

Agent safety note: Agents should use the /thrum:update-context skill instead of running thrum context save directly. The skill composes a structured context (decisions, next steps, work-in-progress) before saving, whereas running the command manually with arbitrary input can overwrite accumulated session state.

thrum context show

Display the saved context for the current agent.

thrum context show [flags]

Example:

$ thrum context show
Context for furiosa (1.2 KB, updated 5m ago):

# Current Work
- Implementing JWT token refresh
- Investigating rate limiting bug

# Get raw output
$ thrum context show --raw > backup.md

thrum context clear

Remove the context file for the current agent. Idempotent — running clear when no context exists is a no-op.

thrum context clear [flags]

Example:

$ thrum context clear
✓ Context cleared for furiosa

thrum context sync

Copy the context file to the a-sync branch for sharing across worktrees and machines. This is a manual operation — context is never synced automatically.

thrum context sync [flags]

What it does:

1. Copies .thrum/context/{agent}.md to the sync worktree
2. Commits the change with message "context: update {agent}"
3. Pushes to the remote a-sync branch

No-op when no remote is configured (local-only mode) or when the --local daemon flag is set.

Example:

$ thrum context sync
✓ Context synced for furiosa
  Committed and pushed to a-sync branch

Notifications

thrum subscribe

Subscribe to push notifications. Subscription types are mutually exclusive: specify exactly one of --scope, --mention, or --all.

thrum subscribe [flags]

Example:

$ thrum subscribe --scope module:auth
✓ Subscription created: #42
  Session:    ses_01HXF2A9...
  Created:    2026-02-03 10:00:00

thrum unsubscribe

Remove a subscription by ID.

thrum unsubscribe SUBSCRIPTION_ID

Example:

$ thrum unsubscribe 42
✓ Subscription #42 removed

thrum subscriptions

List all active subscriptions for the current session.

thrum subscriptions

Example:

$ thrum subscriptions
Active subscriptions (2):

┌─ Subscription #42
│  Type:       Scope (module:auth)
│  Created:    2026-02-03 10:00:00 (2h ago)
└─

┌─ Subscription #43
│  Type:       Mention (@reviewer)
│  Created:    2026-02-03 10:05:00 (1h55m ago)
└─

thrum wait

Block until a matching message arrives or timeout occurs. Useful for automation and hooks. Always filters by the calling agent's identity — only returns messages directed to this agent by name or role. There is no --all flag.

thrum wait [flags]

Exit codes: 0 = message received, 1 = timeout, 2 = error.

Output: thrum wait does not print message content. On success it prints an action directive telling the caller to check inbox; on timeout it prints a timeout notice to stderr.

# Plain text output (default)
$ thrum wait --after -30s --timeout=5m
ACTION REQUIRED: You have unread messages. Run `thrum inbox --unread` now to read and respond to them.

# JSON output
$ thrum wait --after -30s --timeout=5m --json
{"status": "received", "action": "ACTION REQUIRED: You have unread messages. Run `thrum inbox --unread` now to read and respond to them."}

# Use in scripts (only new messages — no --after means "now")
if thrum wait --timeout=30s; then
  thrum inbox --unread   # read the messages
else
  echo "Timeout"
fi

Infrastructure

thrum daemon start

Start the daemon in the background. Uses thrum daemon run internally to run the daemon in a detached process. The daemon serves both a Unix socket (for CLI RPC) and a combined WebSocket + SPA server on port 9999.

thrum daemon start [flags]

The daemon performs pre-startup duplicate detection by checking if another daemon is already serving this repository (via JSON PID files and flock()).

Example:

# Start in local-only mode (no git push/fetch)
thrum daemon start --local

thrum daemon stop

Stop the daemon gracefully by sending SIGTERM.

thrum daemon stop

thrum daemon status

Show daemon status including PID, uptime, version, and the repository path being served.

thrum daemon status

thrum daemon restart

Restart the daemon (stop + start).

thrum daemon restart

Note: Running thrum sync without a subcommand just prints help — use thrum sync force or thrum sync status to take action.

thrum sync status

Show sync loop status, last sync time, and any errors. When local-only mode is active, displays "Mode: local-only" instead of "Mode: normal".

thrum sync status

Sync states: stopped, idle, synced, error.

thrum sync force

Trigger an immediate sync (non-blocking). Fetches new messages from the remote and pushes local messages. The default sync interval is 60 seconds. When local-only mode is active, displays "local-only (remote sync disabled)".

thrum sync force

Backup & Restore

thrum backup

Snapshot all thrum data (events, messages, config, and identity files) to a backup directory. By default, backups are written to .thrum/backup/ inside the repo. The backup directory can be overridden via --dir or configured in .thrum/config.yaml.

thrum backup [flags]

The --dir flag is a persistent flag inherited by all backup subcommands.

Example:

$ thrum backup
Backup complete: .thrum/backup/my-repo/current
  Events: 1240 lines
  Message files: 3
  Local tables: 7
  Config files: 4

$ thrum backup --dir /path/to/backups
Backup complete: /path/to/backups/my-repo/current

thrum backup status

Show information about the most recent backup — timestamp, counts, and archive history.

thrum backup status [--dir DIR]

Example:

$ thrum backup status
Last backup: 2026-03-01 22:15:03
  Events: 1240 lines
  Message files: 3
  Config files: 4
Archives: 7 (12.3 MB)
  Oldest: 2026-02-01 10:00:00
  Newest: 2026-03-01 22:15:03

thrum backup config

Show the effective backup configuration including directory, retention policy, and any configured plugins.

thrum backup config

Example:

$ thrum backup config
Backup directory: .thrum/backup (default)
Retention:
  Daily: 7
  Weekly: 4
  Monthly: forever

thrum backup restore

Restore thrum data from the latest backup or a specific archive zip. A safety backup is automatically created before restoring, and the daemon is stopped during the restore to avoid file handle conflicts.

thrum backup restore [archive.zip] [flags]

Example:

$ thrum backup restore
This will restore thrum data from backup.
  Backup dir: .thrum/backup
  Repo: my-repo
  Source: current/
A safety backup will be created first.
Continue? [y/N] y
Daemon stopped for restore.
Safety backup: .thrum/backup/my-repo/safety-2026-03-02T10:00:00Z.zip
Restored from: .thrum/backup/my-repo/current

# Restore from a specific archive
$ thrum backup restore .thrum/backup/my-repo/2026-02-15T10:00:00Z.zip --yes

thrum backup plugin list

List all backup plugins configured in .thrum/config.yaml.

thrum backup plugin list

thrum backup plugin add

Add a backup plugin by name/command/include pattern, or use a built-in preset.

thrum backup plugin add [flags]

Example:

thrum backup plugin add --preset beads
thrum backup plugin add --name myplugin --command "bd backup --force" --include ".beads/backup/*.jsonl"

thrum backup plugin remove

Remove a configured backup plugin by name.

thrum backup plugin remove --name NAME

thrum backup schedule

View or configure the automatic backup schedule. The daemon runs a backup at the configured interval when it is running.

thrum backup schedule [interval|off] [flags]

Examples:

# Show current schedule
$ thrum backup schedule

# Back up every 24 hours
$ thrum backup schedule 24h

# Set 8-hour interval and override backup directory
$ thrum backup schedule 8h --dir dev-docs/backup

# Disable scheduled backups
$ thrum backup schedule off

Notes:

• Daemon must be restarted for schedule changes to take effect
• Intervals use Go duration format: 24h, 12h, 6h30m, 168h (1 week)

Role Templates

thrum roles list

List all role templates and show which registered agents match each template.

thrum roles list

thrum roles deploy

Re-render agent preambles from role templates. By default deploys for all agents. Use --agent to target a single agent, and --dry-run to preview changes without writing files.

thrum roles deploy [flags]

Example:

$ thrum roles list
Role Templates:
  implementer   → 2 agents (alice, bob)
  reviewer      → 1 agent  (carol)
  coordinator   → 1 agent  (dave)

$ thrum roles deploy --dry-run
[dry-run] Would update preamble for alice (implementer)
[dry-run] Would update preamble for bob (implementer)
[dry-run] Would update preamble for carol (reviewer)
[dry-run] Would update preamble for dave (coordinator)

$ thrum roles deploy --agent alice
✓ Deployed preamble for alice (implementer)

Telegram

thrum telegram configure

Configure the Telegram bridge. When all flags are provided with --yes, runs non-interactively. When flags are omitted, runs in interactive mode and prompts for each value.

thrum telegram configure [flags]

Example:

# Interactive mode (prompts for each value)
$ thrum telegram configure

# Non-interactive
$ thrum telegram configure --token 123456:ABC-DEF --target @mychat --user alice --yes
✓ Telegram bridge configured

thrum telegram status

Show the current Telegram bridge connection status and configuration.

thrum telegram status

Example:

$ thrum telegram status
Telegram Bridge
  Status:  connected
  Bot:     @my_thrum_bot
  Target:  @mychat
  User:    alice

MCP Server

thrum mcp serve

Start an MCP (Model Context Protocol) server on stdin/stdout for native tool-based agent messaging. This allows Claude Code agents to communicate via MCP tools instead of shelling out to the CLI.

thrum mcp serve [flags]

Requires the Thrum daemon to be running. The --agent-id flag sets THRUM_NAME internally for identity resolution.

MCP Tools provided (10 total):

Core messaging (4):

Group management (6):

Configuration in Claude Code's .claude/settings.json:

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

For multi-agent worktrees, use --agent-id or set THRUM_NAME:

{
  "mcpServers": {
    "thrum": {
      "type": "stdio",
      "command": "thrum",
      "args": ["mcp", "serve", "--agent-id", "furiosa"]
    }
  }
}

Environment Variables

Identity Resolution

Identity is resolved using the following priority (highest to lowest):

1. THRUM_NAME environment variable (selects specific identity file)
2. --name CLI flag
3. Environment variables (THRUM_ROLE, THRUM_MODULE)
4. CLI flags (--role, --module)
5. Identity files in .thrum/identities/ directory (auto-selects if exactly one file exists)

For multi-agent worktrees with multiple identity files, set THRUM_NAME to select the correct one.

Configuration Files

.thrum/identities/{name}.json

Per-agent identity files stored in the .thrum/identities/ directory. Created automatically on successful registration. The filename is derived from the agent name (e.g., furiosa.json or implementer_35HV62T9B9.json).

{
  "version": 3,
  "repo_id": "r_0123456789AB",
  "agent": {
    "kind": "agent",
    "name": "furiosa",
    "role": "implementer",
    "module": "auth",
    "display": "Auth Developer"
  },
  "worktree": "main",
  "confirmed_by": "",
  "updated_at": "2026-02-03T10:00:00Z"
}

The section below covers storage internals. You don't need it for normal use.

Storage Layout

Messages and events are stored on the a-sync Git branch in a worktree at .git/thrum-sync/a-sync/:

Next Steps

• Messaging — how send, inbox, reply, and groups work together
• RPC API Reference — the underlying JSON-RPC methods the CLI wraps
• Quickstart Guide — get up and running in 5 minutes
• Overview — which 8 commands you actually need day-to-day