# tmux

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 413 installs · ★ 3195
- Author: mitsuhiko
- License: Vibecoded · policy=link-only · description only; the file stays with the author
- Source: https://github.com/mitsuhiko/agent-stuff/tree/HEAD/skills/tmux/SKILL.md
- Updated: 2026-09-27
- HTML: https://affpapa.org/en/nevibecode/skills/mitsuhiko-tmux

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add mitsuhiko/agent-stuff --skill tmux -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/tmux/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/tmux/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add mitsuhiko/agent-stuff --skill tmux -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tmux/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add mitsuhiko/agent-stuff --skill tmux -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tmux/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install mitsuhiko/agent-stuff tmux
```

2. **Manually: put the files in place**
- File: `.github/skills/tmux/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add mitsuhiko/agent-stuff --skill tmux -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/mitsuhiko/agent-stuff --path skills/tmux
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tmux/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add mitsuhiko/agent-stuff --skill tmux -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/mitsuhiko/agent-stuff/tree/HEAD/skills/tmux/SKILL.md

## When to use it
- 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
- 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

## Similar
- [setup-matt-pocock-skills](https://affpapa.org/en/nevibecode/skills/setup-matt-pocock-skills.md) — skill · 1052851 installs
- [ask-matt](https://affpapa.org/en/nevibecode/skills/ask-matt.md) — skill · 766587 installs
- [to-tickets](https://affpapa.org/en/nevibecode/skills/to-tickets.md) — skill · 711230 installs
- [writing-plans](https://affpapa.org/en/nevibecode/skills/writing-plans.md) — skill · 282859 installs
- [caveman-review](https://affpapa.org/en/nevibecode/skills/caveman-review.md) — skill · 411800 installs
- [caveman-compress](https://affpapa.org/en/nevibecode/skills/caveman-compress.md) — skill · 411500 installs

## Other versions with the same name
- [tmux · openclaw](https://affpapa.org/en/nevibecode/skills/tmux.md) — 8400 installs

From the same set: [mitsuhiko/agent-stuff](https://affpapa.org/en/nevibecode/by/mitsuhiko/agent-stuff.md) — 5 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md