~ $ trau --help

Documentation

Everything you need to install, serve, and run the herd — the hub, remote access, the engine, .trau.ini, and the full CLI reference.

Getting started The hub Remote access The loop Configuration Loop vs. solo tickets Per-phase model routing Prompts Providers Verify, CI & merge Self-heal & fallback Lessons memory Time & cost tracking Spend caps CLI reference Safety

Getting started

trau is a single static Go binary that ships two surfaces: the hub — a machine-local web app started by trau serve — and the terminal TUI. Same engine, same queue underneath: cold, isolated agents drive each ticket build → verify → PR → merge.

Before your first run, make sure these are on your PATH and authenticated:

git — the repo you point trau at must be a git checkout.
gh — the GitHub CLI, authenticated (gh auth login). trau opens and merges PRs through it on GitHub. For Bitbucket Cloud, set BITBUCKET_EMAIL and BITBUCKET_API_TOKEN instead and trau talks to the API directly.
An agent CLI on your PATH: claude, codex, or kimi.
An issue tracker — Linear, Jira, Azure DevOps Boards, or GitHub Issues, over MCP or a direct API token — or none at all: trau's internal issue store runs tickets on repos with no external tracker.

install

# macOS / Linux / WSL2 — Homebrew 4.5+
brew install --cask RomkaLTU/trau/trau
trau --version

# Windows — Scoop
scoop bucket add trau https://github.com/RomkaLTU/scoop-trau
scoop install trau

# Windows — Winget (after Microsoft accepts the release manifest)
winget install Codesomelabs.trau

# Linux / WSL2 without Homebrew — download from GitHub Releases
sudo dpkg -i trau_<version>_linux_amd64.deb
sudo rpm -i trau_<version>_linux_amd64.rpm

Or build from source (Go 1.25+):

from source

git clone https://github.com/RomkaLTU/trau && cd trau
make build   # produces bin/trau

First run, hub path (recommended): start the hub and open it in a browser. The Add a project wizard takes a repo from a path to a live backlog — point it at the checkout, let it inspect the repo, wire the tracker (or pick internal issues), confirm the essentials, and seed the board with a first sync.

hub path

trau serve
# then open http://127.0.0.1:8728

First run, terminal path: cd into a repo that has no .trau.ini and run trau with no arguments. The TUI onboarding wizard walks you through tracker, branch, and provider, writes <repo>/.trau.ini for you — and brings the hub up first, before it even resolves the repo.

terminal path

cd ~/code/your-app
trau

Either way, trau doctor is the preflight: it probes git, gh, the provider CLI, config sanity, tracker labels, write permissions, and whether the hub is reachable and running the same version as the binary — exiting non-zero on any failure.

The hub is not optional scenery: starting trau brings it up and waits for it to answer healthy before the session continues. If it cannot start, trau says so and points at the hub log rather than running blind. The TUI header carries the hub’s status, W opens it in a browser, and --no-serve skips the autostart for one session.

The hub

trau serve starts a machine-local web app — embedded in the same binary — that fronts the engine: registered repos, run history, and internal issues live in a durable local database, so history survives restarts. One hub per machine; every screen is scoped to one active repo, or to All projects.

pages, in sidebar order

Overview: The board. Per-repo cards with queue depth, running ticket, needs-attention items, and spend today — scope-aware, one repo or all.
Loop: One ordered queue per repo. Run next starts draining top to bottom; reorder, skip, or override provider/model for a single launch. Each ticket shows a Loop timeline of what happened when.
Backlog: The ticket board: epic → sub-issue nesting, an Archive, read-only assignee filters (Me / Unassigned), in-queue indicators, an openable "Done today" strip, and add-to-queue from any row. Internal issues are authored here on repos with no tracker.
Inbox: Where raw ideas become ready tickets. The Interview asks one question at a time until the ticket is buildable; Ask ahead batches remaining questions, Start over resets, Drafts hold work in progress. Provider and model switch per conversation.
Runs: The Run ledger — every tracked run, newest first, bucketed needs-attention / active / stopped / merged. Run detail shows per-phase cost, the verify verdict, and the handoff brief, with Resume / Reset / Clear actions.
Terminal: Live PTY transcripts of the agent at work, streamed to the browser — the web counterpart of the TUI’s w key.
Atlas: Agent-generated architecture Views per repo (Data model, App flows). Each View is generated at a stamped commit, flags itself stale as the repo moves, and regenerates on demand.
Costs: Daily / per-repo / per-phase spend rollups with anomaly flags, off the same normalized ledger the CLI prints.
Lessons: Browse the durable lessons memory that failed runs feed.
Skills: Curated skill installs for the target repo.
Settings: The layered config, catalog-driven: every section shows which layer a value comes from and writes to an explicit target (repo or home).
Instances: Loop processes registered on this machine — start and stop them from the hub.

