Wt Session Manager

wt - Worktree Session Manager

Overview

wt orchestrates isolated development sessions where each bead gets its own:

• Git worktree - Isolated code environment
• Tmux session - Persistent terminal
• Test environment - Docker containers with port isolation
• Claude agent - Working on the bead

Philosophy: One bead = one session = one worktree. Sessions persist until explicitly closed.

Architecture: Hub and Workers

HUB SESSION (You are here)
├── Groom beads: wt create, wt ready, wt beads
├── Spawn workers: wt new <bead-id>
├── Monitor: wt, wt watch
└── Switch: wt <session-name>
         │
         ▼
┌─────────────────────────────────────┐
│  WORKER: toast                       │
│  Bead: project-abc                   │
│  Worktree: ~/worktrees/toast/        │
│  Claude running, working...          │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│  WORKER: shadow                      │
│  Bead: project-xyz                   │
│  Worktree: ~/worktrees/shadow/       │
│  Claude running, working...          │
└─────────────────────────────────────┘

Hub session: Where you groom beads and orchestrate workers (this session) Worker sessions: Isolated Claude instances working on specific beads

When to Use wt

Use wt when:

• Parallel work - Multiple beads need simultaneous attention
• Isolation needed - Changes shouldn't interfere with each other
• Test environments - Each task needs its own Docker/ports
• Long-running tasks - Work that persists across hub compaction

Don't use wt when:

• Single simple task - Just work directly in current session
• Quick fix - Doesn't need isolation or persistence
• No worktree needed - Task doesn't involve code changes

Key insight: wt adds overhead (worktree, tmux, test env). Use it when isolation and parallelism justify the cost.

Session Start Protocol (Hub)

At session start, check for active workers and ready beads:

Session Start Checklist

Hub Session Start:
- [ ] Run wt to see active worker sessions
- [ ] Check session status: idle, working, error
- [ ] Run bd ready to see available work
- [ ] Report to user: "X active workers, Y beads ready"
- [ ] If idle workers: suggest checking on them

Pattern: Always check both wt (active sessions) AND bd ready (available work). Idle workers may need attention.

Report format:

• "You have X active workers: [summary]. Y beads are ready for new workers."
• "Worker 'toast' has been idle for 15 minutes - want me to check on it?"

Core Operations

Listing Sessions

wt              # List all active sessions
wt list         # Same as above
wt list --json  # JSON output for scripting/LLM consumption

Output shows: name, bead, status (working/idle/error), last activity, title

Spawning Workers

wt new <bead-id>                    # Spawn worker, auto-switch
wt new <bead-id> --no-switch        # Spawn but stay in hub
wt new <bead-id> --name custom      # Use specific name
wt new <bead-id> --repo ~/project   # Explicit project path

What happens on spawn:

1. Allocates session name from pool (toast, shadow, obsidian...)
2. Creates git worktree at ~/worktrees/<name>/
3. Creates branch named after bead
4. Sets up test environment (docker compose up)
5. Launches Claude in tmux session
6. Switches to the new session (unless --no-switch)

Important: One bead = one session. Cannot spawn multiple workers for same bead.

Switching Sessions

wt <name>           # Switch by session name
wt <bead-id>        # Switch by bead (looks up session)
wt toast            # Example: switch to toast

Attaches to the tmux session. Use Ctrl-b d to detach back to hub.

Monitoring

wt watch                # Interactive TUI dashboard
wt watch --auto-nudge   # Enable auto-nudge for stuck sessions

Watch TUI controls:

• ↑/↓ or j/k - Navigate between sessions
• Enter - Switch to selected session
• n - Toggle auto-nudge on/off
• r - Refresh manually
• q - Quit watch

Watch shows:

• All active sessions with color-coded status
• Status: working (green), idle (yellow), ready (bright green), blocked/error (red)
• Stuck detection: interrupted or idle sessions highlighted
• Status message or idle time
• Auto-refreshes every 5 seconds without flashing

Auto-nudge automatically recovers stuck sessions:

• Interrupted sessions: sends Enter to resume
• Idle sessions (5+ min): sends a continue prompt
• Rate-limited: 2 minute cooldown per session
• Logged to nudge.log in config directory

Tmux pane navigation (when watch is in side pane):

