Documentation

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 source host CLI, authenticated (gh auth login). trau opens and merges PRs through it on source host. 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, kimi, or auggie. Auggie ships on npm and needs Node 20+ (npm install -g @augmentcode/auggie, then auggie login); Augment publishes no native Windows build, so on Windows run it inside WSL2.
• An issue tracker — Linear, Jira, Azure DevOps Boards, or source host 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.

# macOS / Linux / WSL2 — no license key needed; the free trial starts in the hub.
# It installs to $HOME/.local/bin without sudo; TRAU_INSTALL_DIR=<absolute dir> picks another directory:
curl -fsSL https://get.trau.sh/install.sh | sh
trau --version

# Already hold a license key? Pass it and the installer stores it:
curl -fsSL https://get.trau.sh/install.sh | TRAU_LICENSE_KEY=<your-key> sh

# Later: update in place from the terminal, or Settings → Updates in the hub:
trau update            # trau update --check only reports what is available

# Store a key by hand — after a manual install, or when it changes:
trau license set <your-key>

# Linux / WSL2 packages — .deb and .rpm (amd64 and arm64):
V=$(curl -fsS "https://get.trau.sh/v1/latest" | sed -n 's/.*"version": *"\([^"]*\)".*/\1/p')
curl -fsSL -o trau.deb "https://dl.trau.sh/v1/download/$V/trau_${V}_linux_amd64.deb"
sudo dpkg -i trau.deb   # Debian, Ubuntu — .rpm + rpm -i on Fedora, RHEL, openSUSE

# swap amd64 for arm64 on an ARM machine — no license key needed
$v = (Invoke-RestMethod "https://get.trau.sh/v1/latest").version
Invoke-WebRequest "https://dl.trau.sh/v1/download/$v/trau_${v}_windows_amd64.zip" -OutFile trau.zip
Expand-Archive trau.zip -DestinationPath "$env:LOCALAPPDATA\trau" -Force

# put it on your PATH (new shell afterwards)
[Environment]::SetEnvironmentVariable("Path", "$env:LOCALAPPDATA\trau;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")
trau --version

# optional: already hold a license key? store it
trau license set <your-key>

# from then on, trau update or the hub’s Update to X swaps trau.exe for you

Or build from source (Go 1.27+):

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. With no license yet, the hub opens on a lock card: enter your email and the 6-digit code we mail you, and the 14-day trial starts (see Trial and license). The New 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.

trau hub start   # runs the hub as a service
# then open http://127.0.0.1:8728

# trau serve runs the hub in the foreground instead —
# it stops when you close the terminal

First run, terminal path: cd into a repo that has no project config layer and run trau with no arguments. The TUI onboarding wizard walks you through tracker, branch, and provider, writes the project and user config layers to the Hub database — and brings the hub up first, before it even resolves the repo.

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.

Trial and license

trau installs with no license key. The first time you open the hub without one, it shows a lock card: enter your email, type the 6-digit code we mail you, and a 14-day trial starts — every feature, no card. There is one trial per email and one per install.

To keep going, subscribe from inside the hub. It opens a Stripe checkout page; once the payment goes through, the license upgrades itself and a mail brings you the license key. There is one plan, Trau Solo, billed monthly or annually — prices are on trau.sh/#pricing and in the app.

• Two installs per license. To move trau to another machine, release the one you no longer use from the hub, then start trau on the new one.
• Manage subscription in the hub opens the Stripe customer portal: cancel, change the card, or download invoices.
• A paid license keeps working for 7 days without a connection, so a flight or a flaky network does not stop the loop.
• Already hold a key? Pass TRAU_LICENSE_KEY=<your-key> to the installer, or store it on an existing install with trau license set <your-key>. A perpetual key keeps working as it always has.

When the trial ends, a payment fails or the subscription ends, trau locks:

Cancel at any time from Manage subscription in the hub. Refunds and the EU right of withdrawal are on trau.sh/refunds.

The hub

trau hub start runs the hub as a service: 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. (trau serve runs the same hub in the foreground, tied to your terminal.)

