Commands
trailhead is user-invoked (it won’t fire on its own). The first word is the verb; the rest is text or a ticket number. With no verb, /trailhead does smart entry: it inspects the repo and proposes the right next move.
Every verb is also a namespaced command (/trailhead:new, /trailhead:work, /trailhead:bug, …) so typing /trailhead lists them all in the command picker. /trailhead <verb> and /trailhead:<verb> are equivalent.
There are 24 verbs in five clusters. Each row below links to that verb’s guide, which gives its syntax, arguments, what it does step by step, what it writes, and an example:
- Chart: start a map or bring outside work into it.
- Work: resolve tickets and manage their lifecycle.
- View: read-only renders of the map, dashboard and whiteboard, and the live map panel.
- Capture: zero-friction capture of tickets, fog and notes.
- Manage: config, update, prune, and audit.
Smart entry
Section titled “Smart entry”| Command | What it does |
|---|---|
/trailhead | smart entry: detect state and propose |
Give a map its start, or bring outside work into it. Full guide.
| Command | What it does |
|---|---|
/trailhead:new [idea] | chart a new map from a loose idea |
/trailhead:adopt | adopt an existing project (map the codebase once, then go lean) |
/trailhead:ticket <type> <title> | open a ticket on the fly (diverges briefly first: a micro-charting act) |
/trailhead:inbox [issue] | triage issues opened by others and integrate the good ones into the map |
/trailhead:grill [topic] | run a standalone grilling session on a decision/topic |
Resolve tickets and manage a ticket’s lifecycle. Full guide.
| Command | What it does |
|---|---|
/trailhead:work [ticket] | work the next frontier ticket, or the one you name |
/trailhead:quick [ticket | "text"] | work one ticket whole, never splitting: "text" opens a whiteboard ticket off the map; <n> takes an existing ticket (a map ticket stays on its map), runs the full engine, grills only if needed |
/trailhead:pause [note] | checkpoint the ticket in play so anyone can resume it |
/trailhead:resume [ticket] | resume a paused ticket from its PAUSED checkpoint |
/trailhead:split [ticket] | split an oversized ticket into children, supersede the original |
/trailhead:auto [map] | run the frontier autonomously, one ticket after another, until a stop condition (safety rail / fog / a human-necessary decision) or exhaustion; suspends one-ticket-per-session |
Read-only renders of where the work stands. Full guide.
| Command | What it does |
|---|---|
/trailhead:map | show the low-res map (destination, decisions, frontier, fog) |
/trailhead:dashboard | show the repo dashboard: the pinned index of every open map, the whiteboard, and live counts |
/trailhead:whiteboard | show the whiteboard: the loose (map-less) tickets and their frontier |
/trailhead:panel | open or close the live map panel: the active map’s open tickets by state, with a work button per frontier ticket (Claude Code with the trailhead mod only) |
Capture: zero friction, one confirmation line, resolves nothing
Section titled “Capture: zero friction, one confirmation line, resolves nothing”| Command | Lands as | Meaning |
|---|---|---|
/trailhead:todo <text> | a frontier ticket | I’m doing it: defined work, now |
/trailhead:seed <text> | a blocked ticket (trigger noted) | I’ll do it when X happens |
/trailhead:idea <text> | the fog (Not yet specified) | maybe I’ll do it: graduates to a ticket if it sharpens |
/trailhead:note <text> | verbatim text | remember this: not necessarily work |
/trailhead:bug [--of <ticket>] <text> | a bug ticket | a defect; --of records it as a Regression of: a closed ticket, filed where that ticket lives |
The four fog/ticket captures form a spectrum of commitment and timing: note < idea < seed < todo. See Captures & the whiteboard for the full spectrum and the whiteboard.
Manage
Section titled “Manage”Keep the install and the maps healthy. Full guide.
| Command | What it does |
|---|---|
/trailhead:config [get | set …] | the guided, menu-driven setup for .trailhead/config.json, or read and write one key; see Configuration |
/trailhead:update | check for a newer trailhead and install it, detecting how it was installed (dev-symlink, npm, or plugin) |
/trailhead:prune [map] | reclaim a map’s native sub-issue slots under GitHub’s 100 sub-issue cap by dropping the edges of closed and orphan tickets (every reference kept); offered automatically when a map is near or at the cap |
/trailhead:audit [map] [--all] | hunt regressions by checking that the tickets closed since the last audit are still true against the current code, and compare the open ones for duplicates and groupable clusters; read-only until you confirm, and every fix is a proposal applied only on an explicit yes |
Next: chart commands, the first of the five guides, or jump to Captures & the whiteboard for the commitment spectrum and Working as a team for how these commands behave with multiple contributors.