• Ctrl+b ←/→ - Switch between Claude and watch panes
• Ctrl+b o - Cycle through panes

Checking Session Status

wt status           # Current session info (from inside worker)
wt status --json    # JSON output for scripting/LLM consumption

Shows: session name, bead, project, worktree path, branch, port offset, status

Checking Ready Beads

wt ready                    # All registered projects (aggregated)
wt ready <project>          # Specific project only
wt ready --json             # JSON output for scripting/LLM consumption

Lists beads ready for work (no blockers, not in progress).

Multi-project aggregation: When called without a project filter, wt ready queries all registered projects and shows a combined view. This is the hub's unified view of available work.

Multi-Project Bead Grooming

The hub can create and query beads across any registered project without changing directories.

Creating Beads in Any Project

wt create <project> <title> [options]
wt create foo-frontend "Implement login API consumer"
wt create foo-backend "Add /users endpoint" -p 1 -t feature
wt create myapp "Fix auth bug" -d "Token refresh fails on timeout" -t bug

Options:

• -d, --description - Detailed description
• -p, --priority - Priority (0=critical, 1=high, 2=normal, 3=low)
• -t, --type - Issue type (task, bug, feature, epic, chore)

What happens:

1. Looks up project in registered projects
2. Creates bead in that project's .beads/ directory
3. Bead lives in the project - wt just provides hub access

Listing Beads for a Project

wt beads <project>                    # All beads
wt beads <project> --status open      # Filter by status
wt beads <project> --json             # JSON output for scripting/LLM consumption
wt beads foo-frontend --status open

Cross-Project Workflow Example

# Working on backend, realize frontend needs work too
wt beads foo-backend                  # See backend beads
wt create foo-frontend "Consume new /users endpoint" -d "Backend endpoint done in foo-backend-xyz"

# Now you can spawn workers for either
wt new foo-backend-abc --no-switch
wt new foo-frontend-def --no-switch

Key insight: The project's .beads/ remains source of truth. wt is just a multi-project interface that knows where each project lives.

Task Sessions (Lightweight, Non-Bead)

Task sessions are lightweight alternatives to bead sessions for transient work that doesn't need issue tracking.

When to Use Tasks vs Beads

Creating Task Sessions

wt task <description>                           # Simple task, no conditions
wt task "Investigate slow query" --condition none
wt task "Fix PR conflicts" --condition user-confirm
wt task "Run integration tests" --condition tests-pass --project myapp
wt task "Push hotfix" --condition pushed
wt task "Submit PR" --condition pr-merged

Completion conditions:

• none - No checks, completes immediately with wt done
• pushed - Verifies changes are pushed to remote
• pr-merged - Waits for PR to be merged
• tests-pass - Runs test suite before completing
• user-confirm - Requires user confirmation

Task workflow:

1. Hub spawns task: wt task "description" --condition X
2. Task runs in isolated worktree with branch task/<description>
3. Worker completes task and signals: wt signal ready "message"
4. Hub verifies condition and runs: wt done

Listing Tasks

Tasks appear in wt list with type "task":

Active Sessions

     Name               Type   Status      Title                           Project
────────────────────────────────────────────────────────────────────────────────────
     wt-toast           bead   working     Add login feature               myapp
     myapp-task-shadow  task   ready       Fix PR conflicts                myapp

Session Lifecycle

Completing Work

From worker session:

wt done                     # Commit, push, create PR
wt done --merge-mode direct # Force direct merge

From hub:

wt close <name>             # Complete + cleanup session

What wt done does:

1. Checks for uncommitted changes (blocks if present)
2. Pushes branch to remote
3. Creates PR (based on merge mode)
4. Updates bead status

Merge modes:

• direct - Merge directly to main, no PR
• pr-auto - Create PR, auto-merge when CI passes
• pr-review - Create PR, wait for human review (default)

Killing Sessions

wt kill <name>              # Stop session, keep bead open
wt kill <name> --keep-worktree  # Keep worktree too

Use when: need to restart session, or task is blocked

Abandoning Work

wt abandon                  # From inside worker

Discards all changes, removes worktree, keeps bead open.

Project Management

Listing Projects

wt projects                 # List registered projects
wt projects --json          # JSON output for scripting/LLM consumption

Shows: name, repo path, merge mode, active session count

Registering Projects

