tmux — Claude Code plugin: what it does, how to install
Connects Claude Code to your active terminal panes in tmux. The agent reads watcher logs, inspects dev servers, and sends keystrokes into running REPLs.
MIT ★ 114 updated 2026-08-11
/plugin marketplace add nicknisi/claude-plugins
/plugin install tmux@nicknisiWhat tmux does
The plugin hooks into your terminal environment via hooks/tmux-awareness.sh. When $TMUX is present at launch, Claude immediately receives a snapshot of visible panes alongside their running commands. You do not need to prompt the agent to look around.
Two operational setups exist. Mode A operates on your current window splits. It inspects output through capture-pane and feeds keystrokes into active shells. The bundled safe-send.sh script guards existing panes, refusing to type into editors or pagers without an explicit override. Mode B spawns disposable sessions on an isolated socket using -f /dev/null, keeping experimental processes away from your workspace.
The repository bundles scripts to filter panes by port, poll for expected patterns, and collect exit codes. Any edits made to the startup hook require restarting Claude Code before they take effect.
What it helps with
- inspect dev server errors from adjacent terminal splits
- drive interactive Node REPL sessions and debuggers
- poll a terminal pane for specific output patterns before proceeding
- isolate background tasks inside a temporary tmux socket
Example prompts for the agent
- Check the compiler output in the split running Vite and find the syntax error
- Run tests in pane 2 and wait for the test runner to finish
- Send an expression into the active Node REPL and read back the result
How to install tmux
Plugin marketplace
/plugin marketplace add nicknisi/claude-plugins/plugin install tmux@nicknisiStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about tmux
How to install tmux in Claude Code?
Run two commands in sequence: first add the source via /plugin marketplace add nicknisi/claude-plugins, then run /plugin install tmux@nicknisi.
What does the tmux plugin do in Claude Code?
It exposes your existing terminal window splits to the agent. Claude can inspect running dev servers, scrape pane output, and safely feed keystrokes into interactive CLIs.
How do Mode A and Mode B differ?
Mode A observes and interacts with your active project panes. Mode B spins up an isolated sandbox session on a private socket without touching your workspace.
Source text
tmux · MIT
# tmux Makes Claude aware of tmux — and able to use it. When Claude Code runs inside a tmux pane, the terminals you're watching (dev servers, test watchers, REPLs, logs, editors) live on _your_ tmux server. This plugin lets Claude see and drive those surfaces, instead of only spawning sandbox sessions you can't see. ## Components ### SessionStart hook — `hooks/tmux-awareness.sh` Fires when a session starts. If `$TMUX` is set, it injects a short note plus a live snapshot of your visible panes (location + running command) into Claude's context, and points it at the `tmux` skill for the full workflow. If you're not in tmux, it stays silent. This is what gives Claude _awareness_ — a skill alone only loads on demand, after Claude already suspects tmux is relevant. ### `tmux` skill — `skills/tmux/` The how-to, in two modes: - **Mode A — observe & control the user's tmux.** Detect the server from `$TMUX`, list panes, scrape output with `capture-pane`, and (carefully) send keystrokes into existing panes. Defaults to the current window — the splits for the project you're working on. Includes safety rules for writing into panes you didn't create. - **Mode B — isolated sandbox.** Spawn throwaway sessions on a private socket, kept separate from your tmux (launched with `-f /dev/null` for predictable 0-based indexing). Examples lean toward TypeScript/Node workflows (Node REPL, `vite`/`next dev`, `vitest`, `node inspect`), but the mechanics are language-agnostic. ### Bundled scripts — `skills/tmux/scripts/` - **find-panes.sh** — list panes with command, cwd, and listening ports (`-p`); scoped to the current window by default. - **run-in-pane.sh** — run a command in a shell pane, wait for it to finish, and return only that command's output (with its exit code). - **wait-for-text.sh** — poll a pane for a success pattern, an error pattern (fail fast), or an idle period. - **safe-send.sh** — guarded `send-keys` that refuses editors/pagers/TUIs unless forced. - **find-sessions.sh** — enumerate sessions on a socket (Mode B). ## Notes - Reading panes (`capture-pane`) is always safe. Sending keys into a pane you didn't create can disrupt the user's work — the skill documents when to confirm first and when to use a dedicated window instead. - Hooks load at session start; after editing the hook, restart Claude Code for changes to take effect (`claude --debug` to inspect).
© Nick Nisi · MIT · nicknisi/claude-plugins