The doctor command cross-checks worktrees, tmux sessions, and status database entries to find orphaned resources. Run it to diagnose inconsistencies; add --fix to auto-clean them.

Usage

owt doctor [OPTIONS]

Options

Option	Description
--fix	Auto-cleanup orphaned resources (without this flag, read-only diagnosis)

Examples

Diagnose Only

owt doctor

Output:

Checking worktrees, tmux sessions, and status entries...

Orphaned tmux sessions (no matching worktree):
  - owt-old-feature

Orphaned status entries (no matching worktree):
  - stale-experiment

Worktrees without tmux sessions:
  - feat/headless-task (may be headless -- left untouched)

Run with --fix to clean up orphaned resources.

Auto-Fix Orphans

owt doctor --fix

Output:

Fixing orphaned resources...

Killed tmux session: owt-old-feature
Removed status entry: stale-experiment
Skipped worktree without tmux: feat/headless-task (may be headless)

Done. 2 orphans cleaned up.

What Gets Checked

The doctor command performs a three-way cross-reference:

Resource	Source	Orphan Condition
Worktrees	git worktree list	No tmux session (left untouched -- may be headless)
tmux sessions	tmux list-sessions	No matching worktree (killed with --fix)
Status entries	SQLite status database	No matching worktree (removed with --fix)

Why Worktrees Without tmux Are Left Alone

A worktree without a tmux session may be a headless worktree created with owt new --headless. Deleting it could destroy in-progress work. The doctor reports these but never touches them.

Use Cases

• After a crash or unexpected terminal close
• If the Control Plane shows stale rows
• Before a major cleanup to catch inconsistencies
• As part of periodic maintenance

See Also

• owt cleanup -- Remove stale worktrees based on age
• owt delete -- Delete a specific worktree
• owt db health -- Check database health