When a user asks to register a project, always ask about the branch and merge mode before completing registration:

1. Ask the user which branch this project registration is for:

   • Default is main
   • For feature branch workflows, register the same repo multiple times with different branches
   • Example: myapp (main) and myapp-feature-auth (feature/auth branch)

2. Ask the user which merge mode they prefer:

   • direct - Merge directly to target branch, no PR (fast, for solo work)
   • pr-auto - Create PR, auto-merge when CI passes (balanced)
   • pr-review - Create PR, wait for human review (default, safest)

3. Register the project:

   wt project add <name> <path> --branch <branch>
   

4. Configure merge mode if needed:

   wt project config <name>    # Opens in $EDITOR, set merge_mode
   

Example conversation:

User: "Register ~/code/myapp"
You: "I'll register that. A few questions:
      1. Which branch should workers use? (default: main)
      2. How should completed work be merged?
         - direct: Merge directly (no PR)
         - pr-auto: Create PR, auto-merge when CI passes
         - pr-review: Create PR, wait for human review"
User: "main branch, pr-auto"
You: [register project with branch=main, merge_mode=pr-auto]

Feature branch workflow:

User: "Register ~/code/myapp for the feature/auth branch"
You: "I'll register that as a separate project for the feature branch.
      What name for this registration? (suggestion: myapp-auth)"
User: "myapp-auth"
You: [register myapp-auth with branch=feature/auth]

Project config schema:

{
  "name": "myapp",
  "repo": "~/code/myapp",
  "repo_url": "git@github.com:user/myapp.git",
  "default_branch": "main",
  "beads_prefix": "myapp",
  "merge_mode": "pr-review"
}

Key fields:

• repo_url - Canonical git remote URL (auto-discovered)
• default_branch - Branch to create worktrees from and merge back to
• beads_prefix - Shared across all registrations of the same repo

Configuring Projects

wt project config <name>    # Opens in $EDITOR

Project config options:

• merge_mode - direct, pr-auto, pr-review
• default_branch - usually main
• beads_prefix - for bead matching
• test_env.setup - docker compose up command
• test_env.teardown - docker compose down command
• hooks.on_create - run on session create
• hooks.on_close - run on session close

Seance: Talking to Past Sessions

Query past Claude sessions to understand decisions and context.

List Past Sessions

wt seance                   # List recent sessions (workers + hub)

Output shows Session, Title, Project, and Time. Sessions are logged when they end via wt done, wt close, or wt kill. Hub sessions are logged on wt handoff.

Talk to Past Session

wt seance <name>            # Resume in new tmux pane (safe from hub)
wt seance <name> --spawn    # Spawn new tmux session
wt seance toast -p "What blocked you?"  # One-shot question

Resume Hub Sessions

wt seance hub --spawn       # Resume most recent hub in new tmux session

Use cases:

• "Why did you make this decision?"
• "Where were you stuck?"
• "What did you try that didn't work?"

Autonomous Epic Processing

Process an epic's beads sequentially and unattended with wt auto.

Basic Usage

wt auto --epic <epic-id>            # Process all beads in an epic
wt auto --epic <epic-id> --dry-run  # Preview what would run
wt auto --check                     # Check status of running auto

How It Works

1. Acquires per-project lock (~/.config/wt/auto-<project>.lock) — one auto run per project, parallel across projects
2. Audits the epic: validates beads have descriptions, no external blockers
3. Creates a single worktree and tmux session for the entire epic
4. For each bead (sequentially):
   • Sends bead prompt (with epic context and prior bead summaries) to the session
   • Waits for completion or timeout
   • Captures commit info, marks bead done
   • Kills the Claude process (not the session) for fresh context on next bead
5. All commits accumulate in the same worktree branch
6. Merges once at the end according to merge mode

Flags

Epic Setup

Link child beads to an epic before running:

bd create --title="Doc batch" --type=epic
bd create --title="Update API docs" --type=task
bd dep add wt-child wt-epic-id    # child depends on epic
wt auto --epic wt-epic-id

Stopping a Running Auto

wt auto --stop              # Graceful stop after current bead

The current bead continues to completion, then auto exits. Use wt auto --resume to continue later.

Failure Handling

wt auto --epic wt-xyz --pause-on-failure  # Stop on first failure
wt auto --resume                           # Retry after fixing
wt auto --abort                            # Give up and clean up

