home / skills / pchalasani / claude-code-tools / tmux-cli

tmux-cli skill

safe

This skill helps you coordinate and automate tasks across tmux panes using the tmux-cli tool, enabling seamless cross-pane communication.

npx playbooks add skill pchalasani/claude-code-tools --skill tmux-cli

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.3 KB

---
name: tmux-cli
description: CLI utility to communicate with other CLI Agents or Scripts in other tmux panes; use it only when user asks you to communicate with other CLI Agents or Scripts in other tmux panes.
---

# tmux-cli

## Instructions

Use the `tmux-cli` command to communicate with other CLI Agents or Scripts in
other tmux panes. Do `tmux-cli --help` to see how to use it!

This command depends on installing the `claude-code-tools`. If you get an error
indicating that the command is not available, ask the user to install it using:
`uv tool install claude-code-tools`.

## Key Commands

### Execute with Exit Code Detection

Use `tmux-cli execute` when you need to know if a shell command succeeded or
failed:

```bash
tmux-cli execute "make test" --pane=2
# Returns JSON: {"output": "...", "exit_code": 0}

tmux-cli execute "npm install" --pane=ops:1.3 --timeout=60
# Returns exit_code=0 on success, non-zero on failure, -1 on timeout
```

This is useful for:

- Running builds and knowing if they passed
- Running tests and detecting pass/fail
- Multi-step automation that should abort on failure

**Note**: `execute` is for shell commands only, not for agent-to-agent chat.
For communicating with another Claude Code instance, use `send` + `wait_idle` +
`capture` instead.

Overview

This skill provides a CLI utility to communicate with other CLI agents or scripts running in different tmux panes. It exposes commands to execute shell commands remotely and to coordinate with other agent instances for messaging and output capture. Use it only when you need direct pane-to-pane interaction inside tmux.

How this skill works

The tool issues commands into specified tmux panes and returns structured results such as captured output and exit codes. For shell commands use the execute command, which returns JSON with output and exit_code and supports timeouts. For agent-to-agent messaging, use a sequence of send, wait_idle, and capture to deliver messages and retrieve responses.

When to use it

Run a build or test inside another pane and detect success or failure programmatically
Trigger and monitor long-running jobs running in separate tmux panes
Coordinate messages between multiple CLI agents or scripts inside tmux
Capture output from a background agent process for logging or decision-making
Automate multi-pane workflows where steps must abort on command failure

Best practices

Prefer tmux-cli execute for pure shell commands; it returns exit codes to drive control flow
For agent-to-agent chat use send + wait_idle + capture rather than execute
Always set a sensible timeout to avoid indefinite waits when a pane becomes unresponsive
Reference panes with clear identifiers (session:window.pane) to avoid ambiguity
Ensure claude-code-tools is installed if the command is not found (install via the tool manager when prompted)

Example use cases

Run test suites in a dedicated pane and abort deployment on nonzero exit code
Send a prompt to another Claude Code agent and wait for it to finish processing before capturing its reply
Install dependencies in an operations pane and capture the installer output for audit logs
Orchestrate a multi-step build across panes, stopping the pipeline if any step fails
Monitor a long-running analysis script and capture final results once it signals idle

FAQ

What does tmux-cli execute return?

It returns JSON with the captured output and an exit_code (0 for success, nonzero for failure, -1 on timeout).

What if the tmux-cli command is not available?

Install the runtime tools required by the environment (for example, the claude-code-tools package via your environment's tool installer) and retry.