Skip to content

Instantly share code, notes, and snippets.

@possibilities

possibilities/tmux-features-inventory-2026-04-12-v2.md

Created April 13, 2026 03:19
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save possibilities/020e2a4bfbd99ce45322513969dffffb to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save possibilities/020e2a4bfbd99ce45322513969dffffb to your computer and use it in GitHub Desktop.
Download ZIP
ArtHack tmux features inventory (2026-04-12)
Raw
tmux-features-inventory-2026-04-12-v2.md

Tmux Features Inventory - arthack repo

Date: April 12, 2026
Status: Post-removal of hooks-level tmux integration
Repo: /Users/mike/code/arthack

Executive Summary

The arthack project maintains a lightweight, agent-friendly tmux integration layer. The tmux hooks-tracker capture (which was removed on April 12, 2026) has been fully deprecated. The current state consists of:

  1. tmuxctl CLI — Primary command-line interface for session/pane management
  2. Claude Skill (work:tmux) — Agent guidance for interactive terminal work
  3. Cross-tool integrations — jobctl, fixctl, themectl, keyctl, and prisectl use tmux for coordination
  4. Agent advice — tmuxctl command hints in hookctl config (kept, agent-facing)
  5. Demo script — Performance showcase for tmuxctl

1. tmuxctl CLI

Location: /Users/mike/code/arthack/apps/tmuxctl/
CLI entry: apps/tmuxctl/tmuxctl/cli.py (599 lines)
Pattern: Each subcommand has a dedicated run_*.py module

Subcommands

Subcommand Purpose Module
create-session Create new detached tmux session run_create_session.py
create-split Split current pane (auto horizontal/vertical), returns YAML target/pane-id/pid run_create_split.py
check-pane Query pane status: alive, target, pane-id, pid, foreground command run_check_pane.py
run-command Send command, wait for completion, capture output (3-in-1: send-keys + wait + capture) run_run_command.py
send-keys Send keystrokes to pane (append Enter by default, --no-enter for prompts) run_send_keys.py
capture-pane Read pane content (visible area by default, --full for scrollback) run_capture_pane.py
wait-for Poll pane for regex match (0.5s interval, --then-send for one-liners) run_wait_for.py
run-claude Launch Claude Code in detached session, --wait blocks until done run_run_claude.py
load-session Load tmux session from YAML layout in ~/.config/tmuxctl/layouts/ run_load_session.py
show-tree Display session/window/pane tree with real foreground processes run_show_tree.py
tail-panes Show tail of all panes (scope: all, session, or window) run_tail_panes.py
triangulate-self Print current pane's tmux context as YAML (session, window, pane, target) run_triangulate_self.py
show-diff Show git diff in critique or delta (includes untracked files) run_show_diff.py
run-commit Interactive commit wrapper via gitctl (logs output, waits for 'q') run_run_commit.py

Pane-Targeting Conventions

  • Format: SESSION[:WINDOW[.PANE]] with 1-based indexing
  • Examples: work (first pane), work:2 (window 2), work:1.3 (window 1, pane 3)
  • Internal sessions: Names starting with _ are hidden by default (use --show-internal)
  • Recommendation: Always use session name as target, not session:1

2. Tmux Configuration

Status: Stow package removed (commit c3019c23)

The system/tmux/ stow package has been fully removed as of April 12, 2026. Previously contained 3 config fragments:

  • No longer present in the repo

Live user config:
~/.config/tmux/ exists as a symlink:

  • ~/.config/tmux/tmux.conf → symlinks to dotfiles repo (not arthack-managed)
  • ~/.config/tmux/conf.d/ — user-managed directory (not part of arthack)

Note: Tmux configuration is no longer a concern for the arthack project.

3. Claude Code Hooks

Status: Fully removed

The hooks-level tmux integration has been completely removed. Previously provided:

Removed Feature What It Did Removed Via
_capture_tmux_metadata hook Captured session/window/pane context on job start Removed from hooks-tracker
job.tmux_* template variables tmux_session, tmux_window, tmux_pane available in command templates Removed from job.py schema
on_job_named place-pane callback Auto-moved Claude agents to project-specific tmux sessions Removed from dispatcher.py
hooks-tracker tmux columns Tracked job_id → (session, window, pane) in jobs DB Removed from schema
sync-tmux hook Synced hooks-tracker tmux data to prise pipe Removed from hooks.json

Still active: The tmuxctl command advice block in system/hookctl/.config/hookctl/config.yaml (lines 328–332) is kept because it's agent-facing guidance, not hooks-based capture.

4. Claude Skill: work:tmux

Location: /Users/mike/code/arthack/claude/work/skills/tmux/

Files:

  • SKILL.md — Complete skill guide (agent-invocable)
  • references/tmux-commands.md — Advanced command reference

Canonical guidance for agents:

  • Use tmuxctl instead of raw tmux commands
  • Session targeting: use session name, not session:1
  • "Open a pane" = split current window (never create new session/window)
  • run-command is the default for shell commands (one call replaces send-keys + sleep + capture)
  • create-split for panes; always verify with check-pane after splitting
  • wait-for polls at 0.5s; --then-send for one-liner prompt responses
  • Use triangulate-self to discover your own pane before splitting

