> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Note>
  Tmux sessions persist independently of the orchestrator. If the orchestrator crashes, agents continue running.
</Note>

## Configuration

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

```yaml theme={null}
plugins:
  runtime: tmux
```

## Requirements

<ParamField path="tmux" type="binary" required>
  Tmux must be installed and available in PATH

  ```bash theme={null}
  # macOS
  brew install tmux

  # Ubuntu/Debian
  apt-get install tmux

  # Verify installation
  which tmux
  ```
</ParamField>

## Runtime API

The tmux plugin implements the standard Runtime interface:

### create(config)

Creates a new tmux session and runs the launch command.

<ParamField path="config.sessionId" type="string" required>
  Session identifier (must match `[a-zA-Z0-9_-]+`)
</ParamField>

<ParamField path="config.workspacePath" type="string" required>
  Working directory for the session
</ParamField>

<ParamField path="config.launchCommand" type="string" required>
  Command to execute on session start
</ParamField>

<ParamField path="config.environment" type="Record<string, string>">
  Environment variables to set in the session
</ParamField>

<Warning>
  Session IDs must contain only alphanumeric characters, hyphens, and underscores. Other characters will cause validation errors.
</Warning>

### sendMessage(handle, message)

Sends a message to the agent by writing to stdin and pressing Enter.

<Info>
  For messages longer than 200 characters or containing newlines, the plugin uses tmux's `load-buffer` + `paste-buffer` to avoid shell truncation issues.
</Info>

### getOutput(handle, lines)

Captures the last N lines of terminal output from the pane.

<ParamField path="lines" type="number" default="50">
  Number of lines to capture from the scrollback buffer
</ParamField>

### destroy(handle)

Kills the tmux session, terminating all processes running in it.

<Note>
  Session cleanup is best-effort. If the session is already dead, `destroy()` returns without error.
</Note>

### isAlive(handle)

Checks if the tmux session exists.

### getAttachInfo(handle)

Returns the command to attach to the session:

```bash theme={null}
tmux attach -t <session-id>
```

## Usage Examples

### Attach to a Running Session

```bash theme={null}
# List all sessions
ao list

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

# Detach without killing: Ctrl+b, then d
```

### View Session Output

```bash theme={null}
# Capture last 100 lines
tmux capture-pane -t my-session-id -p -S -100
```

### Kill a Stuck Session

```bash theme={null}
# 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

<Accordion title="Session creation fails with 'invalid session name'">
  **Cause**: Session ID contains invalid characters

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

  ```yaml theme={null}
  # Good
  sessionId: feature-123_agent-1

  # Bad (contains /)
  sessionId: feature/123
  ```
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="Cannot attach to session">
  **Cause**: Session may have exited or you're using a different tmux server

  **Solution**:

  ```bash theme={null}
  # List all sessions
  tmux list-sessions

  # Check if orchestrator and your shell use the same server
  echo $TMUX_TMPDIR
  ```
</Accordion>

<Accordion title="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.
</Accordion>

## 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 |

<Info>
  Use tmux for development and debugging. Use process runtime for production deployments where you don't need to attach to sessions.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.