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:

Word in Text	Without -l	With -l
"Enter"	Presses Enter key	Types the word "Enter"
"Space"	Presses Space key	Types the word "Space"
"Escape"	Presses Escape key	Types the word "Escape"
"Tab"	Presses Tab key	Types the word "Tab"

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.