When to Use

• Overnight batch: Groom beads during day, run auto overnight
• Multi-step features: Break an epic into ordered beads, process sequentially
• Documentation sprints: Batch related doc tasks into an epic

Example: Overnight Workflow

# During day: groom beads and link to epic
bd ready                    # Review what's ready
bd show wt-abc              # Check each has good description
bd dep add wt-abc wt-epic   # Link children

# Before leaving
wt auto --epic wt-epic --dry-run   # Verify setup
wt auto --epic wt-epic             # Start

# Next morning
wt auto --check             # See results

Event Monitoring

Track what's happening across worker sessions with wt events.

Basic Usage

wt events                   # Show recent 20 events
wt events --tail            # Follow mode (like tail -f)
wt events --since 5m        # Events from last 5 minutes
wt events --since 1h        # Events from last hour

Events Logged

• session_start - Worker session created
• session_end - Worker completed work (includes PR URL if created)
• session_kill - Worker was killed
• pr_created - Pull request created
• pr_merged - Pull request merged

Hook Integration

Use --new --clear for Claude Code hook integration:

wt events --new --clear     # Show new events, mark as read

Claude Code settings.json:

{
  "hooks": {
    "prompt-submit": ["wt events --new --clear"]
  }
}

This automatically reports events at the start of each conversation turn:

• "wt session 'toast' completed bead wt-xyz (PR: https://...)"
• "wt session 'shadow' was killed (bead: wt-abc)"

When to Use

• Monitor workers: See what happened while you were away
• Hub notifications: Auto-report via hooks without manually checking
• Debugging: Track session lifecycle events

Diagnostics

Check your wt setup with wt doctor.

Basic Usage

wt doctor                   # Run all diagnostic checks

Checks Performed

Example Output

┌─ wt doctor ───────────────────────────────────────────────────────────┐
│                                                                       │
│  [✓] tmux: tmux 3.5a, server running (3 sessions)                     │
│  [✓] git: version 2.50.1                                              │
│  [✓] beads (bd): bd version 0.47.1                                    │
│  [✓] worktree root: /Users/me/worktrees exists and is writable        │
│  [✓] config: using defaults (no config.json)                          │
│  [✓] sessions: 2 active session(s), no orphans                        │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘

All checks passed!

Status Indicators

• [✓] - Check passed
• [!] - Warning (non-critical issue)
• [✗] - Error (must be fixed)

When to Use

• Initial setup: Verify wt is configured correctly
• After issues: Diagnose problems with sessions or worktrees
• Cleanup: Find orphaned sessions/worktrees to clean up

Common Patterns

Pattern 1: Morning Workflow

# Check state
wt                          # See active workers
bd ready                    # See available work

# Spawn workers for ready beads
wt new project-abc --no-switch
wt new project-xyz --no-switch

# Monitor throughout the day
wt watch

Pattern 2: Check on Idle Worker

# From wt list or watch, see "shadow" is idle
wt shadow                   # Switch to it
# Check what's happening, nudge Claude if needed
# Ctrl-b d to return to hub

Pattern 3: Complete and Cleanup

# From hub, close completed session
wt close toast              # Completes work + cleanup

# Or from inside worker
wt done                     # Submit work
wt close                    # Then cleanup

Pattern 4: Parallel Development Sprint

# Spawn multiple workers
wt new app-feature-1 --no-switch
wt new app-feature-2 --no-switch
wt new app-bugfix-3 --no-switch

# Monitor all
wt watch --notify

# Switch to check progress
wt app-feature-1
# Review, give guidance
# Ctrl-b d

wt app-feature-2
# Review, give guidance
# Ctrl-b d

Pattern 5: Resume After Session Start

If hub session restarts (compaction, new session), workers persist:

# Workers are still running in tmux
wt                          # See them all
wt toast                    # Resume interaction

Key benefit: Worker sessions survive hub compaction.

Integration with bd

bd for Strategic Work, wt for Execution

# In hub: groom beads
bd ready                    # What's available?
bd show project-abc         # Review details

# Spawn worker
wt new project-abc          # Execute in isolation

# Worker updates bead automatically
# - Sets status to in_progress on spawn
# - Creates PR on wt done
# - Closes bead on wt close

