wt - Worktree Session Manager¶

Minimal agentic coding orchestrator where you talk to Claude to manage multiple parallel AI workers.

How It Works¶

You have a conversation with Claude. Claude runs the commands.

You: "What work is ready?"
Claude: [runs wt ready] Three beads available: auth feature, login bug, error messages.

You: "Spawn a worker for the auth feature."
Claude: [runs wt new myproject-abc] Session 'toast' is working on it.

You: "How's it going?"
Claude: [runs wt] Toast is actively working, 3 commits so far.

You: "Toast says it's done. Close it."
Claude: [runs wt close toast] PR created, session cleaned up.

You describe what you want. Claude handles the wt commands, git operations, and worker management.

The Hub/Worker Model¶

The architecture separates orchestration from execution:

Hub: A conversation with Claude where you plan work, spawn workers, and monitor progress
Workers: Isolated sessions where AI agents execute tasks autonomously

┌─────────────────────────────────────────────────────────────┐
│  HUB (You + Claude)                                         │
│                                                             │
│  You: "What's ready?"                                       │
│  You: "Spawn workers for the bug fixes"                     │
│  You: "How's toast doing?"                                  │
│  You: "Close the finished ones"                             │
│                                                             │
└─────────────────────┬───────────────────────────────────────┘
                      │ spawns/monitors
                      ▼
┌─────────────────────────────────────────────────────────────┐
│  WORKERS (Claude instances)                                 │
│                                                             │
│  toast: Working on auth feature in ~/worktrees/toast        │
│  shadow: Working on login bug in ~/worktrees/shadow         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

One bead = one session = one worktree. Each task gets isolated: its own git worktree, tmux session, and AI agent.

Built On¶

Beads for task tracking
Git worktrees for code isolation
Tmux for session persistence
Claude (or other agents) for execution

Design Principles¶

Conversational over CLI — You talk to Claude, not memorize commands.
Isolation over sharing — Each worker has its own worktree, branch, and test environment.
Explicit over automatic — Sessions don't auto-close. You control the lifecycle.
Visibility over opacity — Check on any worker anytime through the hub.

Getting Started¶

Installation - Get wt installed on your system
Quick Start - Your first hub session in 5 minutes
Shell Integration - Completions and keybindings

Guides¶

Learn how to work through your hub:

Hub Workflow - The conversation-driven approach to orchestration
Sample Workflows - Real-world scenarios with conversation examples
Auto Mode - Hands-off batch processing
Seance - Querying past sessions

Core Concepts¶

Overview - How wt works
Sessions - How wt manages agent sessions
Worktrees - Git worktree isolation
Beads Integration - Task tracking with beads
Test Environments - Per-session test isolation
Merge Modes - PR workflows

Reference¶

Technical reference for power users who want to understand what Claude runs behind the scenes:

Commands - CLI reference (what Claude runs for you)
Configuration - All configuration options
Environment - Environment variables
Technical Specification - Architecture and internals
Troubleshooting - Common issues and solutions

beads - Git-native issue tracking
gastown - Multi-agent workspace manager
vibekanban - AI agent orchestration with visual UI