tmux-features-inventory-2026-04-12.md

Tmux Features in ArtHack — Complete Inventory

Tmux is deeply integrated into arthack as the primary session management layer for agent workflows. The system spans a dedicated CLI (tmuxctl), tmux config files, Claude Code hooks/skills/commands, and cross-tool integrations that tag every agent session with its tmux coordinates.

---

1. tmuxctl — The Core CLI

apps/tmuxctl/ — 14 subcommands, ~627 lines in cli.py

Subcommand	Purpose
create-session NAME	Create detached session with optional --dir, --cmd, --window-name
load-session LAYOUT	Load session from YAML layout in ~/.config/tmuxctl/layouts/
run-command TARGET CMD	One-shot: send keys, wait for prompt, capture output
run-claude	Launch Claude Code in tmux with plan mode, --skip-commit defaults
run-commit ARGS	Interactive commit wrapper with output logging
wait-for TARGET PATTERN	Poll pane for regex match, optional --then-send
send-keys TARGET KEYS	Send keystrokes (--enter/--no-enter, --literal, --delay)
capture-pane TARGET	Read pane content (--lines N, --full)
create-split CMD	Split along longest axis, returns YAML metadata
check-pane TARGET	Query pane status (alive, pid, command)
show-tree	Session/window/pane tree with real foreground processes
tail-panes	Tail of all panes in a session
triangulate-self	Print current pane's tmux context as YAML
show-diff	Show git diff in critique or delta viewer

Pane targeting format: SESSION[:WINDOW[.PANE]], 1-based indexing. Sessions prefixed _ are hidden by default.

Each subcommand has a dedicated run_*.py module (14 total).

---

2. Tmux Configuration

system/tmux/.config/tmux/conf.d/ — three config fragments, stowed to ~/.config/tmux/ by scripts/install.sh:

File	What it does
arthack-commit.conf	prefix G → split pane for tmuxctl run-commit; prefix H → split for tmuxctl show-diff
arthack-session-id.conf	Hooks (window-layout-changed, after-rename-session, window-unlinked) that call hookctl sync-tmux to keep job-tracker DB in sync with tmux layout changes
devctl.conf	Alt+p FZF project picker, Alt+f file chooser, Alt+t transcript chooser — all as tmux popups

---

3. Claude Code Hooks

hooks-tracker (apps/hookctl/hooks/hooks-tracker.py)

Every Claude Code session gets tagged with tmux coordinates on start:

• Runs tmux display-message -p "#{session_name}\x1e#{window_index}\x1e#{pane_index}"
• Writes tmux_session, tmux_window, tmux_pane to the hooks-tracker SQLite DB

job-callbacks dispatcher (apps/hookctl/hooks/job-callbacks/dispatcher.py)

Template variables for notification messages: {job.tmux_session}, {job.tmux_window}, {job.tmux_pane}, {job.tmux_target} (formatted as main:1.0)

hookctl config (system/hookctl/.config/hookctl/config.yaml)

Command advice for tmuxctl usage patterns:

• Prefer run-command over send-keys + capture-pane
• Use create-split for panes, never create-session
• Verify with check-pane or capture-pane after splitting
• Target by session name, not session:1
• Use send-keys --no-enter for interactive prompts

---

4. Claude Skill

claude/work/skills/tmux/SKILL.md — work:tmux

Loaded when working with tmux, interactive terminals, TUI programs, or full shell environments. Includes a reference doc (references/tmux-commands.md) covering session management, window management, targeting syntax, pane management, and common patterns (split+verify, send+wait+capture, polling, interactive prompts).

---

5. Cross-Tool Integrations

Tool	How it uses tmux
jobctl	Auto-scopes to current tmux/prise session. show-job (no args) auto-selects job in current window. list-jobs scopes to current session by default.
devctl	choose-project ensures a work tmux session exists, loads from work.yaml layout via tmuxctl load-session, creates per-project windows
wirectl	Enriches wire registry with jobctl data including tmux/prise targets
fixctl	Captures current tmux pane output to diagnose errors
keyctl	Parses tmux keybindings from ~/.config/tmux/tmux.conf + conf.d/*.conf as layer 3 in its binding inventory
prisectl	Parallel implementation for prise multiplexer — run-claude, start-pty, same architecture as tmuxctl for non-tmux environments
hookctl	sync-tmux subcommand keeps job DB in sync; place-pane for manual pane placement

---

6. Scripts

Script	Purpose
scripts/demo-tmuxctl.sh	Speed benchmark — creates session, runs commands, launches Claude, times each step
scripts/install.sh	stow_system tmux links config from system/tmux/.config/tmux/ to ~/.config/tmux/

---

7. Commands & Templates

Tmux context is loaded into most agent workflows via the tmuxctl tool listing in command partials. The /develop, /research, /report, /iterate, /grind, /foster, /adopt, and /prise-* command families all have access to tmuxctl subcommands.

---

8. Data Flow Summary

Claude starts in tmux
  → hooks-tracker captures session/window/pane to SQLite
  → tmux hooks fire hookctl sync-tmux on layout changes
  → jobctl reads DB to auto-detect current context
  → job-callbacks use {job.tmux_target} in notifications
  → wirectl enriches peer discovery with tmux targets

---

Recommendations

• prisectl is the parallel track — it mirrors tmuxctl's architecture for prise. Any new tmuxctl feature likely needs a prisectl equivalent.
• The session-id hook conf is the glue — it keeps the job DB accurate when panes move. If tmux layout tracking ever breaks, start debugging there.
• run-command is the canonical pattern — hookctl config actively steers agents away from raw send-keys + capture-pane toward the one-shot run-command. This is the most important convention to preserve.

---

Metadata

cwd: /Users/mike/code/arthack
session-id: 2c30343d-686e-4c5d-9c61-d1e61f22c21b
session-name: arthack-tmux-inventory
path: /Users/mike/docs/tmux-features-inventory-2026-04-12.md

cd /Users/mike/code/arthack && claude --resume 2c30343d-686e-4c5d-9c61-d1e61f22c21b