The whole UI is keyboard-first. ⌘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. ⌘P switches projects, ? opens the shortcuts sheet, g then a letter jumps straight to a page, and j/k or the arrow keys walk rows on Backlog, Loop, Inbox, and the runs ledger — with per-page keys for expanding, archiving, reordering the queue, and starting runs.

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 (on the Hub page) and the needs-attention set reaches you with a deep link to the run or ticket that wants you; come back later and an away recap summarises what happened while you were gone.

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. Hub → 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.

Want the hub on your phone while the loop runs on your desktop? Tailscale is the blessed path — a private tailnet, not a public port. trau hub remote on publishes the running hub and prints its tailnet URL with a QR code to scan; status reports what is published, off takes it down again, and --take moves a forward that is already pointing elsewhere. SERVE_REMOTE=tailscale makes it the standing arrangement rather than a per-start command — every hub start reconciles the forward, so a reboot or a changed SERVE_PORT comes back reachable on its own. Settings → Remote access shows the same URL, a copy button and the QR, offers to publish this hub here when a live forward points somewhere else, and says plainly when the tailnet is down or signed out.

What you reach on the phone is laid out for it. Below the tablet breakpoint the hub switches to a mobile shell with a bottom nav, and every route — overview, the loop, the runs ledger and run detail, the live run view, inbox triage and interviews, backlog and settings — was designed at that width rather than left to reflow. Dialogs, drop-downs, the command palette and the terminal stay inside the viewport, wide tables and diffs scroll in their own frame, and anything that used to appear only on hover has a tap that reaches it.

Reaching the hub from another device changes what some links can do: a worktree app served on a localhost port or a Herd .test site only answers on the hub machine, so those URLs are drawn as host-only markers that explain themselves instead of links into nothing. State-changing API routes additionally require a same-origin request, so a page on another site cannot aim a drain or a restart at your hub.

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.

BUILD   build → handoff ‖ lintfix → cleanup
VERIFY  test gate → verify (fresh eyes) → repair/bugfix on fail → re-verify
SHIP    commit → PR → CI → QA hold (if armed) → merge

• Build — writes the code against the ticket, its acceptance criteria, and its non-goals, then distills a handoff brief while the style chain — lint autofixers, then an AI-slop strip — runs alongside it.
• Verify — a deterministic test gate first (a failing suite supplies the verdict without spending an agent), then a fresh, skeptical agent that sees only the brief and the diff. It grades the work, runs the repo’s verify-check library, drives the app in a browser on UI slices, 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, holds for your approval when the QA gate is armed, 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. A run can also park on purpose — awaiting-pick holds mid-build for a design choice (see Design picks), and awaiting-qa holds a finished run for your approval before merge (QA_GATE=1). Those are holds, not failures: the lane frees at once and the work stays healthy.

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.

Parallel lanes (worktrees)

With WORKTREES=1, trau stops working one ticket at a time. Every run is provisioned its own git worktree — its own checkout, its own branch, and (with an app command) its own running app — created under WORKTREES_DIR as <dir>/<repo>/<ticket> and removed when the ticket settles. Your registered checkout stays yours: a dirty working copy never blocks a run and never gets stashed.

Every eligible queued ticket then drains at once, one spawn per tick — there is no lane cap, so the ceiling is your provider quota, CPU and disk rather than a number you set, and any shared dev database or port stays WORKTREE_SETUP_CMD’s to separate. An epic takes a single lane and its children share the epic’s tree, so a release never interleaves with itself. The Loop screen shows every lane live, including a starting lane while a tree is still being provisioned and which stage it is on, and the hub’s Worktrees page (via ⌘K) lists every provisioned tree.

Provisioning is three steps: the tree gets the checkout, WORKTREE_COPY globs of gitignored files are copied over from the registered root (.env and .env.* by default), and WORKTREE_SETUP_CMD runs with the tree as its working directory (npm ci, composer install, …). A non-zero exit parks the run and keeps the tree for inspection.