⌘K (Ctrl-K on Linux) opens the command palette from anywhere: switch projects, jump to any page, return to somewhere you were recently, or hop straight into a run that is currently active. It also suggests pages related to wherever you already are.

The hub is installable. It ships a web manifest and a service worker, so it can live on a phone home screen or a dock like a native app, and it falls back to a branded offline shell that retries on its own when the machine is unreachable. Opt into Web Push and the needs-attention set reaches you with a deep link to the run or ticket that wants you.

The hub also speaks MCP at /api/v1/mcp, so an agent you already run — Claude Code, Codex, Cursor — can file tickets, arm the queue, read the backlog and live runs, and steer a running agent without opening the web UI. Settings → External agents has the copy-paste setup for each client with the endpoint already resolved, under the same auth posture as the rest of the API: loopback is open, any other bind needs SERVE_TOKEN.

Sync is inbound-authoritative: trau reads tickets from your tracker and writes back statuses and comments. Two things also travel outbound, and only ever on your gesture — assigning a ticket from the board, which writes to the tracker first and mirrors locally only on success, and QUEUED_LABEL, which mirrors the hub queue onto the tracker so planned work is visible there. No phase writes either one, and the next inbound sync always wins.

Remote access

The hub binds to 127.0.0.1 by default and is open on loopback — it is yours, on your machine. Everything beyond loopback is opt-in and gated.

exposure policy

SERVE_TOKEN: Bearer token required on any non-loopback bind. trau serve refuses to start on an exposed address without it.
SERVE_ALLOW_REGISTER: Set to 1 to allow registering/unregistering repos over an exposed bind. Off by default — remote clients can watch but not rewire.

Want the hub on your laptop while the loop runs on your desktop? Tailscale is the blessed path — a private tailnet, not a public port. One hub per machine, machine-local by design: there are no accounts, no teams, and no cloud sync.

The loop

trau processes one ticket per iteration through three steps — Build, Verify, Ship — each made of activities. Every activity starts a brand-new agent process that inherits only a durable handoff brief and the code on disk — no --continue, no --resume. The build agent’s reasoning, and its blind spots, never carry forward.

one ticket

BUILD   build → handoff → lintfix → cleanup
VERIFY  verify (fresh eyes) → repair/bugfix on fail → re-verify
SHIP    commit → PR → CI → merge

Build — writes the code against the ticket, its acceptance criteria, and its non-goals; distills a handoff brief; runs lint autofixers; strips AI-slop from the diff before anyone grades it.
Verify — a fresh, skeptical agent that sees only the brief and the diff. It grades the work, runs the repo’s verify-check library, and can convene a cross-vendor panel.
Ship — stages the verified diff with a clean message, opens the PR, waits for your existing CI checks to land green, then merges and picks the next ticket. Epic branches sync with main continuously and auto-merge once their children land (AUTO_MERGE-gated).

Self-heal: a failed verify spawns a bounded REPAIR pass (MAX_REPAIRS), then a heavier BUGFIX pass (MAX_BUGFIXES), re-verifying each time. Still failing, the ticket is quarantined and the loop moves on. Re-running the same command resumes from the next unfinished phase via the durable per-ticket checkpoint.

When a run stops, the reason has a class. Paused (blameless) — a provider rate-limit or outage; nobody’s fault, resume when the window resets. Faulted — a transient step failure that exhausted its retries and fallbacks; work-in-progress stays on the branch. Quarantined — verify gave a verdict and the repair budget ran out; the ticket gets the QUARANTINE_LABEL and waits for a human. Draining a queue produces a drain report on pause or fault, and the on-fault skip policy decides whether the queue moves on or holds.

