CLI Commands

trkr — a ticket board and AI orchestrator for your repo

Board

trkr init

Creates a Projects v2 board for the current repo: project, board view, Status columns (derived from enabled workflows), Workflow single-select field, and writes .trkr.json. Asks for confirmation before creating.

Re-running against an existing board is a migration: any missing columns are appended (existing columns are never removed, since items live in them) and the Workflow field's options are reconciled. If .trkr.json points to a deleted project, the board is recreated.

Fails with exit 1 if not inside a GitHub repository or gh is not authenticated.

trkr new <text>

Files a ticket from a natural-language description and always ends with it on the board. An intake session classifies the request into a workflow (shown for confirmation, overridable interactively; unknown workflow names fall back to default_workflow, default feature), then:

1. Grill — an interactive interview surfaces every open decision before anything boards. Facts are never questions (the session looks them up in the repo itself); each question comes with recommended answers you pick with one keystroke. A genuinely clear request converges in zero questions. If the interview detects real sprawl it stops and points you at trkr scope.
2. Spec — a spec session writes TicketSpecs (title, body, blocked_by) honoring the interview's decisions. A spec that still contains an ## Open questions section is treated as a failed round: the interview resumes over those questions and the spec is rewritten (two rounds max, then the command fails — nothing half-specified ever boards).
3. Board — all issues are created first, then blocked_by dependency edges are wired, then every ticket is boarded (Workflow set, Status set to the workflow's first column — Backlog on the presets, where it waits for you to drag it forward).

trkr scope <text>

Maps a large effort — one you already know needs more thinking than one interview. Three phases:

1. Destination — an interview names the destination: the spec, decision, or change the effort is driving at. Scope is fixed by it.
2. Fog pass — a breadth-first session surfaces the open decisions. Each sharp question becomes a decision ticket (labeled map:<slug> and decision:<type>, typed research / prototype / grill / task); questions not yet sharp enough are recorded on the map issue (labeled map) as fog. Autonomous types board immediately under the research workflow; grill-type tickets await trkr resolve.
3. Collapse — when the daemon sees a map with no open decision tickets, it runs a collapse session that reads the map and every decision, writes an agent-sufficient spec, boards the resulting tickets, and closes the map.

trkr resolve <issue>

Interviews you about one grill-type decision ticket (same one-keystroke question loop as trkr new), posts the decision as an issue comment, and closes the ticket. Closing the last open decision on a map triggers the daemon's collapse.

trkr delete

Deletes the board (with confirmation) and removes .trkr.json. If the project is already gone, just removes the stale .trkr.json.

Orchestrator

trkr start / trkr stop

Start / stop the daemon.

trkr status

Shows daemon state and the current ticket.

trkr watch

Full-screen live dashboard. Starts the daemon first if none is running (same as trkr start), so trkr watch alone brings the pipeline up. Top to bottom:

• Header — repo (centered), daemon pid, uptime, last poll; a progress bar of done/total tickets with the run state (RUNNING / IDLE / STOPPED).
• Ticket — the selected ticket: column, workflow, turn count, current stage with elapsed time, its history from the daemon log, and a link to the GitHub issue.
• Board — every ticket with a state glyph (✓ done, ● active dispatch, ◐ mid-pipeline, ○ waiting, ✖ blocked) and its column, colored to match the board.
• Worker — live tail of the selected ticket's newest agent session (streamed tool-by-tool for the claude provider), marked running or ended. Moving the selection swaps the session shown.
• Log — the daemon log tail with relative timestamps; routine polls dimmed, dispatches/merges/failures highlighted.

Local state refreshes every second; the GitHub board every 15 seconds. Keys: ↑/↓ (or k/j) select a ticket, r refresh the board now, esc (or q) quit. The selection follows the active ticket until you move it.

trkr unblock <issue>

Puts a blocked ticket back in play: clears its turn counter, removes the trkr:blocked label, and moves it to its workflow's first column (Backlog on the presets — drag it forward to restart the pipeline). If that column is missing (workflow changed since boarding), run trkr init to migrate first.

Global options

• --version — prints the version from package.json.
• --verbose — enable verbose mode.