# Thrum v0.6.3

> Git-backed messaging for AI agent coordination. Real-time. Cross-machine. Persistent.

## What is Thrum

Thrum is a messaging and coordination system for AI agents. Messages are stored
in append-only JSONL logs (sharded by agent) on a dedicated `a-sync` orphan
branch, accessed via a `.git/thrum-sync/a-sync` git worktree. A SQLite projection provides
fast queries. A background daemon provides JSON-RPC over Unix socket and
WebSocket, with automatic Git sync every 60 seconds. No branch switching is
needed -- all sync operations happen within the worktree.

## Quick Start

  thrum init                                          # Set up .thrum/ in repo
  thrum daemon start                                  # Start background daemon
  thrum quickstart --name <agent-name> --role planner --module auth        # Register + start session
  thrum send "Starting work on auth module"            # Send a message
  thrum inbox                                          # Check messages
  thrum sent                                           # Check sent items and receipts

## Global Flags

All commands accept these flags:

  --role VALUE        Agent role (or THRUM_ROLE env var)
  --module VALUE      Agent module (or THRUM_MODULE env var)
  --repo PATH         Repository path (default: ".")
  --json              JSON output for scripting
  --quiet             Suppress non-essential output
  --verbose           Debug output

## All Commands

### Setup & Orientation

  thrum init [--force] [--stealth] [--runtime claude|codex|cursor|gemini|cli-only|all] [--dry-run] [--agent-name NAME] [--agent-role ROLE] [--agent-module MODULE]
    Initialize Thrum in the current repository. Optionally generate runtime-specific configs.

  thrum setup WORKTREE_PATH
    Configure a feature worktree with .thrum/redirect to share the main issue database.

  thrum setup claude-md [--apply] [--force]
    Generate Thrum agent coordination instructions for CLAUDE.md. Prints to stdout
    by default. Use --apply to append to CLAUDE.md (creates if missing). Use --force
    with --apply to replace existing Thrum section.

  thrum migrate [--repo PATH]
    Migrate old-layout repos (JSONL on main branch) to worktree architecture.

  thrum quickstart --name <agent-name> --role ROLE --module MODULE [--display NAME] [--intent TEXT] [--runtime PRESET] [--dry-run] [--force] [--no-init] [--preamble-file PATH]
    Register agent, start session, generate runtime config, and set intent in one step.
    Runtime presets: claude, codex, cursor, gemini, auggie, cli-only.

  thrum overview [--json]
    Show combined status: identity, work context, team, inbox, sync.

  thrum status [--json]
    Show current agent status and session info.

  thrum whoami [--json]
    Show current agent identity (lightweight, no daemon required).

  thrum version
    Show version, build hash, repository URL, and documentation URL.

  thrum prime [--json]
    Gather comprehensive session context for agent initialization or context recovery.
    Shows: identity, session, team, inbox summary, branch, daemon status, commands, listener instruction.

  thrum completion [bash|fish|powershell|zsh]
    Generate shell autocompletion scripts.

### Messaging

  thrum send MESSAGE [--scope type:value] [--ref type:value] [--mention @role] [--thread ID] [--to @role|@everyone] [--everyone] [--format markdown|plain|json] [--structured JSON]
    Send a message. Use --to @everyone to broadcast to all agents. Use --to @group to send to a group.

  thrum reply MSG_ID TEXT [--format markdown|plain|json]
    Reply to a message, copying the parent's audience (mentions/scopes). Includes reply_to reference.

  thrum inbox [--scope type:value] [--mentions] [--unread] [--all|-a] [--page-size N] [--limit N] [--page N]
    List messages in your inbox. Auto-filters to messages addressed to you + broadcasts.
    Use --all to disable auto-filtering and show everything.

  thrum sent [--to @agent|@role|@group|@everyone] [--unread] [--page-size N] [--limit N] [--page N]
    List messages you sent, including resolved recipients and durable read state.
    Use 'thrum sent show <message-id>' for full recipient details on one message.

  thrum wait [--timeout DURATION] [--scope type:value] [--mention @role] [--after OFFSET]
    Block until a matching message arrives.
    --after sign convention: negative (e.g., -30s) = include messages sent up to N ago; positive (e.g., +60s) = only messages N in the future; omit for "now". Exit 0=received, 1=timeout, 2=error.

