thurbox-agents

Thurbox agent definitions

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.

Agent Definitions

Per-agent reference + the "adding a new built-in" checklist: docs/AGENTS.md (each built-in's exact config, ID model, and status-hook mechanism, plus every file to update when promoting a CLI to a built-in).

The set of launchable coding agents is declared as data in ~/.config/thurbox/agents.toml, seeded with built-ins (claude, codex, antigravity, opencode, aider, copilot, vibe, pi, omp) plus shell on first run.

shell is the one seeded entry that is not a coding agent: the platform's own interactive shell (bash -i, or powershell -NoLogo on native Windows, where the multiplexer is psmux). It exists so a session can be anything, and it is the ready-made form of session create --command. Because it declares no resume_args/fork_args, it also documents the rule by example: those groups are the conversation address, and an entry without them can be restarted but never resumed. A raw --command session behaves identically — thurbox builds it a synthetic AgentDef with empty arg groups and persists the recipe on the session row, since there is no agents.toml entry to re-resolve at restart. Each [[agents]] entry is an AgentDef:

default = "claude"

[[agents]]
name = "claude"
command = "claude"
args = []                               # always passed; bake a model here if you want one
resume_args = ["--resume", "{id}"]      # emitted when resuming
fork_args = ["--resume", "{id}", "--fork-session"]
new_session_args = ["--session-id", "{id}"]  # emitted on a fresh spawn

[[agents]]
name = "codex"
command = "codex"
resume_args = ["resume", "--last"]      # id-less: resumes the last session in cwd
fork_args = ["fork", "--last"]
resume_latest = true

Each *_args group is appended only when its driving value is present, with {id} substituted; args is always passed. No model is ever passed — each agent uses its own default config (put ["--model", "opus"] in args if you want to pin one). A second token, {home}, expands (at spawn, on the spawn worker — session_ops::expand_home_in_def, called from spawn::adapt_def_for_launch, which both a fresh launch and session_ops::restart go through) to the resolved home dir — the remote home for an SSH/WSL host — so an agent that wants a session file path rather than a bare id (the built-in omp, below) launches against a concrete, quote-safe absolute path (a literal ~ would never expand — args are POSIX-quoted). Agents that omit resume_args simply start fresh on restart (the live tmux process is what carries state across TUI restarts). Add your own [[agents]] entry to support any CLI — no recompile.