Command-line reference

This page lists the user-facing thrum commands. Your coordinator is the agent you talk to, which starts the other agents, hands out work and reports back to you. After setup you talk to your coordinator agent, and the coordinator runs most of these commands for you. Use this page to see what it is doing, or to run a command yourself when you need to.

The first five commands

These are the commands you type before a coordinator exists. tmux keeps each agent running in its own terminal session. They need macOS or Linux with tmux installed; Install lists the requirements. The quickstart walks through the commands in order.

Thrum’s web UI is the page you open in your browser to see your agents and their messages.

Command	What it does
thrum init	Sets up Thrum in the current Git repository, starts the daemon (Thrum’s background process) and registers your first agent, the coordinator.
thrum tmux start	Starts your coordinator in a tmux session named after the current folder, then attaches you to it.
thrum app	macOS: starts the Thrum menu-bar app, which gives you the web UI. On Linux it opens a terminal interface instead.
thrum daemon status	Shows whether the daemon is running: the first line reads Daemon: running. On Linux, open the address on the line that begins with ui to reach the web UI.
thrum license activate	Links this machine to your licence. You need it for Pro or for Pro free for public repositories; Free works without it. It prints a URL; open it in a browser and click Activate.

Who runs these commands

• You: commands you type yourself, mostly during setup or when you want to check something.
• Coordinator: commands your coordinator agent runs, or tells the agents it creates to run. You normally ask for the outcome in plain words instead of typing the command.

Options that work on every command

Option	What it does
--json	Prints machine-readable output.
--quiet	Hides non-essential output.
--verbose	Prints debug output.
--role, --module	Sets the agent role or module for the command. The environment variables THRUM_ROLE and THRUM_MODULE do the same.

Set the environment variable THRUM_NO_HINTS=1 to hide the hints that commands print after they run.

Set up and check your install

Command	What it does	Who runs it
thrum init	Sets up Thrum in this repository (see the first five commands).	You
thrum version	Shows the Thrum version.	You
thrum app	Starts the menu-bar app (macOS) or a terminal interface (Linux, needs an interactive terminal).	You
thrum app status	Prints one line per running daemon, with its repository, or No daemons running.	You
thrum app install-agent	macOS: loads a LaunchAgent so Thrum starts when you log in.	You
thrum config show	Shows the effective configuration. See Configuration.	You
thrum config set <dotted.path> <value>	Sets a shared configuration field, such as project_name. Machine-local fields are edited in .thrum/config.json.	You
thrum setup claude-md	Prints the Thrum block for CLAUDE.md. Add --apply to write it into ./CLAUDE.md.	You
thrum license activate	Links this machine to your licence.	You
thrum license status	Shows the current licence state.	You
thrum license deactivate	Removes the licence credential from this machine, so Pro ends there at once. Its place is freed only when you remove the machine at my.thrum.team/account.	You
thrum license oss-register	Registers this repository for Pro free for public repositories. It prints the repository details it sends before sending them.	You

Run the daemon

Command	What it does	Who runs it
thrum daemon status	Shows daemon status, including the web UI address.	You
thrum daemon start	Starts the daemon in the background.	You
thrum daemon stop	Stops the daemon. Messaging commands fail until you start it again.	You
thrum daemon restart	Restarts the daemon.	You
thrum daemon logs	Shows the daemon log output.	You

Create, start and stop agents

Your coordinator creates an agent in its own Git worktree (a separate checkout of your repository) and runs it in a tmux session.

A runtime is the AI coding tool an agent runs in, such as Claude Code or Codex.

A snapshot is a note an agent writes before a restart or a compaction, with what it did and what is next.