### Message Management

  thrum message get MSG_ID
    Get a single message with full details.

  thrum message edit MSG_ID TEXT
    Edit a message (full replacement, author only).

  thrum message delete MSG_ID --force
    Delete a message.

  thrum message read [MSG_ID...] [--all]
    Mark messages as read. Use --all to mark all unread messages as read.

  thrum purge --before DURATION|DATE [--confirm]
  thrum purge --all [--confirm]
    Remove old messages, sessions, and events. Without --confirm, shows a preview.
    Supports relative durations (2d, 24h), dates (2026-03-15), and RFC 3339.
    Cleans both SQLite and sync JSONL files. Agents are not touched.

### Agent Identity

  thrum agent register --role ROLE --module MODULE [--name NAME] [--display NAME] [--force] [--re-register]
    Register this agent. Identity priority: THRUM_NAME env > --name flag > identity file.

  thrum agent whoami
    Show current agent identity and active session.

  thrum agent list [--role ROLE] [--module MODULE] [--context]
    List registered agents. --context shows branch/commits/intent.

  thrum agent context [AGENT] [--agent ROLE] [--branch NAME] [--file PATH]
    Show detailed work context for agents.

  thrum agent delete NAME
    Delete an agent (removes identity, messages, SQLite record).

  thrum agent cleanup [--force] [--dry-run] [--threshold DAYS]
    Detect and remove orphaned agents. --threshold sets stale cutoff (default: 30 days).

### Agent Session Aliases

  thrum agent start                     # Alias for session start
  thrum agent end [--reason normal|crash] [--session-id ID]  # Alias for session end
  thrum agent set-intent TEXT           # Alias for session set-intent
  thrum agent set-task TASK             # Alias for session set-task
  thrum agent heartbeat [--add-scope type:value] [--remove-scope type:value] [--add-ref type:value] [--remove-ref type:value]

### Sessions

  thrum session start
    Start a new work session (agent must be registered).

  thrum session end [--reason normal|crash] [--session-id ID]
    End current session.

  thrum session list [--active] [--agent AGENT_ID]
    List all sessions. --active shows only active sessions.

  thrum session heartbeat [--add-scope type:value] [--remove-scope type:value] [--add-ref type:value] [--remove-ref type:value]
    Send heartbeat. Triggers git context extraction, updates last-seen time.

  thrum session set-intent TEXT
    Set work intent for current session. Pass "" to clear.

  thrum session set-task TASK
    Set current task identifier. Pass "" to clear.

### Subscriptions

  thrum subscribe --scope type:value
  thrum subscribe --mention @role
  thrum subscribe --all
    Subscribe to push notifications (mutually exclusive options).

  thrum unsubscribe SUBSCRIPTION_ID
    Remove a subscription.

  thrum subscriptions
    List active subscriptions for current session.

### Groups

  thrum group create NAME [--description TEXT]
    Create a named group.

  thrum group delete NAME
    Delete a group (cannot delete @everyone).

  thrum group add GROUP MEMBER [--role ROLE]
    Add member to group. Default: agent name. Use --role for role-based membership.

  thrum group remove GROUP MEMBER [--role ROLE]
    Remove member from group.

  thrum group list [--json]
    List all groups.

  thrum group info NAME [--json]
    Show group details.

  thrum group members NAME [--expand] [--json]
    List group members (--expand resolves nested groups/roles to agent IDs).

### Team Overview

  thrum team [--all] [--json]
    Show rich status for all active agents (sessions, context, inbox, branches).
    Use --all to include offline agents.

### Context Management

  thrum context save [--file PATH] [--agent NAME]
    Save context for current agent from file or stdin.

  thrum context show [--agent NAME] [--raw] [--no-preamble]
    Show saved context for current agent. Alias: thrum context load.

  thrum context clear [--agent NAME]
    Clear saved context for current agent.

  thrum context preamble [--init] [--file PATH] [--agent NAME]
    Show or manage the preamble (stable header prepended to context).

  thrum context prime [--json]
    Gather comprehensive session context for agent initialization or recovery.

  thrum context sync [--agent NAME]
    Copy context to the a-sync branch for sharing across worktrees.

### Coordination

  thrum who-has FILE
    Check which agents are editing a file.

  thrum ping AGENT
    Check if an agent is online (with or without @ prefix).

### Sync

  thrum sync status
    Show sync loop status and last sync time.

  thrum sync force
    Trigger immediate sync (non-blocking).

### Peer Sync (Tailscale)

  thrum peer add
    Start a pairing session. Displays a 4-digit code. Blocks until peer connects (5min timeout).

  thrum peer join <address>
    Connect to a remote daemon at a Tailscale address. Prompts for 4-digit pairing code.

  thrum peer list
    List paired peers.

  thrum peer remove <name>
    Remove a paired peer.

  thrum peer status
    Show detailed sync status for all peers.

