trkr

A ticket board and AI orchestrator for your repo. trkr creates a GitHub Projects v2 board and runs an agent daemon that moves tickets through an SDLC pipeline — spec, implement, review, and hand off to a human.

Docs: trkr.bnapier.dev

The idea

The board column is a contract boundary. Off-board (intake, spec) is human-in-the-loop; once a ticket boards, the daemon owns it: it moves tickets between columns, runs a fresh AI agent session per stage in a per-ticket git worktree, and enforces hard gates — stages must mechanically prove their artifacts exist. Every workflow terminates in an agent review pass, then trkr requests your review on the PR and moves the ticket to Done. Nothing auto-merges, ever.

• Board state lives on GitHub (issues + Projects v2 + native blocked_by dependencies) — no separate database.
• Provider-agnostic: agents are shell command templates (claude by default; Copilot and Kiro built in). Intake asks who works each ticket and stamps it on the board's Agent field — the daemon runs that provider for the ticket's stages.
• 3 verification turns, then the ticket is Blocked and waits for you (trkr unblock <issue>).
• Local-first OTel-shaped telemetry: one trace per ticket turn, no sampling, every failure replayable.

Quick start

# prerequisites: node 20+, authenticated `gh` CLI, an agent CLI (e.g. `claude`)
npm install -g @barry-napier/trkr

cd ~/your/repo
trkr init                          # create the board
trkr new "add pagination"          # grill + spec + board a ticket
trkr start                         # run the orchestrator
trkr status                        # watch it work

Commands

| Command | What it does | |---|---| | trkr init | Create (or migrate) the board; writes .trkr.json | | trkr new <text> | Classify, grill, spec, and board a ticket | | trkr scope <text> | Map a large effort into decision tickets that collapse into a spec | | trkr resolve <issue> | Interview and close a grill-type decision ticket | | trkr start / stop / status | Control the daemon | | trkr unblock <issue> | Reset a blocked ticket's turns and restart its workflow | | trkr delete | Delete the board |

See the CLI reference and configuration docs for the rest.

Development

pnpm build       # plain tsc → dist/ (the global `trkr` runs dist/)
pnpm test        # vitest
pnpm typecheck
pnpm docs:dev    # this docs site, locally

ESM only. GitHub access goes through the gh CLI (GraphQL) — no vendor SDK.

License

MIT