How to use the tmux Terminal Control agent skill

What the tmux skill makes the agent do

Normally an AI agent can only run one-off shell commands and read their output. With this skill installed, the agent can start programs inside tmux, a terminal multiplexer that keeps sessions alive in the background. It can type keystrokes into those sessions, read what is on screen, and wait for a particular prompt or text to appear.

This is useful for tools that need an interactive terminal, such as Python's REPL, or for running several coding agents side by side in separate sessions.

Install the tmux skill from the ZIP

Download the ZIP for the tmux skill from this page and unzip it. Then place the resulting skill folder in one of these locations:

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal skills: ~/.claude/skills/
• Project skills: a project's .claude/skills/ folder

What you need before using it

The skill has specific requirements. Check them before you install it, because the skill will not work without tmux.

On Windows, the skill requires WSL, with tmux installed inside WSL.

• tmux installed and available on PATH
• A bash shell, since the scripts use bash
• macOS or Linux (Windows requires WSL)
• The skill runs scripts, and it does not use the network

Trigger the skill with natural requests

You do not need special syntax. Describe the job in plain language and mention the interactive or parallel nature of the work. The skill's own guidance is to use tmux only when an interactive TTY is needed. For long-running, non-interactive tasks, normal background execution is preferred.

Good requests name the program to run and what you want to see or wait for. For example, you might ask the agent to open a Python REPL in tmux and evaluate some expressions, or to start two coding agents in separate sessions and report when each one returns to its prompt.

• Start a Python REPL in a tmux session and run a calculation in it
• Watch a session and tell me when the output contains 'Server started'
• Run two coding agents in separate tmux sessions and check which one has finished

Common workflows the skill supports

The skill includes a quickstart that uses an isolated tmux socket. It creates a session, starts Python with the basic REPL setting, and captures the last 200 lines of the pane. The agent also prints monitor commands so you can attach to the session yourself. You can detach again with Ctrl+b d.

The helper script wait-for-text.sh polls a pane for a regex, or a fixed string if you add -F, until the text appears or a timeout is reached. Its default timeout is 15 seconds, and its default poll interval is 0.5 seconds.

• Find sessions with find-sessions.sh, either on your socket or across all sockets
• Send literal text with send-keys -l, or control keys such as C-c
• Clean up sessions with kill-session or kill-server when finished

Safety notes: scripts and keystrokes

The skill runs scripts, so review the files in scripts/ (find-sessions.sh and wait-for-text.sh) before you install it if you have not already done so. The skill does not use the network.

Sent keystrokes are not reviewed. Input sent to a live session can run commands, including destructive ones, with no review step. Do not use this skill on a machine where the agent should not type into live sessions. The skill's guidance is to prefer literal sends (send-keys -l) for safer input handling.

• Read the scripts before first use
• Use separate sockets and short, clearly named sessions
• Clean up sessions when the work is done

Tips for better results

When you run several coding agents in parallel, the skill's tips suggest using separate git worktrees for parallel fixes so branches do not conflict, and running pnpm install first in fresh clones. To detect that an agent has finished, check for the shell prompt (❯ or $). Codex needs --yolo or --full-auto for non-interactive fixes, so consider the risks of those flags before using them.

For Python REPLs, set PYTHON_BASIC_REPL=1, because a non-basic REPL breaks send-keys flows.

• Keep session names short and avoid spaces
• Set NANOBOT_TMUX_SOCKET_DIR if you want a custom socket location
• Use the capture-pane command to read more history when output is long