### Runtime Presets

  thrum runtime list
    List all runtime presets (claude, codex, cursor, gemini, auggie, amp, cli-only).

  thrum runtime show <name>
    Show details for a runtime preset.

  thrum runtime set-default <name>
    Set the default runtime preset.

### Role Templates

  thrum roles list
    List role templates and matching agents.

  thrum roles deploy [--agent NAME] [--dry-run]
    Re-render preambles from role templates. Full overwrite.

### Configuration

  thrum config show [--json]
    Show effective configuration from all sources (config.json, env, defaults).

### Daemon

  thrum daemon start [--local]
    Start daemon in background. --local disables remote git sync.

  thrum daemon stop
    Stop daemon gracefully.

  thrum daemon status
    Show daemon running state, PID, uptime, version.

  thrum daemon restart
    Stop and restart daemon.

## Common Agent Workflows

### Start working on a repo

  thrum init
  thrum daemon start
  thrum quickstart --name <agent-name> --role implementer --module auth --intent "Building auth flow"

### Send a message to a teammate

  thrum send "Auth module ready for review" --to @reviewer --scope module:auth

### Broadcast to all agents

  thrum send "Stopping for lunch, back in 30" --to @everyone

### Send to a group

  thrum send "API changes incoming" --to @backend-team

### Check inbox and reply

  thrum inbox --unread
  thrum sent --unread
  thrum reply msg_01HXE... "Looks good, merging now"

### Coordinate on shared files

  thrum who-has auth.go
  thrum agent list --context

### Check team status

  thrum team

### Check if an agent is online

  thrum ping @reviewer

### Get a combined status overview

  thrum overview

### Manage groups

  thrum group create backend-team --description "Backend developers"
  thrum group add backend-team @alice
  thrum group add backend-team --role implementer
  thrum send "Deploy in 5 minutes" --to @backend-team

### Peer sync across machines (Tailscale)

  # Configure: .env with THRUM_TS_ENABLED=true, THRUM_TS_HOSTNAME, THRUM_TS_AUTHKEY
  # Machine A
  thrum peer add                    # Displays pairing code (blocks 5min)
  # Machine B
  thrum peer join 100.x.y.z:9100   # Use Tailscale IP, enter pairing code
  # Both machines now sync every 15s

### Save and recover context

  thrum context save --file session-notes.md
  thrum context prime          # Gather all context for recovery

## Key Concepts

  Agent       An AI agent or human identified by role + module. ID: agent:role:hash.
  Session     A work period for an agent. Tracks scopes, refs, heartbeats.
  Role        Agent's function (e.g., implementer, reviewer, planner).
  Module      Component the agent is responsible for (e.g., auth, db, ui).
  Group       Named collection of agents, roles, or other groups for targeted messaging.
  Scope       Routing metadata on messages (format: type:value, e.g., module:auth).
  Ref         Reference metadata (format: type:value, e.g., pr:42, mention:reviewer).
  Mention     Tag another agent by role: @role. Stored as ref type "mention".
  Sync        The `a-sync` orphan branch accessed via `.git/thrum-sync/a-sync` worktree.
  Heartbeat   Periodic signal from agent. Extracts git state, updates last-seen.
  Context     Saved session state for recovery after compaction or session boundaries.
  Peer        A Tailscale-connected remote daemon for direct machine-to-machine sync.
  Runtime     AI coding tool preset (Claude, Codex, Cursor, Gemini, etc.) with config defaults.

## MCP Server

  thrum mcp serve [--agent-id NAME]
    Start MCP stdio server for native agent messaging (JSON-RPC over stdin/stdout).
    Use --agent-id to select identity file. Configure in .claude/settings.json.

  MCP Tools:
    send_message(to, content, reply_to?, metadata?)
      Send a message to another agent via @role or @group addressing.
      - to: recipient @role or @group (required)
      - content: message text (required)
      - reply_to: message ID to reply to (optional)
      - metadata: optional key-value pairs (optional)

    check_messages(limit?)
      Poll for unread messages mentioning this agent, auto-marks read.
      - limit: max messages to return (optional, default: 50)

    wait_for_message(timeout?)
      Block until a message arrives (WebSocket push) or timeout.
      - timeout: max seconds to wait (optional, default: 300, max: 600)

    list_agents(include_offline?)
      List registered agents with active/offline status.
      - include_offline: include inactive agents (optional, default: true)

    broadcast_message(content)
      Send to all agents (convenience wrapper around send_message to @everyone).

    create_group(name, description?)
      Create a named group.
      - name: group name (required)
      - description: optional description (optional)

    delete_group(name)
      Delete a group.
      - name: group name to delete (required)

    add_group_member(group, member_type, member_value)
      Add member to group (agent, role, or nested group).
      - group: group name (required)
      - member_type: agent|role|group (required)
      - member_value: agent name, role name, or group name (required)

    remove_group_member(group, member_type, member_value)
      Remove member from group.
      - group: group name (required)
      - member_type: agent|role|group (required)
      - member_value: agent name, role name, or group name (required)

    list_groups()
      List all groups (no parameters).

    get_group(name, expand?)
      Get group details (supports expand=true for nested resolution).
      - name: group name (required)
      - expand: resolve nested groups/roles to agent IDs (optional, default: false)

## Daemon

  Socket:     .thrum/var/thrum.sock (Unix socket, JSON-RPC 2.0)
  WebSocket:  ws://localhost:9999/ (or THRUM_WS_PORT env var)
  PID file:   .thrum/var/thrum.pid (JSON format: PID, RepoPath, StartedAt, SocketPath)
  Port file:  .thrum/var/ws.port (actual WebSocket port)
  Lock:       Socket flock for SIGKILL resilience (auto-released on process death)

  Start:      thrum daemon start (pre-startup duplicate detection via repo affinity)
  Stop:       thrum daemon stop
  Health:     thrum daemon status (shows repo path, JSON PID info)

## Environment Variables

  THRUM_NAME      Agent name (highest priority for identity resolution)
  THRUM_ROLE      Agent role (overrides identity file)
  THRUM_MODULE    Agent module (overrides identity file)
  THRUM_DISPLAY   Display name (overrides identity file)
  THRUM_LOCAL     Enable local-only mode (disables remote sync) -- set to "1"
  THRUM_WS_PORT   WebSocket port (default: 9999)

## Local-Only Mode

  Disables all git push/fetch in the sync loop. Use for public repos where
  you don't want to expose agent messages to origin.

  thrum daemon start --local             # Via CLI flag
  THRUM_LOCAL=1 thrum daemon start       # Via environment variable

  Persists in .thrum/config.json: { "local_only": true }
  Priority: CLI flag > env var > config file > default (true via thrum init)
  Check status: thrum sync status (shows "Mode: local-only" or "Mode: normal")

## Worktree Setup Scripts

  Scripts for batch-configuring redirect files across all worktrees:

  ./scripts/setup-worktree-thrum.sh              # Auto-detect all worktrees
  ./scripts/setup-worktree-thrum.sh PATH          # Single worktree
  ./scripts/setup-worktree-beads.sh              # Auto-detect all worktrees
  ./scripts/setup-worktree-beads.sh PATH          # Single worktree

  Creates .thrum/redirect and .beads/redirect pointing to the main repo.
  Idempotent -- skips already-configured worktrees.

## Toolkit

  Ready-to-use agent configurations and workflow templates in toolkit/:

  toolkit/agents/           Claude Code agent definitions
    thrum-agent.md          Thrum messaging coordination guide
    (Beads plugin)          Install via /install-plugin beads
    message-listener.md     Background message polling agent (Haiku model)

  toolkit/templates/        Agent development workflow patterns
    agent-dev-workflow/     Four-phase skill pipeline (Design/Plan/Setup/Implement)
      implementation-agent.md   Active: prompt template for implementation agents
      philosophy-template.md    Active: anti-patterns template for implementation standards
      planning-agent.md         Reference: superseded by skill pipeline
    README.md               Documentation for using templates

  Install: cp toolkit/agents/*.md your-project/.claude/agents/

## Beads + Thrum Integration

  Beads (task tracking) and Thrum (messaging) together provide complete agent
  memory and coordination:

  Beads: what agents were doing -- tasks, status, dependencies, context recovery
  Thrum: what agents said -- messages, presence, notifications, session tracking

  Both use Git as persistence layer. State survives session boundaries,
  context compaction, and machine changes.

## Identity Resolution Order

  1. CLI flags (--role, --module, --name)
  2. Environment variables (THRUM_ROLE, THRUM_MODULE, THRUM_NAME)
  3. Identity files in .thrum/identities/ directory

  Note: THRUM_NAME env var takes highest priority for name resolution,
  overriding even the --name CLI flag.