BEADS_DIR Inheritance

Workers inherit BEADS_DIR from the project, so bd commands inside workers operate on the correct project's beads.

Troubleshooting

First step for any issue:

• Run wt doctor to check for common problems

Session won't spawn:

• Check if bead exists: bd show <bead-id>
• Check if already has a session: wt (one bead = one session)
• Check project registered: wt projects

Can't find session by bead:

• Use wt to list all sessions
• Session-bead mapping in ~/.config/wt/sessions.json

Worker seems stuck:

• wt watch --auto-nudge to auto-detect and recover stuck sessions
• wt watch then press n to toggle auto-nudge interactively
• wt <name> to switch and investigate manually
• wt kill <name> to restart if needed

Port conflicts:

• Each session gets unique PORT_OFFSET (1, 2, 3...)
• Check wt status for assigned offset
• Ensure docker-compose.yml uses PORT_OFFSET

Session cleanup issues:

• Run wt doctor to find orphaned sessions/worktrees
• wt kill <name> to force-stop sessions
• Check for orphaned worktrees: git worktree list
• Check for orphaned tmux: tmux list-sessions

Machine-Readable Output (--json)

Most listing commands support --json for machine-readable output, useful for:

• LLM/AI agent consumption - Skills, automation, intelligent decision making
• Scripting and pipelines - Parse output with jq, integrate into scripts
• Integration with other tools - Build custom dashboards, notifications

Commands with JSON support

wt list --json              # Sessions array
wt projects --json          # Projects array with session counts
wt ready --json             # Ready beads array
wt beads <project> --json   # Project beads array
wt status --json            # Current session object

Example: Parse with jq

# Get names of all active sessions
wt list --json | jq -r '.[].name'

# Get ready beads with priority 0 (critical)
wt ready --json | jq '.[] | select(.priority == 0)'

# Count sessions per project
wt list --json | jq 'group_by(.project) | map({project: .[0].project, count: length})'

Quick Reference

Hub Session: Dedicated Orchestration

The hub is a dedicated tmux session for orchestrating worker sessions. Unlike worker sessions, the hub has no worktree and is not tied to any specific bead.

Creating/Attaching to Hub

wt hub                      # Create hub or attach if exists
wt hub --status             # Show hub status without attaching
wt hub --detach             # Detach from hub, return to previous session
wt hub --kill               # Kill hub session (prompts for confirmation)
wt hub --kill --force       # Kill hub without confirmation
wt hub --no-watch           # Create hub without watch pane

Hub Characteristics

• Session name: Always "hub"
• Working directory: Home directory (~)
• Watch pane: Right pane with wt watch (25% width, skip with --no-watch)
• No worktree: Hub doesn't have code isolation
• No BEADS_DIR: Uses bd's project detection
• Persistent: Survives across Claude instances via handoff

When to Use Hub

• Central orchestration: Manage multiple worker sessions from one place
• Cross-project work: Work on beads from different projects
• Monitoring: Watch workers, check events, review progress

Hub Workflow

# Start or attach to hub
wt hub

# From hub, spawn workers (automatically stays in hub, workers start working)
wt new wt-abc           # Creates wt-woody, sends initial prompt, stays in hub
wt new supabyoi-xyz     # Creates supabyoi-buzz, starts working

# Monitor workers
wt watch

# Switch to a worker to check on it
wt wt-woody             # Ctrl-b d to detach back to hub

# When done, detach from hub
wt hub --detach         # Returns to previous session

Key behaviors from hub:

• wt new stays in hub by default (use --switch to attach)
• Workers receive detailed workflow instructions and start working
• Session names are project-prefixed: wt-woody, supabyoi-buzz
• Workers do NOT run wt done - hub handles cleanup after review

Worker instructions include:

1. Implement the task
2. Commit changes with descriptive message
3. Run tests (if configured)
4. Create PR (or push for direct mode)
5. Signal completion: wt signal ready "PR: <url>"

Signaling status:

wt signal ready "PR: https://github.com/org/repo/pull/123"
wt signal blocked "Waiting for API credentials"
wt signal error "Tests failing on CI"

Hub sees status changes in wt watch and receives notifications.

Hub vs Worker Sessions

Hub Sessions in Seance

