tmux-messaging

name: tmux-messaging description: Patterns for sending prompts to Claude Code sessions via tmux send-keys

Messaging: The Enter Key Problem

The Problem

AI agents can compose prompts but cannot press Enter in another terminal. When Claude Code is running in a tmux session, there's no built-in way for an external process to submit a prompt to it.

The Solution

tmux send-keys lets any process inject keystrokes into a tmux pane. The send-message.sh script wraps this into a reliable pattern:

1. Send text using send-keys -l (literal flag prevents key interpretation)
2. Press Enter using a separate send-keys Enter command (without -l)

# Simple message
scripts/send-message.sh my-agent "fix the failing test in auth.ts"

# From a file (avoids shell escaping issues)
scripts/send-message.sh my-agent --file ~/prompts/complex-task.txt

# From stdin (pipe-friendly)
echo "implement pagination" | scripts/send-message.sh my-agent --stdin

# To a specific pane in a multi-agent session
scripts/send-message.sh my-swarm --pane 2 "write integration tests"

Why -l Matters

Without the -l (literal) flag, tmux interprets certain words as special keys:

This is why the message text and the Enter keypress MUST be separate commands.

Agent-to-Agent Messaging Patterns

Orchestrator → Worker

An orchestrator agent creates workers and sends them tasks:

# Create workers
scripts/session-create.sh worker-1 ~/project --interactive --skip-permissions
scripts/session-create.sh worker-2 ~/project --interactive --skip-permissions

# Assign tasks
scripts/send-message.sh worker-1 "implement the user authentication module"
scripts/send-message.sh worker-2 "write unit tests for the API endpoints"

# Check progress
scripts/session-review.sh worker-1 --lines 20
scripts/session-review.sh worker-2 --lines 20

# Send follow-up based on progress
scripts/send-message.sh worker-1 "also add rate limiting to the login endpoint"

Pipeline Pattern

Output from one agent feeds into the next:

# Agent 1: Generate code
scripts/send-message.sh coder "implement the REST API for /products"

# Wait for completion
sleep 60

# Capture output
OUTPUT=$(scripts/session-review.sh coder --lines 100)

# Agent 2: Review the code
echo "Review this code output and identify issues: $OUTPUT" | \
  scripts/send-message.sh reviewer --stdin

Multi-Agent Swarm

All agents work in parallel on different aspects:

scripts/multi-agent-setup.sh my-swarm --agents 4 --workdir ~/project --claude

scripts/send-message.sh my-swarm --pane 0 "implement the database schema"
scripts/send-message.sh my-swarm --pane 1 "implement the API routes"
scripts/send-message.sh my-swarm --pane 2 "implement the frontend components"
scripts/send-message.sh my-swarm --pane 3 "write end-to-end tests"

# Monitor with dashboard
scripts/multi-agent-dashboard.sh my-swarm --watch 10

Interrupt and Redirect

To change what an agent is working on:

# Send Ctrl-C first, then new task
scripts/send-message.sh my-agent --ctrl-c "stop that, instead focus on fixing the login bug"

Complex Prompts

For prompts with special characters, code blocks, or multi-line content, use file input:

cat > /tmp/task.txt << 'PROMPT'
Refactor the authentication module with these requirements:

1. Use JWT tokens instead of sessions
2. Add refresh token rotation
3. Implement the following interface:

```typescript
interface AuthService {
  login(email: string, password: string): Promise<TokenPair>
  refresh(token: string): Promise<TokenPair>
  logout(token: string): Promise<void>
}

Make sure all existing tests still pass. PROMPT

scripts/send-message.sh my-agent --file /tmp/task.txt

## Reference

See `references/send-keys-patterns.md` for detailed escaping rules and tmux key patterns.