Each lane can serve its own app, and APP_SERVE picks how. Point APP_START_CMD at how the project runs and every worktree boots it on its own port, allocated upward from WORKTREE_PORT_BASE. On a Laravel machine running Herd, the tree is instead linked as its own site and served at http://<ticket>.test — mirroring the repo’s main site best-effort, so a secured main site makes the tree’s URL https and rewrites APP_URL in its .env, and an isolated one pins the tree to the same PHP version; both are undone when the tree settles. Either way the run page links straight to that instance with start/stop (or link/unlink) controls and a live log tail — Herd trees tail the tree’s own Laravel log — so browser verify, the QA hold, and the design-pick hold all drive the branch under test instead of your dev server.

Design picks (ui.sh)

A design choice is not a correctness question, so trau refuses to let the agent make one silently. When a build routes the ui.sh ideas skill, the agent lays out several annotated UI variants with a picker toolbar injected into the app, then parks the run at awaiting-pick instead of choosing for itself. The queue lane is freed at once — the drain keeps moving — while the branch, its work-in-progress, and its app stay up for whoever does the choosing.

Setup is two steps. Install: put your ui.sh account token in Settings as UIDOTSH_TOKEN, and the hub’s Skills page becomes a skills manager — browse the catalogue your account owns, install, update, and remove, with everything landing in user scope under ~/.claude/skills. Route: add ideas to REQUIRED_SKILLS, or to a rule in .trau/skills-rules.json so only design-flavored tickets carry it. Routing the skill is the whole opt-in — there is no arming toggle — and a build that routes it but ends without laying out variants finishes exactly as it always did.

The hold lives on the run page: every decision with its options, and — with worktrees on and APP_START_CMD set (see Parallel lanes) — a link to the branch’s own served app, so you click through the real variants rather than screenshots. A repo serving no app still holds; the card works from the labels alone. Submitting is all-or-nothing, one choice per decision, and resumes the run: a fresh finalize agent keeps what you picked, removes the rest, strips every trace of the picker scaffolding, and only then hands off to verify → commit → PR → CI as usual. That finalize (and each regenerate) is the PICK phase in per-phase model routing.

“None of these” is also an answer. Rejecting every variant requires notes on what is wrong and buys a regenerate round: one agent cleans the rejected round away, lays out fresh variants that answer your notes, and comes back to the same gate. Rounds are bounded by PICK_ROUNDS; a regenerate past the bound parks the run for a human with your notes as the reason.

Configuration

trau stores its project and user config layers in the Hub database. The remaining file layer is ./trau.ini — a flat INI subset (KEY=value with # comments) for local overrides. Config keys are also environment-variable names, so PROVIDER in a layer and TRAU_PROVIDER in your shell are the same knob. Settings resolve in layers, from lowest to highest precedence:

A minimal project config layer contains values like these:

TRACKER_PROVIDER=linear     # linear | jira | azure | github
LINEAR_TEAM=YourTeam        # team name / Jira key / Azure project / source host 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

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.

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, commit, and pick fall back to Sonnet and lintfix to Haiku unless you route them yourself.

# 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 (kimi routes models only — its CLI exposes no per-phase effort knob). 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.

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.

Machine trust is the default posture: CLAUDE_FLAGS and CODEX_FLAGS ship with the providers’ permission-skip flags (--dangerously-skip-permissions, --dangerously-bypass-approvals-and-sandbox), because an autonomous loop cannot stop to click Approve. Point trau only at checkouts you are willing to have modified autonomously — and to restore approval prompts, set the FLAGS key yourself: a present-but-empty value overrides the default.

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.

The QA gate

QA_GATE=1 holds every run after its CI goes green and before it merges, in a durable awaiting-qa state with its own strip in the run ledger. The lane is freed while it waits — the queue starts the next item — and the worktree and its app stay up, so you drive the branch under test rather than reading a description of it.

Approve merges. Reject requires notes on what is wrong and spawns a bounded fix round that returns to the same gate. The repo-wide default is only a default: each queued item’s own Hold-for-QA choice in the run-steps dialog overrides it in both directions. The QA gate and the design-pick hold are independent — one run can hit both, the pick before verify and QA after CI.

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.

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.

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.

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

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.

CLI reference

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.
• Own lane — WORKTREES=1 keeps every run in its own per-ticket worktree, out of your working copy.
• 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, or QA_GATE=1 to hold even green runs for your approval.
• Hub exposure — the hub is loopback-only by default; anything beyond requires SERVE_TOKEN. See Remote access.