Hub Commands

Hub commands are what Claude runs when you ask it to manage workers from your hub session.

Conversational equivalent: Instead of memorizing these commands, just tell Claude what you want:

You say...	Claude runs...
"What work is ready?"	wt ready
"Spawn a worker for the auth task"	wt new myproject-abc
"How are the workers doing?"	wt or wt watch
"Switch to toast"	wt toast
"Close toast"	wt close toast

This page documents the commands for reference.

Session Management

wt / wt list

List all active worker sessions.

wt
wt list

Output:

┌─ Active Sessions ────────────────────────────────────────┐
│ 🟢 toast    myproject-abc   Working   Add auth flow     │
│ 🟡 shadow   myproject-def   Idle      Fix login bug     │
│ 🔴 obsidian myproject-ghi   Error     Update API        │
└──────────────────────────────────────────────────────────┘

wt new <bead-id>

Create a new worker session for a bead.

wt new myproject-abc123

What it does:

1. Creates git worktree in ~/worktrees/<name>/
2. Creates branch from bead ID
3. Starts tmux session
4. Launches Claude Code
5. Marks bead as in_progress

Options:

Flag	Description
--name	Override session name
--no-attach	Create without attaching

wt <name>

Switch to a session by name or bead ID.

wt toast
wt myproject-abc123

wt pick

Interactive session picker.

wt pick

Uses fzf if available, otherwise shows numbered prompt.

wt watch

Live TUI dashboard showing all session statuses.

wt watch
wt watch --auto-nudge

Updates in real-time as sessions change state.

Options:

Flag	Description
--auto-nudge	Auto-detect and nudge stuck/interrupted sessions

Auto-nudge detects two stuck states: - Interrupted - Claude was interrupted; sends Enter to resume - Idle - Session idle for 5+ minutes; sends a continue prompt

Nudges are rate-limited (2 minute cooldown per session) and logged to nudge.log. Toggle auto-nudge on/off with the n key in the TUI.

wt kill <name>

Kill a session without closing the bead.

wt kill toast

What it does:

• Terminates tmux session
• Removes worktree
• Does NOT update bead status
• Use for abandoned/stuck sessions

wt close <name>

Complete work and clean up session.

wt close toast

What it does:

1. Commits any uncommitted changes
2. Pushes branch
3. Creates PR (if configured)
4. Updates bead status
5. Removes worktree and tmux session

---

Hub Session

wt hub

Create or attach to a dedicated hub session.

wt hub

The hub is a special tmux session for orchestration.

Options:

Flag	Description
--watch	Attach and add watch pane
--detach	Detach from hub
--kill	Terminate hub session

---

Bead Management

wt ready [project]

Show beads ready to work on (no blockers).

wt ready
wt ready myproject

wt create <project> <title>

Create a new bead.

wt create myproject "Add user authentication"

wt beads <project>

List all beads for a project.

wt beads myproject

---

Project Management

wt projects

List registered projects.

wt projects

wt project add <name> <path>

Register a new project.

wt project add myproject ~/code/myproject

wt project config <name>

Edit project configuration.

wt project config myproject

Opens config in $EDITOR.

wt project remove <name>

Unregister a project.

wt project remove myproject

---

Auto Mode

wt auto

Autonomous batch processing of ready beads.

wt auto
wt auto --project=myproject
wt auto --max=5

Options:

Flag	Description
--project	Filter to specific project
--max	Maximum sessions to spawn
--merge-mode	Override merge mode
--timeout	Timeout per session
--dry-run	Preview without executing

wt auto --check

Check auto mode status.

wt auto --check

wt auto --stop

Stop auto processing.

wt auto --stop

---

Handoff

wt handoff

Hand off hub session to a fresh Claude instance.

wt handoff
wt handoff -m "Continue with priority fixes"
wt handoff -c  # Auto-collect state

Options:

Flag	Description
-m	Include message in handoff
-c	Auto-collect state (sessions, ready beads)
--dry-run	Preview what would be collected

---

Past Sessions

wt seance

List past sessions.

wt seance

wt seance <name>

Resume a past Claude session.

wt seance toast

wt seance <name> -p "prompt"

One-shot query to a past session.

wt seance toast -p "Where did you put the nginx config?"