Hub sessions appear in wt seance after a handoff, allowing you to resume previous hub conversations:

wt seance                   # Lists both worker (⚙️) and hub (🏠) sessions
wt seance hub --spawn       # Resume the last hub session

Example output:

Past Sessions (seance)

     Session             Title                                 Project         Time
────────────────────────────────────────────────────────────────────────────────────
 ⚙️  myproject-toast     Add OAuth authentication flow         myproject       2026-01-20 14:30
 🏠  hub                                                                       2026-01-20 12:00

⚙️ = Worker session   🏠 = Hub session

Hub Persistence: Handoff and Prime

Hub sessions can survive compaction and restarts through the handoff system.

The Problem

When the hub session compacts or restarts:

• Worker sessions survive (they're in tmux)
• But hub context is lost

The Solution: wt handoff

IMPORTANT: When user requests handoff (or you detect context limit), you MUST:

1. Summarize the conversation first - Create a concise summary including:

   • What was accomplished this session
   • Key decisions made and why
   • Current state of work (what's done, what's pending)
   • Any blockers or issues discovered
   • Recommended next steps

2. Call wt handoff with the summary:

   wt handoff -m "SUMMARY:
   - Accomplished: [list what was done]
   - Decisions: [key decisions and rationale]
   - Current state: [where things stand]
   - Next steps: [what should happen next]
   - Notes: [anything the next session should know]"
   

3. The new session will:

   • Receive a prompt to read ~/.config/wt/handoff.md
   • Have full context of what happened
   • Continue where you left off

Trigger conditions for handoff:

• User explicitly asks for handoff
• You notice context is getting long/compacted
• Before a major context switch
• End of a work session

Example handoff:

wt handoff -m "SUMMARY:
- Accomplished: Fixed handoff respawn bug (wt-rcj), context now passes to new session
- Decisions: Used session name detection instead of WT_HUB env var for reliability
- Current state: Code committed and pushed, tests passing
- Next steps: Test handoff end-to-end, then implement /handoff skill integration
- Notes: Watch pane was restored manually after debugging"

What happens internally:

1. Collects context (active sessions, ready beads, in-progress work)
2. Writes your summary + auto-collected context to ~/.config/wt/handoff.md
3. Stores in "Hub Handoff" bead (persists in beads)
4. Logs hub session for seance (can resume via wt seance hub)
5. Writes handoff marker file
6. Clears tmux history
7. Respawns fresh Claude via tmux respawn-pane

Startup: wt prime

New Claude session runs:

wt prime                    # Inject context from previous session
wt prime --quiet            # Suppress non-essential output
wt prime --no-bd-prime      # Skip running bd prime

What happens:

1. Checks for handoff marker (detects post-handoff state)
2. Shows warning: "DO NOT run /handoff - that was your predecessor"
3. Injects handoff content from bead
4. Runs bd prime for beads context

Claude Code Hook Integration

Add to .claude/settings.json:

{
  "hooks": {
    "SessionStart": ["wt prime"]
  }
}

This auto-primes new sessions with handoff context.

When to Use Handoff

• Context bloat: Session growing slow, need fresh start
• Before leaving: Save state before stepping away
• After major decision: Checkpoint before moving on

Key Points

• Worker sessions survive handoff (they're in tmux)
• Handoff bead persists context in beads database
• Marker file prevents "handoff loop" bug
• wt prime clears marker after reading

Hub Beads Store

The hub has its own beads store at ~/.config/wt/.beads/ with hub- prefix:

~/.config/wt/
├── .beads/           # Hub-level beads (hub-* prefix)
│   ├── beads.db      # SQLite database
│   └── issues.jsonl  # JSONL export
├── config.json       # wt configuration
└── sessions.json     # Active sessions state

Initialization: Hub beads are auto-initialized when:

• wt hub creates a new hub session
• wt handoff or wt prime first runs

Manual initialization (if needed):

cd ~/.config/wt && bd init --prefix hub

The Hub Handoff bead:

• Title: "Hub Handoff"
• Status: pinned (never closed)
• Description: Contains the handoff context
• Cleared after wt prime displays it

View hub beads:

cd ~/.config/wt && bd list
cd ~/.config/wt && bd show hub-xxx  # specific bead

Reference Files

Converted and distributed by TomeVault — claim your Tome and manage your conversions.