trkr

Appearance

Getting Started ​

Prerequisites ​

  • Node.js 20+
  • The gh CLI, authenticated (gh auth login) — all GitHub access goes through it. Projects v2 needs the project token scope; trkr init detects a missing scope and offers to run gh auth refresh -s project for you.
  • An AI agent CLI on your PATH — Claude Code (claude) by default; Copilot and Kiro are also built in

Install ​

bash
npm install -g @barry-napier/trkr

Or build from source (pnpm required):

bash
git clone https://github.com/barry-napier/trkr.git
cd trkr
pnpm install
pnpm build
npm link

Create a board ​

From inside any GitHub repository:

bash
trkr init

This creates a Projects v2 board linked to the repo, sets up the Status columns (derived from your enabled workflows), adds a Workflow single-select field, and writes .trkr.json with the project IDs. Re-running init after changing workflows migrates the board by appending any missing columns (existing columns are never removed).

File a ticket ​

bash
trkr new "search results should paginate past 100 items"

An intake session classifies the request into a workflow (feature, bugfix, chore, …), then grills you: an interactive interview that surfaces every open decision, one question at a time, each with recommended answers you pick with a single keystroke. Facts are never questions — anything discoverable in the repo, the session looks up itself. A clear request converges in zero questions.

When the interview finishes, a spec session writes one or more tickets with acceptance criteria honoring your answers, wires blocked_by dependencies between them, and boards everything. trkr new always ends with tickets on the board — nothing is parked.

For an effort you already know is big and foggy, use trkr scope instead: it names the destination, breaks the fog into decision tickets, and the daemon collapses the map into a boarded spec once every decision resolves — see the CLI reference.

Run the orchestrator ​

bash
trkr start

The daemon polls the board and runs agent sessions to move tickets through the pipeline. Freshly boarded tickets sit in Backlog, which is inert — kick one off by dragging it into its first stage's column (Spec for feature/bugfix, Implement otherwise); every transition after that is automatic. Check on the daemon with:

bash
trkr status

Stop it with trkr stop. When a ticket exhausts its turns it gets the trkr:blocked label — fix the underlying issue and put it back in play with trkr unblock <issue>.

The human touchpoints ​

trkr is deliberately autonomous in the middle and human at the edges:

  1. Intake — you file the ticket and answer the grilling interview; every open decision is resolved before boarding.
  2. Kick-off — you drag the boarded ticket out of Backlog to start the pipeline.
  3. Blocked — tickets that fail three verification turns stop and wait for you.
  4. Merge — every workflow ends with an agent review pass, then trkr requests your review on the PR and moves the ticket to Done. You merge; trkr never does.