thurbox-cli

thurbox-cli, automations, tasks and messages

Working reference extracted from CLAUDE.md, which indexes it. The rationale behind these decisions is owned by the docs under docs/; a change that invalidates what this says updates it in the same PR.

thurbox-cli

A second binary (thurbox-cli) drives the same SQLite-backed, tmux-hosted sessions headlessly (no TUI). It shares the database with the TUI; changes appear via PRAGMA data_version polling.

cargo build --bin thurbox-cli
thurbox-cli session create --name demo --repo-path /path \
    --agent codex --worktree-branch feat/x
# Spawn on a remote host from hosts.toml (worktree + tmux live remotely):
thurbox-cli session create --name demo --repo-path /srv/repo \
    --host devbox --worktree-branch feat/x
# Spawn a worker under a lead session (parent must exist):
thurbox-cli session create --name worker --repo-path /path \
    --parent <lead-uuid>
# Multi-repo: each --add-repo gets its own worktree on --worktree-branch;
# --add-dir attaches a repo as-is (no branch). The agent launches in a
# symlink workspace gathering every repo. Works on `task create` too.
thurbox-cli session create --name demo --repo-path /a \
    --agent claude --worktree-branch feat/x \
    --add-repo /b@main --add-repo /c@master --add-dir /reference
thurbox-cli session list                       # human-readable table
thurbox-cli session list --json | jq           # machine output for scripts
thurbox-cli session list --parent <lead-uuid> --json | jq  # direct children only

Subcommands: session (create/list [--deleted]/get/delete/restore/restart [--if-missing]/send [--no-enter]/key/capture/focus/signal/doctor/sync/register — sync/register and the flags serve session sharing, ADR-24), automation (alias auto: create/list/show/edit/remove/run/runs/tick), task (alias todo: create/list/show/edit/remove/run), message (alias msg: send/inbox/prune — the inter-session mailbox queue; see below), editor (get/set the Ctrl+O editor command; editor mode <auto|terminal|gui> chooses how it launches — terminal editors get a real TTY via a tmux popup or TUI suspend, GUI editors spawn detached; see the Editor Integration section of docs/FEATURES.md), config (validate/show — strict-parses every config file / prints the effective resolved config; see docs/CONFIG.md), extension (alias ext: install/uninstall/reinstall/list/available/update/activate/ deactivate/status — manage opt-in extensions; see below), version (prints the running version; --check queries GitHub's latest release — gated on [features] version_check, on by default for 1.0), update (downloads, verifies, and replaces the installed binaries with the latest release within the current major — a new major is reported, never installed, because 2.x replaced the whole interface; --force bypasses the up-to-date/dev-build/major guards; gated on [features] auto_update, on by default for 1.0; the TUI also runs this silently on startup when the flag is on), notify (diagnose OS desktop notifications: prints the detected delivery backend and last error; --test fires a sample — see OS notifications below), perf (print the perf snapshot a running TUI publishes while THURBOX_PERF_LOG or its perf HUD is active — see docs/PERFORMANCE.md), plugin (v2 interface plugins without a TTY: dir reports the directory in force and which of the two rules chose it, new <name> writes a starter that already loads, check loads the interface the way thurbox does and exits non-zero on a failure — including on a pane that loaded but which no arrangement places, printing the layout.lua line to add — list is the same inventory the settings modal's Interface tab shows, and events lists every event a plugin may subscribe to with its payload, and install|sync|update|remove|available manage panes from a declarative spec — see docs/PLUGINS.md).