Command	What it does	Who runs it
thrum tmux start	Starts an agent in the current directory and attaches you to it. Takes --name, --runtime, --model and --effort.	You
thrum worktree create <name>	Creates a worktree with Thrum set up in it. With --name and --role it also registers the agent and launches it in a tmux session.	Coordinator
thrum worktree list	Lists worktrees with their Thrum agents.	Coordinator
thrum worktree adopt [path]	Wires an existing Git worktree into Thrum.	Coordinator
thrum worktree teardown <name>	Removes a worktree and the Thrum files in it.	Coordinator
thrum tmux create <name>	Creates a tmux session for an agent.	Coordinator
thrum tmux launch <name>	Starts an AI tool inside a tmux session.	Coordinator
thrum tmux status	Lists the tmux sessions Thrum manages, with their state.	Coordinator
thrum tmux connect [name]	Attaches you to a running agent’s session, by agent name or session name. Without a name it shows a numbered list.	You
thrum tmux send <name> [<text>]	Types text, or named keys with --keys, into an agent’s session.	Coordinator
thrum tmux capture <name>	Prints what the agent’s pane shows. --lines sets how many lines (default 50).	Coordinator
thrum tmux restart <name>	Restarts an agent’s session and restores its saved context. --resume resumes the runtime’s own session.	Coordinator
thrum tmux kill <name>	Stops an agent’s tmux session.	Coordinator
thrum tmux snapshot save	Saves a snapshot of the conversation for a restart.	Coordinator
thrum tmux snapshot restore	Prints the saved restart snapshot.	Coordinator
thrum tmux snapshot check	Exits 0 if a restart snapshot exists, 1 if not.	Coordinator
thrum agent register	Registers this agent.	Coordinator
thrum agent whoami	Shows this agent’s identity. thrum whoami does the same.	Coordinator
thrum agent set-status <working|idle|blocked|stuck>	Sets the agent’s status.	Coordinator
thrum agent sleep	Parks an agent: saves a snapshot, then stops its session. Needs --agent <name>.	Coordinator
thrum agent wake	Starts a parked agent again from its snapshot.	Coordinator
thrum agent retire	Retires a sleeping agent. It asks for confirmation unless you pass --force. thrum agent restore brings it back.	Coordinator
thrum agent restore	Brings a retired agent back to sleeping. Run thrum agent wake next.	Coordinator
thrum agent resurrect	Recovers a stale agent that crashed without a snapshot. Run thrum agent wake next.	Coordinator
thrum agent delete <name>	Deletes an agent and its data. --force skips the confirmation.	Coordinator
thrum agent cleanup <agent>...	Removes the agents you name if their worktree is gone or they are not running. --dry-run checks without removing; --force removes without asking.	Coordinator

Send and read messages

Command	What it does	Who runs it
thrum send [MESSAGE]	Sends a message. --to @agent sets the recipient and can repeat. --stdin or --body-file read the body from stdin or a file.	Coordinator
thrum reply MSG_ID [TEXT]	Replies to a message, to the same audience.	Coordinator
thrum inbox	Lists messages in your inbox. --unread, --mentions and --from filter it.	Coordinator
thrum sent	Lists messages you sent.	Coordinator
thrum wait	Waits for a new message. --timeout sets the limit (default 30s).	Coordinator
thrum message get MSG_ID	Shows a message in full.	Coordinator
thrum message read [MSG_ID...]	Marks messages as read.	Coordinator
thrum message edit MSG_ID [TEXT]	Replaces a message’s text.	Coordinator
thrum message delete MSG_ID	Deletes a message. Needs --force.	Coordinator
thrum message list	Lists messages, with optional filters.	Coordinator
thrum message search QUERY	Searches messages by text.	Coordinator

See the team

Command	What it does	Who runs it
thrum team	Shows the agent roster, what each agent works on and how full its context is. With account usage on, it also shows each AI account’s used, remaining and reset time. --compact gives one line per agent.	You
thrum team @AGENT	Shows one agent in detail.	You
thrum overview	Shows status, team and inbox together.	You
thrum ping AGENT	Checks whether an agent is online.	Coordinator
thrum agent status	Shows the calling agent’s identity, context usage and memory counts.	Coordinator

Sessions and saved context

