Tmux Runtime Plugin

Run agents in tmux sessions with full terminal control and session persistence

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

Session creation fails with 'invalid session name'

Cause: Session ID contains invalid characters

Solution: Ensure session IDs only contain [a-zA-Z0-9_-]

# Good
sessionId: feature-123_agent-1

# Bad (contains /)
sessionId: feature/123

Command truncation or mangled output

Cause: Very long commands (>200 chars) or special characters

Solution: 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

Cannot attach to session

Cause: Session may have exited or you’re using a different tmux server

Solution:

# List all sessions
tmux list-sessions

# Check if orchestrator and your shell use the same server
echo $TMUX_TMPDIR

Process keeps running after destroy()

Cause: Tmux session killed but child processes detached

Solution: Ensure launch commands don’t use nohup or & to background processes. If needed, use the process runtime plugin instead.

Comparison with Process Runtime

Feature	Tmux	Process
Persistence	Survives orchestrator restarts	Dies with orchestrator
Attachment	Full terminal via tmux attach	No interactive attachment
Overhead	Higher (tmux server + session)	Lower (direct child process)
Use Case	Interactive debugging, long-running agents	Headless automation, CI/CD

Use tmux for development and debugging. Use process runtime for production deployments where you don’t need to attach to sessions.