Getting started

Runs on Claude Code and Codex CLI. trailhead is authored once; the installer projects host-native artifacts. On Claude Code: a skill + /trailhead:* commands + hooks. On Codex CLI: a native skill invoked $trailhead, one $trailhead-<verb> skill per verb for discoverability, and the guardrails as native Codex hooks. Choose the host with --claude / --codex, or let the installer auto-detect.

Prerequisites

An authenticated gh CLI (the tracker is GitHub Issues).
A GitHub repo to work in.
For the npm path, Node 18+.

Install

Native install, managed by /plugin:

/plugin marketplace add ToRvaLDz/trailhead
/plugin install trailhead@trailhead

Update with /plugin update trailhead; remove with /plugin uninstall trailhead.

Installs into your agent’s config dir:

npx @marcomigozzi/trailhead              # auto-detect the host (defaults to ~/.claude)
npx @marcomigozzi/trailhead --claude     # Claude Code (~/.claude or $CLAUDE_CONFIG_DIR)
npx @marcomigozzi/trailhead --codex      # Codex CLI ($CODEX_HOME or ~/.codex)
npx @marcomigozzi/trailhead --symlink    # dev install (Claude; symlink to the checkout, edits go live)
npx @marcomigozzi/trailhead --uninstall  # remove everything it added (pair with --claude / --codex)
npx @marcomigozzi/trailhead --dir=<path> # target a specific config dir

On Claude Code it copies the skill (+ its references/), the /trailhead:* commands, the hooks (into hooks/, registered in settings.json) including a SessionStart update check, and the label-guard + statusline templates, idempotently.

npx @marcomigozzi/trailhead --codex projects a native Codex skill invoked as $trailhead ($trailhead work, $trailhead new "idea", …), one thin $trailhead-<verb> skill per verb for discoverability, the six guardrails as native Codex hooks (~/.codex/hooks.json, enabling features.hooks; the four Bash guards share one process behind a single registration; the search guard is Claude-Code-only and isn’t projected to Codex), and per-technique subagent model pins from models.codex.* into ~/.codex/agents/.

Codex 0.145.0+ is required (the installer gates on codex --version). The artifacts mockup mode (Claude Code’s Artifact tool) isn’t available on Codex; the cross-host design: stitch mode (Google Stitch MCP) is the hosted option there, with local disk as the fallback.

Re-run the install to update, or run /trailhead:update (Claude) / $trailhead update (Codex) from inside the agent: it detects how trailhead was installed and installs the newer version where that is safe. Release notes are in the CHANGELOG.

After installing

Restart or reload your agent so the commands register, then run /trailhead to start (smart entry), or /trailhead:new "<idea>" to chart a map. On Codex the surface is $trailhead instead: run $trailhead for smart entry, $trailhead new "<idea>" to chart, or a per-verb $trailhead-<verb> skill.

Note: once installed, the commit guard hook runs on every git commit (enforcing Conventional Commits and blocking Co-Authored-By); disable the plugin’s hooks in settings if you don’t want that. Either way trailhead is self-contained: no external skill or plugin is required, no preflight, no version drift.

Next: read Core concepts for the map/ticket/frontier/fog vocabulary, or jump straight to Commands for the full verb list.