5. Cross-Tool Integrations

jobctl

Files: apps/jobctl/jobctl/cli.py
Integration: Auto-scopes job lookups by tmux session (identifier can be job name, job_id, session_id, or substring; auto-detects from TMUX_PANE env if omitted)

devctl

Files: apps/devctl/devctl/run_choose_project.py
Integration: Loads tmux session from work.yaml layout via tmuxctl load-session work when picking a project

fixctl

Files: apps/fixctl/fixctl/run_fix_errors.py
Integration: Captures current tmux pane output and working directory (tmux display-message, tmux capture-pane) to feed error context to Claude

themectl

Files: apps/themectl/themectl/run_scrape_themes.py
Integration: Detects current tmux pane (TMUX_PANE env or tmux display-message) and stores it in SCRAPE_PANE for UI server coordination

keyctl

Files: apps/keyctl/keyctl/parsers.py (tmux keybinding parser)
Integration: Parses tmux config files for key bindings (layer: "tmux"), normalizes keys via normalize_tmux_key()

prisectl (prise multiplexer)

Files: apps/prisectl/init.lua
Integration: Session/pane lifecycle management — maintains panes[pty_id] = { cwd, title } and dispatches move_pane_to_session to keep Claude agents organized by project session. Note: This is the new primary agent multiplexer tracker (replaces old hooks-tracker coords).

6. Scripts

Demo Script

Location: /Users/mike/code/arthack/scripts/demo-tmuxctl.sh
Purpose: Performance showcase for tmuxctl

  • Creates session, runs commands, splits panes, launches Claude
  • Times each operation to demonstrate overhead
  • Cleans up on exit

Install Script

Location: /Users/mike/code/arthack/scripts/install.sh
Tmux-related: No specific install steps; tmux is assumed pre-installed (macOS: via homebrew)

7. Commands & Templates

Tool Summaries Partial

Location: claude/arthack/command-templates/_partials/tool-summaries.md.tmpl
Content: Injects tmuxctl agent teaser via tmuxctl --agent-teaser

Core Guidelines Partial

Location: claude/arthack/command-templates/_partials/core.md.tmpl
Content: Guidance that "Teams should never use tmux — always run agents in process"

Agent Advice in hookctl Config

Location: system/hookctl/.config/hookctl/config.yaml (lines 328–332)
Content: Active, kept tmuxctl command tips for agents:

- Targets: use session name (e.g., mysession), not mysession:1
- send-keys --no-enter for interactive prompts (pressing 'y', 'q', C-c)
- wait-for polls at 0.5s; --then-send sends text after a match
- run-claude always passes --skip-commit to claude

8. Data Flow Summary

Before (hooks-tracker capture):

Claude agent starts
  → hooks-tracker captures session/window/pane
  → tmux hooks fire sync-tmux
  → job DB rows updated with (session, window, pane)
  → jobctl reads DB, auto-scopes by tmux session
  → agent can place new panes via on_job_named callback

After (current, post-removal):

Claude agent starts
  → Agent explicitly calls tmuxctl (e.g., tmuxctl create-split)
  → tmuxctl returns target/pane-id/pid as YAML
  → Agent uses target for follow-up commands
  → prisectl maintains session/pane state (prise pipe)
  → jobctl reads session identifier from env if needed

Key difference: No automatic capture. Explicit tooling.

9. Recommendations

Keep Using tmuxctl

  • Still the canonical CLI for tmux control
  • More efficient than raw tmux (run-command is 3-in-1)
  • Agent-friendly output format (YAML, exit codes)

prisectl is the New Primary Tracker

  • Session/pane coords are no longer captured by hooks-tracker
  • prisectl maintains the source-of-truth pane tree via prise pipe
  • Agents that need session tracking should query prisectl, not DB

work:tmux Skill is Canonical

  • Agent guidance for all tmux scenarios
  • Always reference "open a pane = split" rule
  • Emphasize create-split + check-pane pattern for verification

Agent Advice in hookctl Config

  • Kept intentionally (agent-facing, not hooks-based)
  • Review if adding new tmuxctl subcommands

Metadata

Field Value
Working Directory /Users/mike/code/arthack
Session ID a722a7fc-bb9c-49a4-99b9-8b21baa4dd06
Session Name remove-tmux-integration-pieces
Report Path /Users/mike/docs/tmux-features-inventory-2026-04-12-v2.md
Generated 2026-04-12

Resume this session:

claude --resume a722a7fc-bb9c-49a4-99b9-8b21baa4dd06

References

  • Prior inventory (reference style): https://gist.github.com/possibilities/11351b6f4bd68ea9be4529298648459b
  • tmuxctl CLI: /Users/mike/code/arthack/apps/tmuxctl/tmuxctl/cli.py
  • tmux skill: /Users/mike/code/arthack/claude/work/skills/tmux/SKILL.md
  • Demo script: /Users/mike/code/arthack/scripts/demo-tmuxctl.sh
  • Hooks removal commits: c3019c23 (system/tmux), 1bb35932 (session_env table), and related
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment