Skip to main content
plugin

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add nicknisi/claude-plugins
/plugin install tmux@nicknisi
Open on GitHub

What 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@nicknisi

Step 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

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set18

The whole set →
blog-post-writer blog-post-writer converts raw notes, git commits, and logs into a fact-checked, flat blog post draft with explicit author question markers. CX Codex +1 ★ 114repo stars conference-talk-builder conference-talk-builder turns rough notes, transcripts, or a topic into a structured tech talk script with a slide-by-slide plan. Use it to shape ideas into a narrative. CX Codex +1 ★ 114repo stars youtube-notes youtube-notes is a Claude Code skill that turns YouTube captions into chapter-based notes with clickable timestamps. It activates on a YouTube link or a request to analyze a video. CX Codex +1 ★ 114repo stars security-auditor This subagent checks a codebase for critical security flaws through trust-boundary and invariant analysis. Use it for an explicit security audit or vulnerability assessment. CX Codex ★ 114repo stars sources The sources plugin reads X and Reddit posts and turns YouTube videos into timestamped notes. Use it for source triage, video questions, and digests. ★ 114repo stars image-gen image-gen — a skill inside the plugin draws and edits pictures through Gemini or Claude-image-2: diagrams, illustrations, region repaint by mask. ★ 114repo stars essentials essentials is a Claude Code plugin with specialized agents and skills for everyday development, from semantic commits to verified code reviews and session handoffs. ★ 114repo stars content The content plugin for Claude Code turns notes into blog posts and talk plans, then flags common AI writing patterns in prose. ★ 114repo stars

Project sponsors

Companies that keep this analytics open