XTRM-Tools

xtrm (xt) is an agentic workflow system that turns Claude Code and Pi into disciplined, self-managing development agents. Every session is structured, every change is tracked, and every agent knows exactly what to do next.

Beads — issue tracking built for agents

Beads is a Dolt-backed issue tracker designed for agentic workflows. Issues are first-class citizens: agents claim them before editing, close them before committing, and carry context forward across sessions and machines via persistent memory. The full bd CLI is available inside every session — bd ready, bd update <id> --claim, bd close <id>, bd remember.

Hooks — enforcement gates that run automatically

A policy compiler produces hooks for both Claude Code and Pi from a single source. These gates enforce the workflow without relying on the agent to remember: the Edit gate blocks writes without an active claim, the Commit gate blocks git commit until the issue is closed, the Stop gate checks for unclosed work at session end, and the Memory gate prompts the agent to persist insights before exiting. Quality gates run ESLint, tsc, ruff, and mypy automatically on every file save.

Skills — reusable agent behaviors

A library of composable skills covers the full development lifecycle: session management (using-xtrm), structured planning (planning), test coverage strategy (test-planning), autonomous session close (xt-end), PR queue management (xt-merge), documentation synchronization (sync-docs), and domain expertise (backend, devops, security, data science). Skills are injected into the agent context on demand.

Planning mode

The planning skill generates a structured issue board from any spec or idea — epics, tasks, dependencies, test coverage annotations — using bd create in parallel. Agents can pick up and continue planned work across sessions with full context. GitNexus impact analysis is integrated into the planning flow so blast radius is assessed before a single line is written.

Statusline

A live statusline renders in every Claude Code session: active claim, open issue count, model, context window health (color-coded truecolor gradient), and token usage — all in a single line below the prompt. No configuration required after xtrm init.

Specialists

sp (@jaggerxtrm/specialists) is the runtime companion for specialist execution (sp run, sp view, sp render-task). xtrm-tools vendors specialist-owned skills into ~/.xtrm/skills/default/ (global SSOT) and keeps user-authored packs under ~/.xtrm/skills/user/packs/. Consumer repos carry project packs at .xtrm/skills/<pack>/ — the new service-knowledge pack (service-knowledge at .xtrm/skills/<pack>/service-knowledge) is resolved at xt pi --role / xt claude --role launch time: bare logical names like service-knowledge are matched against enabled views, project packs, and the global default (xtrm-lk07w.14). The release-contract handshake runs through .github/workflows/specialists-validation.yml; sp is a runtime prerequisite for specialist commands.

Version 0.11.6 | Complete Guide | Changelog

Documentation

| Doc | Contents | |-----|----------| | XTRM-GUIDE.md | Complete reference — architecture, concepts, full workflow | | docs/hooks.md | All hooks — event wiring, gate logic, order, authoring | | docs/policies.md | Policy system — compiler, schema, Claude/Pi parity | | docs/skills.md | Skills catalog — all skills, categories, how they load | | docs/release.md | Release contract — specialists handshake, publish gates, runtime prereqs | | docs/skills-ownership.md | Skills ownership — vendored vs owned skills, publish contract | | docs/xtrm-directory.md | .xtrm/ directory layout — managed assets and user fallback | | docs/skills-tier-architecture.md | Skills tiers — global SSOT + project residual state | | docs/plans/global-skills-migration.md | Global skills migration — architecture and operator workflow | | docs/pi-extensions.md | Pi extensions — managed sync, authoring, parity notes | | docs/worktrees.md | xt worktrees — xt claude/pi, xt attach, xt end, isolation model | | docs/xt-pi-role.md | xt pi --role / xt claude --role — specialist launcher: flags, behavior matrix, pane options, XTMUX_AGENT_* env, coordination pattern | | docs/mcp-servers.md | MCP servers — gitnexus, github-grep, deepwiki, official plugins | | docs/bash-tools.md | Bash-native specialist CLIs — ghgrep, ctx7, deepwiki | | docs/cli-architecture.md | CLI internals — install flow, diff/sync engine, config merge | | docs/docs-commands.md | Docs command suite — show, list, cross-check, output modes, drift checks | | docs/project-skills.md | Legacy project-skill migration notes and current asset location | | docs/cat-b-distribution.md | Cat B distribution ownership, migration policy, Windows stance | | docs/testing.md | Live testing checklist — integration, gates, worktree flows | | CHANGELOG.md | Full version history |

Quick Start

# Install globally (one-time)
npm install -g xtrm-tools

# Bootstrap global skills tree (one-time per HOME)
xt bootstrap

# Set up xtrm in your project
xtrm init

# Verify
xt --version
xt doctor

One-line run:

npx -y github:xtrm-dev/core init

Typical workflow after install:

# Start a sandboxed session in a worktree
xt claude my-feature
# or with a bead + specialist role (skills auto-loaded at turn 1)
xt pi --role planner --bead <id>
xt claude --role reviewer --bead <id> --prompt 'review the auth changes'

# Publish that worktree: rebase, push, open PR, optional cleanup
xt end

# Refresh project memory from bd memories + current repo state
xt memory update

# If multiple xt/* PRs are open, drain the merge queue oldest-first
xt merge

Launch xt pi --role <name> / xt claude --role <name> resolves skills via sp view <name> — bare names like service-knowledge are resolved from project packs (.xtrm/skills/<pack>/service-knowledge), then enabled views, then global default. See docs/xt-pi-role.md for flags (--bead, --prompt, --model, --skill, --subordinate) and the Pi/Claude behavior matrix.

xt end handles one worktree session at a time. xt merge is the follow-up queue operator: it inspects open xt/* PRs, processes them FIFO, waits for green CI on the oldest PR, merges it with --rebase, then rebases the remaining queued xt branches and repeats. xt memory update shells out to the memory-processor specialist, which condenses bd memories and current project state into .xtrm/memory.md; use --dry-run to inspect without writing.

Keeping xtrm and specialists updated

Update the installed packages first. xt update reads assets from the globally installed xtrm-tools package, so an old global install cannot deliver new skills.

npm install -g xtrm-tools@latest @jaggerxtrm/specialists@latest
xt --version
sp --version

Refresh one repo or a whole fleet. xt update is a dry-run by default; add --apply to write changes. Current versions also check bd/GitNexus maintenance and apply the bd auto-stage patch (export.git-add=false plus a pre-commit JSONL stage shim) so bd writes stay quiet mid-work while commits still include the latest .beads/issues.jsonl snapshot.

# Preview drift
xt update --repo .
xt update --root ~/dev
xt update --root ~/projects
xt update --all-repos          # shorthand sweep for ~/dev + ~/projects

# Apply managed asset updates
xt update --apply --repo .
xt update --apply --root ~/dev
xt update --apply --root ~/projects
xt update --apply --all-repos  # patches and commits each changed repo

Enable optional packs and verify the active view:

xt skills enable code-quality          # default: --global
xt skills enable xt-optional --global  # senior-*, docker-expert, python-testing, obsidian-cli
xt skills list                         # global inventory
xt skills list --local                 # composed project view

If a repo is reported as incomplete or a newly shipped skill is missing, rebuild the active view:

cd <repo>
xt init -y
xt update --apply --repo .

# Verify a shipped skill landed and is active
ls ~/.xtrm/skills/default/issue-triage/SKILL.md    # Global SSOT
ls -l ~/.xtrm/skills/active/issue-triage           # Global active view
ls -l .xtrm/skills/active/issue-triage             # Project composed view
ls -l .claude/skills/issue-triage                  # Claude runtime pointer

Global Skills Migration

Migrate existing per-repo skills to global SSOT:

# Bootstrap global tree (one-time per HOME)
xt bootstrap

# Per-repo migration (dry-run first)
cd <repo>
xt migrate skills --dry-run
xt migrate skills --apply

Full workflow: docs/plans/global-skills-migration.md

Check specialists runtime drift separately from xtrm-managed skills/hooks:

sp doctor --check-drift
sp prune-stale-defaults --dry-run --root <repo-or-root>
# after review, prune redundant defaults only:
sp prune-stale-defaults --root <repo-or-root>

What's Included

Core Enforcement

| Component | Runtime | Purpose | |-----------|---------|---------| | Beads Gates | both | Issue tracking — edit/commit/stop gates, memory prompts | | Session Flow | both | Claim sync, stop gate, xt end reminder in worktrees | | Quality Gates | both | Auto linting (ESLint, tsc, ruff, mypy) on file edits | | GitNexus | Claude | Knowledge graph context for code exploration | | Service Knowledge | both (Pi + Claude) | Project-pack resolution — consumer repos carry .xtrm/skills/<pack>/service-knowledge; bare service-knowledge resolved at xt pi --role / xt claude --role launch (xtrm-lk07w.14) |

Privacy & Telemetry

xtrm-tools does not collect any telemetry or analytics. No usage data, no codebase scanning, no phone-home behavior. All operations run locally in your environment.

Skills

Skills are resolved through a three-tier registry in .xtrm/skills/ (default + optional + user). xt init populates the global catalog; activate optional packs with xt skills enable <pack> (default scope: --global). Current optional packs (six): research-methods, code-quality, security-ops, data-engineering, architecture-design, and xt-optional (holds senior-backend, senior-devops, senior-security, senior-data-scientist, docker-expert, python-testing, obsidian-cli). Full live catalog: xt skills list / docs/skills.md.

Skills are organized into two categories: xtrm workflow skills built specifically for the xtrm stack, and general-purpose expert skills that work in any project.

xtrm Workflow Skills

These skills implement the xtrm-specific development workflow — session management, issue tracking, planning, quality, and documentation patterns.

| Skill | Purpose | |-------|---------| | using-xtrm | Session operating manual — when to use which tool | | using-quality-gates | Quality gate workflow — TDD guard, lint/typecheck cycle | | using-tdd | Test-driven development with 80%+ coverage enforcement | | using-script-specialists | One-shot sp script specialist invocation (template-driven, no beads) | | xt-end | Autonomous session close — rebase, push, PR, cleanup | | xt-merge | FIFO PR merge queue for xt worktree sessions | | planning | Structured issue board from any spec, with phases and deps | | test-planning | Test coverage planning alongside implementation work | | delegating | Cost-optimized task delegation to background agents | | using-specialists | Specialist routing and execution workflow (vendored contract) | | using-specialists-auto | Auto-mode specialists execution and handoff flow | | update-specialists | Reconcile specialists runtime drift vs xtrm-managed assets | | update-xt | Refresh xtrm-managed assets across one repo or many | | issue-triage | Board hygiene: semantic duplicate clustering and graph rewiring | | releasing | Release-contract workflow and publish gating | | xt-debugging | Runtime debugging, traces, and failure triage | | init-session | Session bootstrap and context setup | | session-close-report | End-of-session report generation and handoff | | starting-and-resuming-work | Orient, delegate, and hand off across sessions | | multiplexing / multiplexing-team | Terminal multiplexing + team coordination primitives | | sre-triage | SRE incident triage (service-knowledge aware) | | deploy-monitor | Deploy verification (service-knowledge aware) | | capacity-reclaim | Capacity forecasting and safe reclaim (disk/tmpfs/swap/inodes) | | verified-audit | Over-engineering and efficiency audits | | spec-dispatch | PRD → runnable bd board compilation | | sync-docs | Doc audit and structural sync across a sprint | | skill-creator | Create, improve, and evaluate skills | | specialists-creator | Create and validate .specialist.yaml definitions | | find-skills | Discover and install skills on demand | | authoring-workflows | Author reliable agent workflows | | prompt-improving | Apply Claude XML best practices to prompts | | premortem | Pre-implementation risk analysis | | security-pipeline | Security scanning baseline (gitleaks, semgrep, osv-scanner) | | updating-dependencies | Dependency update workflow |

General-Purpose & Supporting Skills (curated)

A curated subset — the full live catalog is xt skills list / docs/skills.md. Domain packs like senior-backend, docker-expert, python-testing, and obsidian-cli live in the xt-optional optional pack (xt skills enable xt-optional).

| Skill | Purpose | |-------|---------| | clean-code | Pragmatic coding standards, no over-engineering | | code-review | Structured code review workflow | | hook-development | PreToolUse/PostToolUse hook authoring | | using-kpi / using-nodes | KPI tracking and distributed node workflows | | gitnexus-exploring | Navigate unfamiliar code via knowledge graph | | gitnexus-impact-analysis | Blast radius before making code changes | | gitnexus-debugging | Trace bugs through call chains | | gitnexus-refactoring | Plan safe refactors via dependency mapping | | gitnexus-cli / gitnexus-guide | GitNexus CLI and usage patterns | | deepwiki | Query repository/library docs via DeepWiki | | github-search | GitHub code and issue search (ghgrep) | | vaultctl | Obsidian vault control and automation | | last30days | Recent activity summarization | | find-docs | Discover documentation across sources | | agent-docs-maintainer | Maintain agent-facing documentation |

Policy System

Policies in policies/ are the single source of truth for all enforcement rules. They compile to both Claude hooks and Pi extensions.

| Policy | Runtime | Purpose | |--------|---------|---------| | beads.json | both | Issue tracking gates | | session-flow.json | both | Claim sync, stop gate, xt end reminder | | quality-gates.json | both | Linting/typechecking on file edits | | quality-gates-env.json | both | Warns if tsc/ruff/eslint missing at session start | | gitnexus.json | claude | Knowledge graph enrichment | | using-xtrm.json | both | Injects project memory without eagerly loading the using-xtrm skill | | worktree-boundary.json | claude | Blocks edits outside active worktree | | service-skills.json | pi | Territory-based skill activation |

node scripts/compile-policies.mjs           # Generate hooks.json
node scripts/compile-policies.mjs --check   # CI drift detection

See docs/policies.md for full schema and authoring reference.

CLI Commands

xtrm <command> [options]

| Command | Description | |---------|-------------| | claude | Launch Claude Code in a sandboxed worktree (--role for specialist roles) | | pi | Launch Pi in a sandboxed worktree (--role for specialist roles) | | init | Bootstrap xtrm with phased installer: machine → Claude → Pi → project | | status | Read-only diff view | | reset | Reset xtrm-managed state | | clean | [deprecated] Remove orphaned hooks — use xt update [--apply] | | end | Close worktree session: rebase, push, PR, cleanup | | worktree | Worktree operations: list, clean, reap | | attach | Re-attach to an existing worktree and resume the Claude/Pi/Codex session | | docs | Documentation inspection and drift-check suite | | memory | Memory synthesis and update flow | | merge | Drain queued xt/* PRs via xt-merge | | debug | Watch hook and bd lifecycle events in real time | | report | Session and workflow report generation | | skills | Skills catalog and enable/disable management (list, enable, disable, create-pack) | | claude-sync | Sync Claude-specific settings and managed state | | doctor | Health checks, drift, and Pi package reporting | | update | Refresh xtrm-managed files for one repo or many (--apply writes; dry-run by default) | | migrate | One-time per-repo migration: skills/hooks to global scope | | version | Print xtrm-tools build identity (package, version, commit) | | spec | PRD-level intent artifacts that compile to bd issues via the planner | | release | Release flow and publish helpers | | help | Show command help |

Flags: --yes / -y (non-interactive), --dry-run (preview), --prune (force-replace hooks)

Useful update commands:

xt update --root ~/dev              # dry-run fleet refresh
xt update --apply --root ~/dev      # write managed asset updates
xt update --repo .                  # dry-run current repo
xt update --apply --repo .          # write current repo updates
xt init -y                          # bootstrap incomplete repo / rebuild active skills

For detailed docs command usage, see docs/docs-commands.md or run xtrm docs --help / xtrm docs cross-check --help. For release flow details, see docs/release.md; the release skill drives the contract directly and does not rely on the deprecated xt release prepare/publish flow.

See docs/cli-architecture.md for internals.

MCP Servers

| Server | Purpose | |--------|---------| | gitnexus | Knowledge graph | | github-grep | Code search | | deepwiki | Repository documentation |

Official Claude plugins installed by xtrm init: context7.

See docs/mcp-servers.md for configuration details.

Specialist Bash Tools

| Tool | Purpose | Install source | |------|---------|----------------| | ghgrep | GitHub code search CLI wrapper over mcp.grep.app | Ships as bin in xtrm-tools | | ctx7 | Context7 docs + skills CLI | Installed by machine bootstrap (xt init) | | deepwiki | Repo documentation Q&A CLI | Installed by machine bootstrap (xt init) |

See docs/bash-tools.md for usage examples and when to use CLIs vs MCP equivalents.

Issue Tracking (Beads)

bd ready                           # Find unblocked work
bd update <id> --claim             # Claim an issue
bd close <id> --reason "Done"      # Close when done

See XTRM-GUIDE.md for the full bd command reference.

Version History

| Version | Date | Highlights | |---------|------|------------| | 0.11.6 | 2026-08-20 | PATH-based pi lookup fix (see CHANGELOG.md) | | 0.11.5 | 2026-08-20 | Launch hardening, Pi rendering polish, xt worktree reap, Codex runtime (experimental), Python kernel doctrine | | 0.11.0 | 2026-07-16 | Launcher, role-model isolation, verified audits, release metadata, and concise changelogs | | 0.7.21 | 2026-05-16 | Pi extension polish and current package line; update flow verified for xtrm-managed skills and specialists runtime | | 0.7.20 | 2026-05-15 | Worktree bootstrap guidance and Pi external tool overlay/chrome release | | 0.7.19 | 2026-05-14 | README, CLI, and docs synced to shipped npm package; release-contract and specialists workflow fully documented | | 0.7.18 | 2026-05-13 | Specialists became first-class; vendored specialist skills, release-contract handshake, npm publish --provenance, Pi package health reporting, security pipeline | | 0.7.17 | 2026-05-12 | Skills ownership and vendoring contract tightened; user fallback under ~/.xtrm/skills/default documented | | 0.7.16 | 2026-05-11 | CLI and docs drift cleanup; workflow orchestration polish | | 0.7.15 | 2026-05-10 | Session and hooks maintenance; publish prep hardening | | 0.7.14 | 2026-05-09 | Worktree and statusline refinements | | 0.7.13 | 2026-05-08 | Core workflow stability updates |

See CHANGELOG.md for full history.

MIT License