mitsuhiko/agent-stuff

Overview

This skill programs tmux as a controllable terminal multiplexer to run interactive CLIs (Python, gdb, databases, shells) by sending keystrokes and scraping pane output. It isolates agent sessions on a private socket so agent activity does not clash with a user’s personal tmux. The skill is TypeScript-based and designed for Linux and macOS with stock tmux.

How this skill works

The skill creates a tmux server on a private socket and starts named sessions and panes. It sends literal keystrokes to a target pane, polls or captures pane output to detect prompts or completion text, and cleans up sessions when finished. Helper scripts support polling for text, listing sessions, and capturing pane history with joined lines to avoid wrapping artifacts.

When to use it

• Run an interactive Python REPL or script and exchange code programmatically.
• Drive a debugger (gdb or lldb) for automated debugging tasks.
• Interact with TTY-only tools (ipdb, psql, mysql, node, bash) without attaching a user terminal.
• Isolate agent-driven terminal work to avoid interfering with the user's tmux config.
• Capture or monitor long-running CLI output and wait for specific prompts or completion messages.

Best practices

• Always use a private socket directory (CLAUDE_TMUX_SOCKET_DIR) and tmux -S "$SOCKET" to avoid using the user's tmux instance.
• After starting a session, immediately print a copy/paste monitor command so the user can attach or capture output.
• Prefer literal send-keys (-l or -- with proper quoting) to avoid shell splitting and use control sequences like C-c for interrupts.
• Set PYTHON_BASIC_REPL=1 when launching Python interactive shells to keep prompt behavior stable.
• Poll for prompts or completion text with a timed helper script to avoid race conditions before sending further input.

Example use cases

• Start a Python REPL, wait for the >>> prompt, then send multi-line code and capture results.
• Launch gdb --quiet on a binary, disable pagination, run until a breakpoint, collect backtraces and local variables.
• Spawn a psql or mysql session, run queries programmatically, and capture the last N lines of output.
• Run an instrumented test that prints a completion message, poll the pane for that message, then gather logs.
• Provide the user with an attach command so they can monitor or intervene in the running session.