Command	What it does	Who runs it
thrum quickstart [name]	Registers an agent, starts a session and sets its intent in one step.	Coordinator
thrum prime	Gathers the context an agent loads at the start of a session.	Coordinator
thrum session start	Starts a session.	Coordinator
thrum session end	Ends the current session. --reason is normal or crash.	Coordinator
thrum session list	Lists sessions. --active shows only active ones.	Coordinator
thrum session heartbeat	Sends a heartbeat for the session.	Coordinator
thrum session set-intent TEXT	Sets what the agent is working on.	Coordinator
thrum session set-task TASK	Sets the current task.	Coordinator
thrum context save	Saves the agent’s context from a file or stdin.	Coordinator
thrum context show	Shows the saved context. thrum context load is an alias.	Coordinator
thrum context clear	Clears the saved context.	Coordinator

Sync, back up and clean up

Command	What it does	Who runs it
thrum sync status	Shows sync status.	You
thrum sync force	Starts a sync now.	You
thrum sync enable	Turns sync on. Takes effect after the next daemon restart.	You
thrum sync disable	Turns sync off. Takes effect after the next daemon restart.	You
thrum backup	Saves your Thrum data to a backup directory. --dir overrides the directory.	You
thrum backup status	Shows the last backup.	You
thrum backup config	Shows the effective backup configuration.	You
thrum backup restore [archive.zip]	Restores from the latest backup, or from the archive you name. --yes skips the confirmation.	You
thrum backup schedule [interval|off]	Shows or sets automatic backups, for example 24h.	You
thrum purge	Previews removing old messages, sessions and events. --before sets the cutoff; add --confirm to delete.	You

Work across machines

A peer is another machine running Thrum that you have paired with yours. See Work across multiple machines for the full flow.

Command	What it does	Who runs it
thrum peer add --type <tailscale|local|network>	Starts pairing on this machine and prints a peercode. --type local pairs two daemons on this computer.	You
thrum peer join --type <type> [peercode]	Joins a peer with the peercode from peer add.	You
thrum peer list	Lists paired peers.	You
thrum peer status	Shows detailed sync status for each peer.	You
thrum peer remove [<name>]	Removes a paired peer.	You
thrum peer configure <peer-name> <add-agent|remove-agent> <agent-name>	Adds or removes a proxy agent for a peer: a local stand-in name that routes messages to an agent on that peer’s machine.	Coordinator
thrum peer grant <peer-name>	Sets what a paired machine may read from this one, such as messages, an agent’s terminal view or its conversation transcript. Each permission is a capability: --capabilities grants it and --revoke withdraws it.	You
thrum peer set-coordinator <peer> <agent-name>	Records which agent is the coordinator on a peer. An empty name clears it.	Coordinator

Bridges and MCP

See Set up the email bridge, Message your coordinator on Telegram and MCP.

Command	What it does	Who runs it
thrum telegram configure	Sets up the Telegram bridge, interactively or with --token, --target and --user.	You
thrum telegram pair	Pairs your Telegram account with the bridge.	You
thrum telegram status	Shows the Telegram bridge status.	You
thrum email init	Starts a guided setup of the email bridge, with templates for Gmail, Fastmail and iCloud. Incoming iCloud mail is rejected for now; Which mail providers work has the list. Restart the daemon afterwards. You can also set it up in Settings, General tab, Email Bridge, in the web UI, which needs no restart. The bridge it sets up needs Pro.	You
thrum email status	Shows whether the email bridge is running, its last error, and how many mails it has received and queued to send.	You
thrum email send --to <address> --subject <text> --body <text>	Sends an email through the bridge by hand. Use --body - to read the body from standard input. Needs Pro.	You
thrum mcp serve	Starts the MCP server over stdio for agent messaging.	Coordinator

Roles and runtimes

A runtime is the AI tool an agent runs, such as Claude Code. A runtime preset is the saved setting that tells Thrum how to launch one runtime. A role says what an agent does. A role template holds the instructions for one role, and a preamble is the part an agent receives.

