thurbox: Skill for Claude Code

thurbox-cli, automations, tasks and messages

Working reference indexed by AGENTS.md. 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
thurbox-cli session list --parent <lead-uuid> --recursive  # every descendant
thurbox-cli session list --tree                # nested as the sidebar nests it

Subcommands: ui (instances/state/actions/action/input for a live local TUI), schema (CLI command tree plus that instance's live UI action catalog), agent (launch-args — see below), session (create/list [--deleted [--since]]/get/delete/reap/purge/restore/restart [--if-missing]/rename/reparent/stop/start/fork/exec/meta/reports-as/set-key/send [--no-enter]/key/capture/focus/signal/doctor/sync/revision/register — sync/revision/register and the flags serve session sharing, ADR-24), watch (stream the session event log, one event per line), runtime (status/stop — what thurbox runs that is not a session), 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; send --title --body [--session] [--key --min-interval] delivers one for a script, hook or Exec automation — honours both off switches, never touches session state, dedupes a key across processes through a lease in event_cursors; see docs/CONFIG.md → Scripted notifications), perf (print the perf snapshot a running TUI publishes while THURBOX_PERF_LOG or its perf HUD is active; --plugins for one row per pane, sorted by cost, with hints — see docs/PERFORMANCE.md), plugin (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), doctor (whether this machine has what a session needs: the multiplexer and its version, every registered agent's command, the launcher for each configured host, and the full search path. The companion to session doctor, which asks whether an existing session's status hooks are wired — this one names no session, so it answers on a machine where nothing has been created yet. fail and a non-zero exit only for what must work: no multiplexer, or no registered agent that resolves anywhere; a partly-installed registry is warn and exits 0. See "What is missing, before you hit it" below).