Skip to main content
The tmux runtime plugin manages agent execution in tmux sessions, providing isolated terminal environments with session persistence and easy attachment.

​
Overview

The tmux runtime creates detached tmux sessions for each agent, allowing you to:
  • View agent activity in real-time by attaching to sessions
  • Keep agents running even if you disconnect
  • Send commands to agents via stdin
  • Capture terminal output for activity detection
Tmux sessions persist independently of the orchestrator. If the orchestrator crashes, agents continue running.

​
Configuration

To use the tmux runtime, configure it in your agent-orchestrator.yaml: 
plugins:
  runtime: tmux

​
Requirements

​
tmux
binary
required
Tmux must be installed and available in PATH
# macOS
brew install tmux

# Ubuntu/Debian
apt-get install tmux

# Verify installation
which tmux

​
Runtime API

The tmux plugin implements the standard Runtime interface:

​
create(config)

Creates a new tmux session and runs the launch command.
​
config.sessionId
string
required
Session identifier (must match [a-zA-Z0-9_-]+)
​
config.workspacePath
string
required
Working directory for the session
​
config.launchCommand
string
required
Command to execute on session start
​
config.environment
Record<string, string>
Environment variables to set in the session
Session IDs must contain only alphanumeric characters, hyphens, and underscores. Other characters will cause validation errors.

​
sendMessage(handle, message)

Sends a message to the agent by writing to stdin and pressing Enter.
For messages longer than 200 characters or containing newlines, the plugin uses tmux’s load-buffer + paste-buffer to avoid shell truncation issues.

​
getOutput(handle, lines)

Captures the last N lines of terminal output from the pane.
​
lines
number
default:"50"
Number of lines to capture from the scrollback buffer

​
destroy(handle)

Kills the tmux session, terminating all processes running in it.
Session cleanup is best-effort. If the session is already dead, destroy() returns without error.

​
isAlive(handle)

Checks if the tmux session exists.

​
getAttachInfo(handle)

Returns the command to attach to the session: 
tmux attach -t <session-id>

​
Usage Examples

​
Attach to a Running Session

# List all sessions
ao list

# Attach to session
tmux attach -t my-session-id

# Detach without killing: Ctrl+b, then d

​
View Session Output

# Capture last 100 lines
tmux capture-pane -t my-session-id -p -S -100

​
Kill a Stuck Session

# Graceful shutdown via orchestrator
ao stop my-session-id

# Force kill directly
tmux kill-session -t my-session-id

​
Advanced Features

​
Long Command Handling

For commands exceeding 200 characters, the plugin uses a two-step process:
  1. Write command to a temporary file
  2. Load into tmux buffer and paste
  3. Clean up temp file
This prevents truncation issues in zsh/bash with very long commands.

​
Environment Variables

All environment variables specified in config.environment are passed to the session using tmux’s -e KEY=VALUE flag.

​
Pane Capture

The getOutput() method uses tmux capture-pane -p -S -N to extract the last N lines from the scrollback buffer, providing a snapshot of recent terminal activity.

​
Troubleshooting

Cause: Session ID contains invalid charactersSolution: Ensure session IDs only contain [a-zA-Z0-9_-]
# Good
sessionId: feature-123_agent-1

# Bad (contains /)
sessionId: feature/123
Cause: Very long commands (>200 chars) or special charactersSolution: The plugin automatically handles this using buffer-based paste. If issues persist:
  1. Check for unescaped special characters in the launch command
  2. Verify tmux version >= 2.0
  3. Use shellEscape() from @composio/ao-core for dynamic commands
Cause: Session may have exited or you’re using a different tmux serverSolution:
# List all sessions
tmux list-sessions

# Check if orchestrator and your shell use the same server
echo $TMUX_TMPDIR
Cause: Tmux session killed but child processes detachedSolution: Ensure launch commands don’t use nohup or & to background processes. If needed, use the process runtime plugin instead.

​
Comparison with Process Runtime

FeatureTmuxProcess
PersistenceSurvives orchestrator restartsDies with orchestrator
AttachmentFull terminal via tmux attachNo interactive attachment
OverheadHigher (tmux server + session)Lower (direct child process)
Use CaseInteractive debugging, long-running agentsHeadless automation, CI/CD
Use tmux for development and debugging. Use process runtime for production deployments where you don’t need to attach to sessions.

Build docs developers (and LLMs) love

Get started for freeTalk to us