Guide · Agent skill
How to use the tmux Session Control agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The tmux Session Control skill lets an AI agent look inside terminal sessions that tmux keeps running in the background. It can read what is on screen, type text, press keys such as Enter or Ctrl+C, list sessions and wait for a line of text to appear. This guide explains what the skill does, how to install it, how to ask for things in plain language, and what to watch out for before you let it act in a terminal.
tmux Session Controlspinabot/brigade · MIT Download the skill Quick start
- 1Check your system. Confirm you are on macOS or Linux and that tmux and a Bash shell are available.
- 2Download the ZIP. Download the tmux skill ZIP from this page.
- 3Install the skill. Unzip it into ~/.claude/skills/ for all projects, into a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 4Start your tmux sessions. Run your interactive tools inside named tmux sessions such as shared or worker-2, so the agent has something to target.
- 5Ask in plain language. Request a check, such as asking what worker-3 is showing or whether it is waiting for input.
- 6Review before approving. Read what the agent found before it sends a y, Enter or other keystroke to a session that matters.
What is the tmux Session Control skill?
An agent skill is a folder of instructions (a SKILL.md file plus any helper scripts) that an AI agent loads when a task matches it. This one teaches the agent to control tmux sessions by sending keystrokes and reading pane output.
The main use is monitoring and answering prompts from other interactive programs that run inside tmux, such as parallel Claude Code or Codex sessions. The skill's own examples use a primary session called shared and parallel workers named worker-2 through worker-8.
- Read what is currently shown in a session or pane
- Send text, or keys such as Enter, Escape, Ctrl+C, Ctrl+D and Ctrl+Z
- List sessions and windows, and create or kill sessions
- Wait until a particular line of text appears (via the wait-for-text helper)
Requirements before you install
The skill runs on macOS (darwin) and Linux only. Its metadata lists those as the supported systems, so it is not intended for Windows.
You need tmux installed and a Bash shell for the helper scripts. The skill's metadata includes a Homebrew install step using the tmux formula, so Homebrew is one option if tmux is not already on your machine.
- macOS or Linux
- tmux installed (Homebrew formula: tmux)
- Bash shell for scripts/find-sessions.sh and scripts/wait-for-text.sh
How to install the tmux skill
Download the skill's ZIP file from this page. Then choose one of the two install routes below.
Option A, personal skills: unzip the file into ~/.claude/skills/ so the skill is available across your projects.
Option B, project skills: unzip the file into the .claude/skills/ folder inside a specific project. It then applies only to that project.
Option C, Claude apps: upload the skill in the Claude apps under Settings → Capabilities → Skills.
How to trigger the skill with natural requests
You do not need special syntax. Describe the task in plain language that mentions tmux, sessions or the terminal work you want checked. The agent matches the request to the skill's 'When to Use' list, which covers monitoring Claude or Codex sessions, sending input to interactive terminal applications, scraping output from long-running processes, and checking on background work in existing sessions.
Name the session when you can. Clear names like shared or worker-3 make it easier for the agent to find the right target.
- Check on worker-3 and tell me if it is waiting for permission.
- Look at the last 20 lines of the shared session.
- Tell worker-4 to fix the bug in auth.js and press Enter.
- List all my tmux sessions and what each one is doing.
Commands the skill uses and what they do
Under the hood the agent runs standard tmux commands. You can run the same commands yourself to understand what the agent sees and does.
Target format is session:window.pane, for example shared:0.0. Use capture-pane -p to print the screen to stdout, and -S - to include the entire scrollback history.
- tmux ls lists sessions
- tmux capture-pane -t shared -p | tail -20 shows the last 20 lines
- tmux send-keys -t worker-3 'y' Enter approves a y/n prompt
- tmux send-keys -t shared -l -- text sends literal text, then Enter is sent separately
tmux capture-pane -t shared -p | tail -20Safe input and a worked example
For interactive terminal apps such as Claude Code or Codex, the skill sends text and Enter as separate steps to avoid paste and multiline problems. A short pause sits between them.
A typical check on a worker looks for prompt markers in the last few lines, then answers only if the session is waiting for input.
tmux send-keys -t shared -l -- 'Please apply the patch in src/foo.ts'
sleep 0.1
tmux send-keys -t shared EnterSafety notes: scripts, network and sensitive sessions
The skill runs scripts (scripts/find-sessions.sh and scripts/wait-for-text.sh) and the metadata marks it as running scripts. It does not declare network use.
The biggest risk is not network access but input. The agent can send keystrokes that approve permission prompts, so if it is pointed at the wrong session it can act in a terminal without your review. Do not use it on sessions where a mistaken 'y' would cause harm, and keep sensitive work in sessions you are happy for an agent to touch.
Do not use this skill for one-off shell commands, starting background processes or non-interactive scripts. The skill itself says to use the exec tool for those.
- Scripts run: yes
- Network use: no
- Avoid sessions with production credentials or destructive prompts unless you are supervising
What people use it for
- Checking whether parallel Claude Code workers are idle, busy or waiting for permission
- Approving routine y/n or numbered prompts in a worker session you have already reviewed
- Sending a follow-up task to a worker session, such as a bug fix request
- Reading the scrollback of a long-running process to see its last results
- Listing sessions and windows to get an overview of your running terminal work
Frequently asked questions
Is the tmux Session Control skill free?
The skill is published under the MIT licence, as stated on this page. tmux itself is a separate tool that you install on your own machine.
What do I need to install the tmux agent skill?
You need macOS or Linux, tmux installed, and a Bash shell for the helper scripts. The skill's metadata includes a Homebrew install step for tmux.
Does the tmux skill work on Windows?
The skill's metadata lists only darwin (macOS) and linux as supported systems, so it is not intended for Windows.
Where do I put the skill folder after downloading the ZIP?
Unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.
Can the agent accidentally approve something dangerous?
Yes. The agent can send keystrokes such as y and Enter, so if it targets the wrong session it can approve a permission prompt without your review. Use it on sessions where that risk is acceptable and supervise sensitive work.
Should I use this skill or just run tmux commands myself?
For a single quick check, running tmux capture-pane or tmux send-keys yourself is enough. The skill is useful when an agent should monitor several sessions over time. For one-off shell commands or non-interactive scripts, the skill's own guidance says to use a normal exec tool instead.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers who run several interactive coding agents or CLI tools in tmux and want an agent to check on them or answer routine prompts. It is a poor fit for Windows users, simple one-off commands or sessions where an accidental keystroke would matter, so pick a normal exec tool or manual tmux commands in those cases.
Download the skill