| name | tmux-thread-picker |
| description | Legacy tmux-only thread picker. Use only when the user explicitly asks for tmux or the old tmux-thread-picker CLI. For normal thread, workspace, worktree, pane, or agent management, prefer the Herdr workspace manager skill. |
Tmux Thread Picker
Legacy tmux-only workflow. The user now prefers Herdr for normal thread/workspace/worktree/agent management. Use this skill only when the user explicitly asks for tmux or the old tmux-thread-picker CLI.
Use the user's thread picker as the source of truth for tmux work threads and LLM/Codex activity.
Commands
Inspect threads:
/Users/boss/.dotfiles/bin/tmux-thread-picker.sh --rows
Use the explicit tmux socket for navigation and pane control:
tmux -S /private/tmp/tmux-501/default switch-client -t 'session:window'
tmux -S /private/tmp/tmux-501/default select-pane -t '%pane'
tmux -S /private/tmp/tmux-501/default send-keys -t '%pane' 'text' Enter
Open the interactive picker only when the user wants direct interactive selection:
/Users/boss/.dotfiles/bin/tmux-thread-picker.sh
The interactive UI is implemented in Go with Bubble Tea. It is not fzf-based; live state refresh happens inside the picker and should not be controlled through fzf reload/listen behavior.
The user's tmux bindings open the interactive picker in a full-screen borderless tmux popup:
M-t display-popup -B -E -w 100% -h 100% ... TMUX_THREAD_ATTENTION_ONLY=1 ... tmux-thread-picker.sh
M-T display-popup -B -E -w 100% -h 100% ... TMUX_THREAD_ATTENTION_ONLY=0 ... tmux-thread-picker.sh
Create another 4-pane thread window for the same path, intentionally bypassing worktree deduplication:
/Users/boss/.dotfiles/bin/tmux-worktree-layout.sh duplicate '<source-session>' '<path>' '[name]'
Use this for requests like "create another session thread for the current path" or "make two more of these". Prefer the current tmux session as <source-session> and the current working directory as <path>. This command must leave the user on the current tmux window after creating the duplicate thread.
Row Format
--rows prints tab-separated rows:
kind visible_display target branch pin_key project search_text
Relevant kind values:
GROUP: project heading; never navigate to this.OPEN: existing tmux window or Codex pane; navigate with target.WT: git worktree not currently open; opening it may create/switch tmux layout through the picker workflow.
For OPEN, target is usually session:window. When a row represents a specific pane it can include a pane suffix; switch to the window first, then select the pane if present.
State Labels
Read these from the visible display column:
run or ▶: Codex/LLM work is actively running.wait or ●: Codex/LLM work finished and is waiting for user attention.codex: a Codex CLI pane is open but not marked running.open*: current tmux window.open: existing tmux window.work: available git worktree.!: busy process in that window.P: pinned thread.A: archived thread.
Prefer summarizing run, wait, codex, and ! rows first when the user asks what needs attention.
Safe Workflow
- Run
tmux-thread-picker.sh --rows.
- Parse only the row fields needed for the task.
- For status questions, report project, title, state, path/branch, and duration if visible.
- For navigation requests, use
tmux switch-client with the row target, and select-pane when the target identifies a pane.
- For sending text, select the pane only when needed, then use
send-keys.
Never kill tmux windows or panes unless the user explicitly asks to close/kill them. Do not use picker keybindings like ctrl-q on the user's behalf unless explicitly requested.
For duplicate same-path thread creation, do not use raw tmux new-window; it only creates one pane. Call tmux-worktree-layout.sh duplicate ... so the result gets the standard 4-pane layout and preserves the user's current window.
Useful Filters
Show all rows even when an attention-only environment is active:
TMUX_THREAD_ATTENTION_ONLY=0 /Users/boss/.dotfiles/bin/tmux-thread-picker.sh --rows
Show archived rows:
TMUX_THREAD_SHOW_ARCHIVED=1 /Users/boss/.dotfiles/bin/tmux-thread-picker.sh --rows
Use --list for a human-readable list without row metadata:
/Users/boss/.dotfiles/bin/tmux-thread-picker.sh --list
Interactive Picker Keys
When the user is driving the UI:
Enter: open selected thread.Ctrl-n: create a new thread worktree.Ctrl-r: refresh.Ctrl-o: open the worktree selector.Ctrl-p: pin or unpin.Ctrl-t: edit title.Ctrl-y: regenerate auto-title.Ctrl-x or Alt-a: archive or unarchive.Alt-f: show all.Alt-v: show archived.