Command	What it does	Who runs it
thrum roles list	Shows the configured role templates and the agents that match them.	You
thrum roles deploy	Rewrites each registered agent’s preamble, the standing instructions for its role, from the role templates. --dry-run previews it.	Coordinator
thrum roles refresh	Regenerates a role template from its saved answers.	Coordinator
thrum roles configure	Configures role templates from flags or from the roles it detects. --autonomy coordinator=strict makes the coordinator ask before it merges, and coordinator=autonomous sets it back. Add --deploy so the agents get the new instructions; each loads them at its next restart. It rewrites the files in .thrum/role_templates/ with no backup.	Coordinator
thrum runtime list	Lists runtime presets.	You
thrum runtime show <name>	Shows one runtime preset.	You
thrum runtime init <name>	Generates the runtime’s files in the repository without needing the daemon.	You
thrum runtime set-default <name>	Sets the default runtime.	You
thrum runtime doctor	Checks ~/.thrum/runtimes.json and fails if a custom runtime is malformed.	You

Shared work and records

Your agents use these to track work and share what they learn. The first column names the command family; the subcommands are the verbs that follow it. Writing in some of these families needs Pro; the licence rules under the table say which.

Command family	Subcommands	What it does
thrum issue	add, show, list, ready, update, close, comment, dep, dep-remove, assign, unassign, claim, release, history	Tracks tasks. ready lists the issues nothing blocks.
thrum monitor	start, list, show, update, stop, restart, delete, logs	Runs a command, filters its output with a pattern, and delivers the matching lines as messages to a target.
thrum dashboard	set, show, get, update, delete, clear, results	Manages the document on an agent’s Dashboard tab.
thrum queue	add, list, show, start, block, done, drop, assign, update, wait, ready, note, item	Tracks committed work. A bundle is one unit of committed work, and its items are short checklist entries inside it.
thrum state	set, get, show, list, delete, describe, history	Stores current-value entries, either per agent or for the whole fleet.
thrum memory	create, show, list, search, edit, delete, link, unlink, history, index, tags, kinds, count	Stores structured notes such as decisions and lessons.
thrum vault	set, get, list, rm, grant, revoke, grants, capabilities, backup, restore	Stores secrets such as passwords and tokens, encrypted on this machine, for one agent, one role or the whole project. Needs Pro. Keep secrets in the vault says where the key is kept.

Your coordinator and its agents run these. Licence rules:

• Needs Pro: thrum memory create, edit and link; thrum state set; every thrum queue command that creates or changes a bundle or item; thrum dashboard set, update and delete; and every thrum vault command, which a machine without Pro refuses with “Vault is a Pro feature”. Reading, listing and the other commands in these families work without Pro.
• Not licence-gated: thrum issue and thrum monitor.
• Peer sharing: these peer capabilities need Pro: reading an agent’s transcript, changing its runtime configuration, editing its artifacts and sharing storage.

Examples

Set up without the prompts. Each flag fills in one prompt of thrum init, so a script can run it unattended:

thrum init --name coord_my_app --role coordinator --module main \
  --worktrees-root "$HOME/.thrum/worktrees/my_app" --roles enhanced

--worktrees-root sets the folder where agent worktrees go, and --roles enhanced applies the enhanced role templates, the choice the quickstart recommends.

Start the coordinator with a model and reasoning effort for this launch only:

thrum tmux start --model opus --effort high

Pair two machines. On both, first run thrum config set tailscale.listen true and thrum daemon restart. Run the first command on the machine that is waiting, and the second on the machine that joins, with the peercode the first one printed:

thrum peer add --type tailscale
thrum peer join --type tailscale <peercode>

Preview which messages, sessions and events a purge removes, then run it:

thrum purge --before 30d
thrum purge --before 30d --confirm

Read only the unread messages in your inbox:

thrum inbox --unread

Next steps

• Configuration: the settings in .thrum/config.json.
• Glossary: the terms used on this page.
• Fix common errors: what to try when a command fails.