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 maintenance (documenting), and domain expertise (backend, devops, security, data science). Skills are injected into the agent context on demand and work identically in Claude Code and Pi.

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 and Serena code intelligence are 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 (upcoming)

Native integration with the specialists framework — spawning purpose-built sub-agents for parallel workloads, code review, and long-running background tasks directly from within a session.

---

Version 0.7.1 | 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/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/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 github:Jaggerxtrm/xtrm-tools@latest

# Set up xtrm in your project
xtrm init

# Verify
claude plugin list
# → xtrm-tools@xtrm-tools  Version: 0.7.1  Status: enabled

One-line run:

npx -y github:Jaggerxtrm/xtrm-tools init

Typical workflow after install:

# Start a sandboxed session in a worktree
xt claude my-feature

# 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

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.

---

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 Skills	Pi	Territory-based Docker service skill activation

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). Optional packs are installed by default during xt install; activate any pack with xt skills enable <pack>. Current optional pack catalog: research-methods, code-quality, security-ops, data-engineering, and architecture-design.

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-serena-lsp	Code exploration and surgical edits via Serena LSP
using-tdd	Test-driven development with 80%+ coverage enforcement
using-service-skills	Service catalog discovery and expert persona activation
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 (specialists run/feed/result)
orchestrating-agents	Multi-model orchestration (Gemini, Qwen handshake)
documenting	SSOT doc maintenance with drift detection
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
creating-service-skills	Generate operational service skill packages
scoping-service-skills	Task intake and service routing
updating-service-skills	Detect drift and sync expert persona docs
prompt-improving	Apply Claude XML best practices to prompts

General-Purpose Expert Skills

Domain expert skills that can be used in any project, independent of the xtrm workflow.

Skill	Purpose
senior-backend	NodeJS, Express, Go, Python, Postgres, REST/GraphQL
senior-devops	CI/CD, infrastructure as code, cloud platforms
senior-security	AppSec, pen testing, threat modeling, crypto
senior-data-scientist	Statistics, ML, A/B testing, causal inference
docker-expert	Multi-stage builds, Compose, container security
python-testing	pytest, TDD, fixtures, mocking, coverage
hook-development	PreToolUse/PostToolUse hook authoring
clean-code	Pragmatic coding standards, no over-engineering
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
obsidian-cli	Interact with Obsidian vaults via CLI
deepwiki	Query repository/library docs via DeepWiki

---

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	claude	Injects session manual at SessionStart
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
install	Install plugin + beads + gitnexus (interactive target selection)
init	Initialize project (bd, gitnexus, service-registry)
status	Read-only diff view
clean	Remove orphaned hooks
claude [name]	Launch Claude Code in a sandboxed xt/<name> worktree
pi [name]	Launch Pi in a sandboxed xt/<name> worktree
attach [slug]	Re-attach to an existing worktree and resume the Claude or Pi session
end	Close worktree session: rebase, push, PR, cleanup
memory update	Run memory-processor to synthesize bd memories + repo state into .xtrm/memory.md
update	Refresh xtrm-managed files for one repo or many (--apply, --repo <path>, --root <dir>, --json)
release prepare	Prepare a release from xt reports and changelog drafting (--major, --minor, --patch, --from, --to)
release publish	Publish a prepared release with annotated tag/push and optional GitHub release
merge	Drain queued xt/* PRs via xt-merge: FIFO CI gate → rebase merge → rebase cascade
worktree list	List active xt/* worktrees with runtime, last activity, and resume hint
worktree clean	Remove merged worktrees
docs	Documentation inspection and drift-check suite (xtrm docs --help)
docs show	Display frontmatter for README, CHANGELOG, docs/*.md
docs list	Inventory markdown docs with filters, summaries, and optional cache bypass
docs cross-check	Compare docs against recent PR activity and closed bd issues
debug	Watch hook and bd lifecycle events in real time

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

For detailed docs command usage, see docs/docs-commands.md or run xtrm docs --help / xtrm docs cross-check --help. For release flow details, run xt release --help; xt release prepare currently depends on the specialists changelog script compatibility tracked by unitAI-dnmcg.

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: serena, context7, github, ralph-loop.

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 install / xt init)
deepwiki	Repo documentation Q&A CLI	Installed by machine-bootstrap (xt install / 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.7.1	2026-04-02	Optional packs pre-populated on install; Pi core symlink path fix; new default skills (deepwiki, specialists-creator, using-specialists)
0.5.30	2026-03-22	Fix statusline on fresh installs; xt end --dry-run
0.5.29	2026-03-22	Statusline truecolor gradient; --no-verify autocommit; xt-merge skill
0.5.24	2026-03-21	Hash-based docs drift detection; CLI docs cleanup
0.5.20	2026-03-21	xtrm docs show; worktree-boundary hook; statusline injection

See CHANGELOG.md for full history.

---

MIT License