tmux - SKILL.md Agent Skill

name: tmux description: Shell scripts for managing Claude Code instances in tmux sessions, enabling multi-agent orchestration, message sending, and session monitoring version: 1.0.0

tmux - Claude Code Multi-Agent Management

Shell-script toolkit for spawning, messaging, monitoring, and cleaning up Claude Code sessions running in tmux. Designed for agents and cron jobs that need to orchestrate multiple Claude Code instances.

Quick Reference

Intent	Script	Example
Start a session	`session-create.sh`	`session-create.sh my-agent ~/project "implement auth"`
List sessions	`session-list.sh`	`session-list.sh`
Send a prompt	`send-message.sh`	`send-message.sh my-agent "fix the failing test"`
Read output	`session-review.sh`	`session-review.sh my-agent --lines 50`
Tail a pane	`pane-tail.sh`	`pane-tail.sh my-swarm --pane 2`
Attach (interactive)	`session-attach.sh`	`session-attach.sh my-agent`
Stop a session	`session-kill.sh`	`session-kill.sh my-agent`
Multi-agent setup	`multi-agent-setup.sh`	`multi-agent-setup.sh my-swarm --agents 3 --workdir ~/project`
Dashboard	`multi-agent-dashboard.sh`	`multi-agent-dashboard.sh my-swarm`
Cleanup	`cleanup.sh`	`cleanup.sh "test-*"`

When to Use

You need to spawn one or more Claude Code sessions programmatically
You need to send prompts to running Claude Code instances (the "Enter key problem")
You need to monitor what Claude Code is doing across multiple sessions
You're building automation (cron, CI, orchestration) around Claude Code

Core Concept: The Enter Key Problem

AI agents can compose prompts but cannot press Enter in another terminal. This skill solves that with send-message.sh, which uses tmux send-keys to deliver text and press Enter in any tmux session. See skills/messaging/SKILL.md for details.

Usage

All scripts are in scripts/. Each supports --help. Exit codes: 0 success, 1 error, 2 resource limit.

Single Session Workflow

SCRIPTS="skills/tmux/scripts"

# Create a session
$SCRIPTS/session-create.sh backend ~/project "implement the REST API for /users"

# Check what it's doing
$SCRIPTS/session-review.sh backend --lines 30

# Send a follow-up prompt
$SCRIPTS/send-message.sh backend "also add pagination to the list endpoint"

# When done, kill it
$SCRIPTS/session-kill.sh backend

Multi-Agent Workflow

SCRIPTS="skills/tmux/scripts"

# Create 3-agent swarm
$SCRIPTS/multi-agent-setup.sh my-swarm --agents 3 --workdir ~/project

# Send tasks to each pane
$SCRIPTS/send-message.sh my-swarm --pane 0 "implement the auth module"
$SCRIPTS/send-message.sh my-swarm --pane 1 "write tests for the API"
$SCRIPTS/send-message.sh my-swarm --pane 2 "set up the database schema"

# Monitor progress
$SCRIPTS/multi-agent-dashboard.sh my-swarm

# Clean up
$SCRIPTS/cleanup.sh my-swarm

Sub-Skills

Sub-Skill	Purpose
`skills/session-management/SKILL.md`	Session lifecycle (create, monitor, kill)
`skills/multi-agent/SKILL.md`	Multi-pane layouts and agent coordination
`skills/messaging/SKILL.md`	Sending prompts and the Enter key problem

References

Reference	Purpose
`references/tmux-scripting.md`	Full tmux command reference for scripting
`references/send-keys-patterns.md`	Escaping rules, `-l` flag, special keys
`references/session-naming.md`	Naming conventions (`[a-zA-Z0-9_-]`)
`references/multi-pane-layouts.md`	Layout patterns with ASCII diagrams
`references/troubleshooting.md`	Common issues and fixes

State and Logs

Session state: /tmp/tmux-skill/sessions/<name>.json
Logs: $OPENCLAW_DIR/logs/tmux-skill.log (default ~/openclaw/logs/)

Relationship to Orchestrator Plugins

This skill can complement higher-level orchestration plugins:

This skill: Standalone shell scripts. No dependencies beyond tmux + jq. Usable from any context (cron, CI, other scripts, agents).
Orchestrator plugins: Higher-level integrations (e.g., TypeScript-based) that provide gateway methods for programmatic session management via a plugin system.

Both approaches use the same underlying tmux patterns (sanitized names, capture-pane, send-keys -l).