Taking the wheel: when a run goes sideways and you would rather steer the agent yourself than let it retry, trau hands you its actual session. Each claude phase records its session id into the ticket checkpoint, so the session outlives the process that minted it. Open in terminal on the hub’s run view — or trau takeover <ID> from a shell — stops the run, waits until the loop has genuinely let go of the working tree, and only then resumes that session in your terminal. Two writers on one checkout is the failure mode the wait exists to prevent.

The takeover holds the repo for as long as your terminal lives, and hand-back is manual: closing it resumes nothing. The ticket stays parked and re-enters the loop only when you queue it again with Run next.

quality passes

LINT_FIX: Run the project’s lint/format autofixers before verify. Default 1.
LINT_FIX_CMD: Deterministic lint-fix command (e.g. vendor/bin/pint, npm run lint:fix). Empty = a cheap agent auto-detects and runs the project’s fixers.
CLEANUP: Strip AI-slop from the slice’s diff before verify. Default 1.

Configuration

trau is configured through .trau.ini — a flat INI subset (KEY=value with # comments). The keys ARE the environment-variable names, so PROVIDER in the file and TRAU_PROVIDER in your shell are the same knob. Settings resolve in layers, lowest to highest precedence:

precedence

built-in defaults: Shipped with the binary.
./trau.ini: Local fallback for the current directory (or TRAU_ENV).
~/.trau.ini: Personal / machine defaults — binaries, API keys, trust flags. Do not commit.
<repo>/.trau.ini: Project facts — tracker, base branch, loop policy. Commit this. Repo config beats home config, so what the project declares wins over personal defaults.
environment: Any KEY above, or its TRAU_<KEY> alias (e.g. TRAU_PROVIDER), which wins.
CLI flags: --repo, --provider, etc. Highest precedence of all.

A minimal project config — the wizard generates something like this:

<repo>/.trau.ini

TRACKER_PROVIDER=linear     # linear | jira | azure | github
LINEAR_TEAM=YourTeam        # team name / Jira key / Azure project / GitHub slug
READY_LABEL=ready-for-agent
QUARANTINE_LABEL=needs-human

BASE_BRANCH=main
REMOTE=origin
PROVIDER=claude             # claude | codex | kimi

AUTO_MERGE=1                # 1 = merge on green CI; 0 = stop at the PR
MERGE_METHOD=squash         # squash | merge | rebase
MAX_ITERATIONS=15

project knobs

TRACKER_PROVIDER: Which tracker backs the loop: linear, jira, azure, or github.
LINEAR_TEAM: Team name (Linear), project key (Jira), team project name (Azure DevOps), or repo slug (GitHub).
ISSUE_PREFIX: Ticket-ID prefix for parsing, branch names, and sentinels (e.g. COD, TMS, ENG). Empty = derive from the team key, falling back to COD.
READY_LABEL: Tickets carrying this label are eligible to run. Default ready-for-agent.
QUARANTINE_LABEL: Applied when a ticket exhausts its repair budget. Default needs-human.
BASE_BRANCH / REMOTE: Git target for branches and PRs. Default main / origin.
PROVIDER: Default agent backend for the loop. Default claude.
PROJECT: Linear project this repo owns. When set, the loop only picks tickets in this project, refuses a cross-project run, and files bugs here. Empty = no scoping.

tracker access (~/.trau.ini)

LINEAR_API_KEY: Optional Linear personal API key — enables the fast direct GraphQL path instead of MCP-only access.
JIRA_BASE_URL: Jira Cloud site base URL for the direct REST adapter (e.g. https://acme.atlassian.net).
JIRA_EMAIL / JIRA_API_TOKEN: Atlassian account email plus a classic (unscoped) API token. Together with JIRA_BASE_URL they enable direct REST calls, with MCP as the fallback.
AZURE_ORG_URL: Azure DevOps Services organization URL for the direct REST adapter (e.g. https://dev.azure.com/acme).
AZURE_PAT: Azure DevOps personal access token. There is no MCP fallback for this provider, so it is required.

new since v1.0

APP_URLS: Monorepo mapping of workspace → local app URL (e.g. web=http://localhost:3000,admin=http://localhost:3001), so browser verify hits the right app for the slice. Single-app repos keep using APP_URL.
AUTO_STASH: Stash uncommitted WIP when a fresh pick starts instead of aborting, and restore it at session end. Default 0.
SERVE_TOKEN: Bearer token for the hub on any non-loopback bind — see Remote access.
SERVE_ALLOW_REGISTER: Allow repo (un)registration over an exposed hub bind. Default 0.
TRACKER_PROVIDER=internal: Use trau's internal issue store — author and run tickets with no external tracker.

Loop vs. solo tickets

trau pulls tickets labelled with your READY_LABEL (default ready-for-agent). What happens next depends on whether the ticket has sub-issues.

Solo — a ticket with no sub-issues runs as a single pass on its own branch off BASE_BRANCH. One task in, one task done.
Loop / epic — a ticket with sub-issues fans out onto a shared epic branch and processes each child tagged ready-for-agent. The epic branch keeps syncing with main, and once its children land it auto-merges on green CI (AUTO_MERGE-gated); children run directly later stack onto the same branch.

EPIC_FLOW controls this. Set EPIC_FLOW=1 to fan out sub-issues onto an epic branch, or EPIC_FLOW=0 to always treat the passed ticket as a standalone branch. Children that lack the ready label are skipped.

Monorepos: project detection is workspace-aware, APP_URLS maps each workspace to its own local URL for browser verify, and commits and PR titles conform to the conventions the repo already uses.

loop control

MAX_ITERATIONS: How many tickets a full loop run will work before stopping. Default 15.
MAX_REPAIRS: Quick verify-fail self-heal attempts before a bugfix. Default 2 (0 = none).
MAX_BUGFIXES: Comprehensive bugfix passes after quick repairs. Default 2 (0 = none).
EPIC_FLOW: 1 = fan sub-issues onto an epic branch; 0 = standalone branch. Default 1.

Per-phase model routing

Pick one PROVIDER for the project, then tune model and effort per phase. Phases you can address: BUILD, HANDOFF, VERIFY, REPAIR, BUGFIX, CLEANUP, LINTFIX, COMMIT, PICK. Keys are namespaced by provider, so each backend keeps its own routing. Mechanical phases ship with cheap defaults — handoff, cleanup, and commit fall back to Sonnet and lintfix to Haiku unless you route them yourself.

.trau.ini

# Claude: Fable 5 for the hard thinking, Sonnet 5 for the cold verify
CLAUDE_BUILD_MODEL=fable
CLAUDE_BUILD_EFFORT=max
CLAUDE_VERIFY_MODEL=claude-sonnet-5
CLAUDE_VERIFY_EFFORT=medium

# Codex: hardest work on GPT-5.6 Sol (the default), mechanical phases lighter
CODEX_BUILD_MODEL=gpt-5.6-sol
CODEX_BUILD_EFFORT=xhigh
CODEX_COMMIT_MODEL=gpt-5.4-mini
CODEX_COMMIT_EFFORT=low

Pattern is <PROVIDER>_<PHASE>_MODEL and <PROVIDER>_<PHASE>_EFFORT. Leave a phase unset to fall back to the provider default (CLAUDE_MODEL / CLAUDE_EFFORT, etc.). Override the whole provider for a single run with --provider.

Prompts

The prompts are the loop’s real behaviour surface, so they are editable. Every phase prompt — build, handoff, verify, commit, repair, bugfix, cleanup, lint-fix, and the rest — is a named template in a registry, each with a title, a description, and its list of placeholders. Edit them from the hub: Settings → Prompts sets the wording for the whole machine, and a repo’s own Prompts section overrides just that project.

how an override resolves

repo > global > built-in: The narrowest override wins. Nothing set anywhere means the shipped default, which is always one click away via Reset to default.
validated fail-closed: An override that does not parse, or that drops a required placeholder, is rejected and the built-in default is used instead. Required placeholders are the ones carrying contracts the loop parses back — verdict and rubric JSON shapes, handoff and notes file paths, the REFUSED sentinel — so a reworded prompt cannot silently break the pipeline.
snapshotted per run: Prompts resolve once, when a ticket starts. Editing mid-run never splits a single run across two versions of a prompt.

Two things are deliberately not editable: tracker MCP prompt fragments and the pointer notes for rubric, build-notes, and lessons files. They are mechanical glue around loop-owned artifacts, not wording worth retuning.

Providers

trau drives the agent CLI you already use, interactively and on the subscription you already pay for — never a metered headless API call, and no provider key for trau to hold, subject to each CLI’s own terms. claude is the most exercised path today; codex (default model GPT-5.6 Sol) and kimi are wired and get sharper with every run. Models come from a single shared catalog, so the hub pickers and the config keys always agree.

provider knobs (~/.trau.ini)

CLAUDE_BIN / CODEX_BIN / KIMI_BIN: Binary name or path for each provider. Default to the bare command.
CLAUDE_FLAGS / CODEX_FLAGS / KIMI_FLAGS: Extra flags passed to the agent CLI. Machine-trust flags live here.
CLAUDE_MODEL / CLAUDE_EFFORT (etc.): Provider default model and reasoning effort when a phase route does not override them.
CLAUDE_DISALLOWED_TOOLS: Tools disabled inside agents. Default Agent,Workflow — denies in-agent subagent fan-out (each phase is already its own process).
CODEX_PROFILE: Optional Codex exec profile, passed through as codex exec --profile <name>.
CLAUDE_CONFIG / CODEX_CONFIG / KIMI_CONFIG: Optional provider-local KEY=value files, resolved relative to the env file that names them.
AGENT_TIMEOUT: Per-agent-call hard timeout in seconds — a backstop for runaway calls; unproductive hangs are killed earlier by AGENT_STALL_WINDOW. Default 3600.

Permission-override flags such as --dangerously-skip-permissions disable approval prompts — keep them in ~/.trau.ini and only on trusted, sandboxed checkouts. Never commit them to a project config.

Verify, CI & merge

The verify phase is the gate. By default trau waits for whatever checks your PR runs and merges only when they are green and none are pending — set EXPECTED_CHECKS when tests run on the PR itself rather than locally.

merge & verify

AUTO_MERGE: 1 merges on green CI; 0 stops at the PR for you. Default 1.
MERGE_METHOD: squash, merge, or rebase. Default squash.
EXPECTED_CHECKS: Comma-separated check names that must be present and green. Empty = any existing checks.
REQUIRE_CI: Gate merges on CI. Set 0 for repos whose workflows never run on pull requests, so a PR with zero checks doesn’t spin to CI_TIMEOUT. Onboarding auto-detects this. Default 1.
CI_TIMEOUT / CI_POLL: Seconds to wait for checks, and seconds between polls. Default 600 / 30.
BROWSER_VERIFY: auto (UI slices only), always, or never. Drives browser-based verification.
APP_URL: Base URL of your locally-running app, used by browser verify. Default http://localhost.
VERIFY_CHECKS: Run the pluggable verify-check library each verify phase. Default 1. Checks live in the target repo under .trau/checks/*.yaml; severity gates the merge (error blocks, warn surfaces).
VERIFY_PANEL: Cross-vendor verify panel: run verify as several fresh, isolated processes from different providers, each judging the diff independently. Each member is provider:model:effort. Empty = a single verifier.
VERIFY_PANEL_POLICY: How panel verdicts merge: unanimous (any dissent blocks, the default), majority, or any-pass.

Self-heal & fallback

A transient agent-step failure — a stalled subprocess, a hard timeout, or a non-rate-limit crash — self-heals instead of parking the ticket. The step retries on a fresh process, then hands off to the next fallback provider; only when the whole chain is exhausted does the run fault, with the work-in-progress preserved on its branch and the ticket left resumable. Rate-limits and provider outages pause the run blamelessly — nobody’s fault, resume when the window resets — and a verified give-up still quarantines. The Run ledger buckets each outcome so you can tell a blameless pause from a fault at a glance.

transient-failure recovery (~/.trau.ini)

AGENT_STALL_WINDOW: Kill and recover a step that emits no output for this many seconds, well before AGENT_TIMEOUT (Claude interactive only). Default 180 (0 = disabled).
AGENT_RETRIES: Transient retries on the same provider before falling back or parking. Default 2.
AGENT_BACKOFF: Base seconds to wait between transient retries (grows with the attempt). Default 10.
FALLBACK_PROVIDERS: Ordered provider[:model[:effort]] specs to try after the primary is exhausted, e.g. codex,kimi. Empty = retry-only.

Lessons memory

Failed runs teach later runs. Each repair experiment — the failure type, the attempted fix, the evidence, the result, and a distilled lesson — is appended to .trau/runs/memory/lessons.jsonl after a repaired success or a quarantine. Lessons relevant to a slice are recalled into later build, verify, and repair prompts. Relevance is filtered and capped, so a thin or empty ledger injects nothing.

lessons memory

LESSONS: Record and recall lessons. Default 1 (0 = off: no recording, no recall).
LESSONS_DISTILL: Enrich each lesson with a cheap, isolated agent pass for a richer, ticket-agnostic takeaway. Default 0 (mechanical record only).

Time & cost tracking

Every run keeps per-phase token and cost accounting, summed at the end and printable any time with trau --status. The ~$X estimate is notional, not a bill: trau prices tokens itself because interactive runs report no provider cost.

Most of a phase’s token TOTAL is cache-read tokens, billed at 0.1× input (5-minute cache writes at 1.25×), so a multi-million-token phase is mostly cheap cache hits. On a subscription your marginal cost is the flat plan fee — read the estimate as a relative signal between phases and models, not a charge.

artifacts

RUNS_DIR: Root for per-ticket artifacts: <RUNS_DIR>/<ID>/{state, *.log, tokens.jsonl}. Default .trau/runs — auto-gitignored, and a legacy ./runs migrates automatically on startup.

terminal ui & usage hud

TRAU_TUI: Use the Bubble Tea TUI in a terminal. Default 1 (toggle per-run with --no-tui; pipes, cron, and --status always use plain output).
THEME: TUI color theme preset: default, catppuccin, dracula, gruvbox, or nord. Any semantic role can be overridden with a THEME_<ROLE> hex value.
NOTIFY: Desktop notifications on pause, quarantine, and session end. Opt-in. Default 0.
AGENT_COLS / AGENT_ROWS: Geometry of the agent PTY; the live agent view (the TUI’s w key, or trau watch headless) reconstructs at this size. Default 120 × 40.
USAGE_WINDOW: Track the active provider's real rate-limit window in the HUD (Claude OAuth usage, Codex app-server, Kimi balance). Metadata-only, fails closed. Default 1.
USAGE_WINDOW_PTY: Pseudo-terminal /usage fallback for providers with no structured window (Kimi subscription). Brittle, opt-in. Default 0.

Opt-in time logs: with TIMELOG_ENABLED=1, every merged ticket also writes a per-ticket effort log compatible with dev-flow tooling.

time logs (opt-in)

TIMELOG_ENABLED: Write a per-ticket effort time log (JSON) after merge. Default 0.
TIMELOG_STORAGE: Where logs land: repo (<repo>/.dev-flow/time/), user (~/.dev-flow/time/<repo>/), or none. Default repo.
TIMELOG_OUTPUT_FORMAT: Export rendering: default (JSON), jira-worklog, toggl-csv, or plain.
TIMELOG_ESTIMATOR: Per-ticket effort estimate: heuristic (deterministic table) or agent (a cheap agent call). Default heuristic.

Spend caps

Optional spend ceilings, enforced off the same normalized token/cost ledger that --status prints and checked before each agent call. A ticket that reaches its per-ticket cap is quarantined and the loop moves on; reaching a per-day cap stops the run cleanly so it can resume once the budget resets or you raise it. Empty = no cap. On unmetered providers prefer the token caps, since the USD figure is a notional estimate.

budget governance

MAX_TICKET_USD: Quarantine a ticket once its estimated cost reaches this many dollars. Empty = no cap.
MAX_TICKET_TOKENS: Quarantine a ticket once it reaches this many tokens. Empty = no cap.
MAX_DAILY_USD: Stop the run once the day's spend across all tickets reaches this many dollars. Empty = no cap.
MAX_DAILY_TOKENS: Stop the run once the day's tokens across all tickets reach this figure. Empty = no cap.

CLI reference

commands & flags

trau: Launch the TUI in the current repo — bringing the hub up first and waiting for it to answer healthy. With no .trau.ini, starts the onboarding wizard.
trau serve: Start the hub: a machine-local web app on http://127.0.0.1:8728. Binds to loopback by default; any other bind requires SERVE_TOKEN, and remote registration additionally requires SERVE_ALLOW_REGISTER=1.
trau stop: Stop the hub and leave it stopped, blocking until the port is free. Refuses while any loop is live — naming each run’s pid, repo and ticket — since a loop with no hub can neither checkpoint nor reach its tracker; --force parks those runs at their checkpoints first.
trau hub <cmd>: Manage the hub: start it if nothing is listening, restart it onto the current on-disk binary (--force to clear a wedged one), or supervise / unsupervise it so launchd brings a crashed hub back on its own.
trau doctor: Preflight check: git, gh, the provider CLI, config sanity, tracker labels, and write permissions. Exits non-zero on any failure, so it drops cleanly into CI.
trau watch: Tail a running loop’s live agent activity from another shell — the headless counterpart to the TUI’s w key and the hub’s Terminal page.
trau steer <ID> <note>: Queue an operator note for a running ticket without stopping it — it reaches the agent mid-phase, or at the next spawn if the run is between agents. Pass "-" to read the note from stdin. Needs a hub already up.
trau takeover <ID>: Stop the run and resume that ticket’s recorded claude session in this terminal. The repo stays locked for as long as the terminal lives; the ticket parks when you close it.
trau forensics <cmd>: Read-only incident queries over the run history: runs, events, spend. See trau forensics --help.
trau --no-serve: Skip the hub autostart for this TUI session.
trau --once: Process the next eligible ticket end-to-end, then exit.
trau --list-eligible [--json]: List the tickets the loop would consider, in pick order, without running anything.
trau --yes: Skip interactive confirmations — for scripted or unattended launches.
trau <ID>: Run one specific ticket; an epic with sub-issues fans out onto an epic branch.
trau --parent <ID>: Treat <ID> as an epic and process its sub-issues (a bare <PREFIX>-<n> arg is equivalent).
trau --dry-run: Show the next eligible ticket without executing — changes nothing on disk.
trau --status [--json]: Print durable checkpoints plus token and cost totals. Add --json for machine-readable output.
trau --reset <ID>: Drop the branch and state and re-queue the ticket. Refuses if it is already merged unless --force is given.
trau --clear <ID>: Drop only the local checkpoint — no git, no re-queue — for tickets finished out-of-band.
trau --max <N>: Cap iterations for this run, overriding MAX_ITERATIONS.
trau --no-resume: Skip the resume scan and always pick a fresh ticket.
trau --repo <path>: Operate on a repo other than the current directory.
trau --provider <name>: Override the configured provider for this run (claude | codex | kimi).
trau --no-tui: Force plain log output instead of the Bubble Tea TUI.
trau --verbose / --debug: Extra stderr diagnostics: --verbose shows what the loop is doing; --debug also logs every git/gh command invoked.
trau --version: Print the installed version.
trau --help: List every command and flag.

Safety

trau is experimental and it changes code on its own: it edits the target repo, opens PRs, and by default auto-merges green ones. Point it only at a checkout you are willing to have modified autonomously.

Preview first — trau --dry-run shows the next ticket and planned phases without touching disk.
Preflight — trau doctor checks git, gh, the provider, config, and tracker labels before a run can fail mid-phase.
Bounded by design — MAX_ITERATIONS, MAX_REPAIRS, and MAX_BUGFIXES cap how far a run goes.
Spend caps — MAX_TICKET_USD / MAX_TICKET_TOKENS quarantine a runaway ticket, and MAX_DAILY_USD / MAX_DAILY_TOKENS stop the run at a daily budget.
Quarantine on failure — a ticket that exhausts its repair budget gets the QUARANTINE_LABEL and is left for a human.
Per-agent timeout — AGENT_TIMEOUT halts a stuck phase and writes a transcript as evidence.
Stop at the PR — set AUTO_MERGE=0 to keep a human in the merge loop.
Hub exposure — the hub is loopback-only by default; anything beyond requires SERVE_TOKEN. See Remote access.