tmux

Arguments

$0 (optional verb) routes to a section; pass the target pane, window, or session as the rest. With no verb, infer the operation from the request.

• capture: print pane content. See Capturing Pane Content.
• send: send keys to a running pane. See Starting Claude Sessions.
• split: open a pane. See Opening Panes.
• notify: check which windows need attention (bell/activity). See Session.
• list: inventory panes, windows, and sessions. See Drilling Into Other Targets.

Pane

!bash ${CLAUDE_SKILL_DIR}/scripts/pane.sh

Use $TMUX_PANE to identify the current pane and target adjacent ones.

Window

!bash ${CLAUDE_SKILL_DIR}/scripts/window.sh

Each pane line ends with its geometry as @<left>,<top> <width>x<height>, in cell coordinates from the window's top-left. Resolve spatial references from these: LHS = lowest left, RHS = highest left, top = lowest top, bottom = highest top. When describing layouts, draw ASCII box diagrams from the positions and sizes.

Worktrees and Parallel Panes

Panes in a git repo show their branch and whether the checkout is a linked (worktree) or the primary (main) one. When the user refers to work by branch or worktree ("the pane on the X branch", "the worktree for Y", "the other pane, which is ready"), match the reference to a pane's branch and dispatch to it with send-keys (or treat it as already running) rather than entering a worktree of your own. A pane already in a worktree is set up for parallel work; hand off to it instead of duplicating the checkout.

Session

!bash ${CLAUDE_SKILL_DIR}/scripts/session.sh

The TITLE column shows the active pane's title in each window. Claude sessions advertise their current task there, usually enough to identify a window without capturing its content. Windows marked here are the current window; bell or activity flags mean the window needs attention (a process finished, errored, or produced output).

Sessions

!bash ${CLAUDE_SKILL_DIR}/scripts/sessions.sh

Drilling Into Other Targets

Each script accepts an optional target argument to inspect any pane, window, or session — not just the current one:

bash ${CLAUDE_SKILL_DIR}/scripts/session.sh other-session
bash ${CLAUDE_SKILL_DIR}/scripts/window.sh other-session:2
bash ${CLAUDE_SKILL_DIR}/scripts/pane.sh %12

Compose them to drill down: pick a session from sessions.sh, list its windows with session.sh <name>, then inspect a specific window with window.sh <name>:<idx>.

Opening Panes

Use split-window with -t $TMUX_PANE so new panes open relative to Claude's pane. Always pass -d to avoid switching Claude's own pane to the new one.

Layout Mapping

User intent	Flags	Notes
right / beside	-h -d	Horizontal split
below / underneath	-v -d	Vertical split
right sidebar	-h -d -l 40%	Narrow right pane
left sidebar	-h -d -b -l 40%	Narrow left pane (-b = before)
bottom panel	-v -d -l 25%	Short pane below
top panel	-v -d -b -l 25%	Short pane above

Running a Command

Inline a command string only for a single bare command:

tmux split-window -h -d -t $TMUX_PANE 'tail -f logs/dev.log'

The command runs in the new pane's shell. When it exits, the pane closes. Use $SHELL or omit the command to open an interactive shell.

Anything past a bare command can make split-window silently fail: a ;, quotes, an exec fallback, or other shell metacharacters. The failure is quiet: no pane opens, no error prints, and -P -F '#{pane_id}' returns nothing. It reads as the pane never appearing, not as the pane opening then disappearing. Split bare and send-keys the command instead. The new pane's shell runs the keys verbatim, past tmux's own parsing of the inline string:

pane=$(tmux split-window -h -d -t $TMUX_PANE -P -F '#{pane_id}')
tmux send-keys -t "$pane" 'cd repo; exec zsh' Enter

Starting Claude Sessions

Pass the initial prompt as a CLI argument rather than using send-keys:

tmux split-window -h -d -t $TMUX_PANE 'claude "analyze the test failures"'

A prompt with a ;, nested quotes, or other metacharacters hits the same silent inline-parsing failure. Split bare and send-keys the whole claude '...' line instead (see Running a Command). Use send-keys only for follow-up messages to an already-running session.

Collaborative File Viewing

When collaborating on a file, open it in a sidebar pane so the user sees changes in real-time as you edit.

tmux split-window -h -d -l 40% -t $TMUX_PANE '<command> <file>'

The inline form is safe only when both the command and the path are bare. A filename with a space, or a $EDITOR carrying flags (code -w), hits the same silent no-op. Split bare and send-keys the viewer line instead (see Running a Command).

Available Tools

!bash ${CLAUDE_SKILL_DIR}/scripts/tools.sh

Markdown Files

Prefer a terminal markdown renderer with file watching. Tools in preference order:

Tool	Command	Notes
bun	bun --watch file.md	Rendered markdown with live reload
glow	glow -w 0 file.md	Rendered, no watch (reopen on change)
batwatch	batwatch --watcher poll file.md	Syntax-highlighted with file watching
bat	bat --paging always file.md	Syntax-highlighted source, no watch
less	less file.md	Plain text fallback

Other Files

Open with $EDITOR when set, otherwise fall back to read-only viewers:

Tool	Command	Notes
$EDITOR	$EDITOR file.ts	User's preferred editor, most auto-reload on external changes
batwatch	batwatch --watcher poll file.ts	Syntax-highlighted with file watching
bat	bat --paging always file.ts	Syntax-highlighted, read-only
less	less file.ts	Plain text fallback

Use the first available option. If the pane exits immediately, the tool is missing; try the next.

Capturing Pane Content

Use capture-pane -p to print to stdout instead of a paste buffer.

tmux capture-pane -t $TARGET -p
tmux capture-pane -t $TARGET -p -S -100

-S -100 includes 100 lines of scrollback above the visible area.

Gotchas

• Always use -P -F '#{pane_id}' to capture pane IDs at creation time
• Always use -d on split-window to avoid switching Claude's pane
• split-window with an inline command containing ;, quotes, or metacharacters can silently no-op (no pane, no error). Split bare, then send-keys the command
• Use $TMUX_PANE (set by tmux natively and injected by context hook) to target the current pane