tmux

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).