tmux · mitsuhiko — Claude Code skill: what it does, how to install
Runs interactive CLI sessions inside tmux using an isolated socket. Helpful when an agent must feed keystrokes into Python or lldb and scrape pane output.
npx skills add mitsuhiko/agent-stuff --skill tmux -a claude-codeWhat tmux does
The skill gives the agent a way to spin up detached terminal multiplexer sessions, send keys to them, and scrape pane text. To keep your personal tmux server untouched, all agent sessions live on a private socket under CLAUDE_TMUX_SOCKET_DIR (or ${TMPDIR:-/tmp}/claude-tmux-sockets). It runs on Linux and macOS with a stock tmux install.
Two helper scripts drive synchronization: find-sessions.sh discovers running sessions, and wait-for-text.sh polls pane lines against a regex until a prompt appears. For debugging sessions, the skill defaults to lldb. For Python interactive shells, setting PYTHON_BASIC_REPL=1 is mandatory; otherwise the advanced REPL breaks the automated send-keys input.
Whenever a session starts, the agent provides a ready-made tmux attach or capture-pane command so you can step in. Cleaning up takes a single kill-session or kill-server call on the private socket.
What it helps with
- Run interactive REPL sessions like Python or node in the background
- Automate debugging workflows with lldb or gdb
- Prevent agent terminal sessions from interfering with user tmux sessions
- Poll pane output for specific prompt patterns with a timeout
Example prompts for the agent
- Start a python session in tmux, import json, and print a test dictionary
- Run lldb against ./build/app in a background session and fetch the backtrace
- Open a detached tmux shell, tail the service log, and wait for the ready signal
How to install tmux
1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill tmux -a claude-code2Manually: put the files in place
~/.claude/skills/tmux/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/tmux/
1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill tmux -a codex2Manually: put the files in place
.agents/skills/tmux/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill tmux -a cursor2Manually: put the files in place
.cursor/skills/tmux/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install mitsuhiko/agent-stuff tmux2Manually: put the files in place
.github/skills/tmux/SKILL.md1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill tmux -a gemini-cli2Platform CLI
gemini skills install https://github.com/mitsuhiko/agent-stuff --path skills/tmuxManually: put the files in place
.devin/skills/tmux/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill tmux -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about tmux
How do I install tmux for Claude Code?
Run npx skills add mitsuhiko/agent-stuff --skill tmux -a claude-code. The skill file will be placed in ~/.claude/skills/tmux/SKILL.md.
Why does this skill create a separate tmux socket?
It isolates agent sessions under CLAUDE_TMUX_SOCKET_DIR so background processes do not clash with your personal tmux configuration or active windows.
Why does Python need PYTHON_BASIC_REPL=1 in this skill?
Modern Python consoles with multi-line editing interfere with raw send-keys sequences. Forcing PYTHON_BASIC_REPL=1 restores basic line input that the agent can script reliably.
Similar skills
All skills for Agent setup: memory, context, orchestration →tmux by other authors comes first.
