Tmux Integration

The Tmux Integration within Oh-My-OpenCode provides a sophisticated mechanism for AI agents to interact with terminal-based interfaces. It specifically enables the system to handle TUI (Terminal User Interface) and CLI (Command Line Interface) applications by simulating keystrokes, running commands in persistent sessions, and capturing output for validation.

This integration is a core component of the "Agent-Executed QA Scenarios," allowing agents to verify deliverables that lack a traditional graphical UI or API endpoint. By leveraging Tmux, the orchestrator can ensure that command-line tools behave as expected in a real terminal environment without human intervention.
Sources: README.md, src/agents/prometheus/plan-template.ts:107-115

Architecture and Components

The Tmux integration is structured as a feature-set comprising a manager for lifecycle handling, an action executor for command processing, and shared utilities for direct Tmux interaction.

System Overview Diagram

The following diagram illustrates how a user request for CLI/TUI verification flows through the Prometheus planning phase into the Tmux-based execution layer.

Component Responsibilities

Sources: src/features/tmux-subagent/manager.ts, src/features/tmux-subagent/action-executor.ts, src/shared/tmux/index.ts, src/agents/prometheus/plan-template.ts:107-115

Execution Workflow

The integration follows a strict sequence for verifying TUI/CLI applications. This is primarily triggered during the execution of a work plan where a task is marked for interactive_bash verification.

Interaction Sequence

Verification Logic

The verification logic relies on "Agent-Executed QA Scenarios." For Tmux-based tasks, the agent:

1. Initializes: Starts a named Tmux session with a specific command (e.g., ./my-cli --config test.yaml).
2. Monitors: Uses a "Wait for" condition, searching the pane's stdout for specific strings (e.g., "Configuration loaded").
3. Interacts: Sends virtual keystrokes or Escape sequences to navigate menus or trigger actions.
4. Asserts: Validates that the terminal output contains expected values or that the process exits with a specific code.
5. Evidence Capture: Captures the final state of the terminal pane as evidence for the verification report.

Sources: src/agents/prometheus/plan-template.ts:178-185, src/features/tmux-subagent/action-executor.ts

Implementation Details

The implementation leverages standard Tmux commands via a wrapper to ensure consistency across different terminal environments.

Key Tools and Tools Patterns

• interactive_bash: The primary tool used within the planning templates to indicate a Tmux-based verification task.
• Pane Capture: Logic within the shared utilities that executes tmux capture-pane -p to retrieve the current text buffer of the terminal.
• Keystroke Simulation: Use of tmux send-keys to simulate user input, including special keys like Enter, Tab, or arrows.

Sources: src/agents/prometheus/plan-template.ts:111, src/shared/tmux/index.ts, src/features/tmux-subagent/action-executor.ts

Scenario Configuration Example

Verification scenarios are defined in Markdown plans and parsed by the executor.

Scenario: CLI loads config and displays menu
  Tool: interactive_bash (tmux)
  Preconditions: Binary built, test config at ./test.yaml
  Steps:
    1. tmux new-session: ./my-cli --config test.yaml
    2. Wait for: "Configuration loaded" in output (timeout: 5s)
    3. Assert: Menu items visible ("1. Create", "2. List", "3. Exit")
    4. Send keys: "3" then Enter
    5. Assert: "Goodbye" in output
    6. Assert: Process exited with code 0

Sources: src/agents/prometheus/plan-template.ts:178-185

Summary

Tmux Integration enables Oh-My-OpenCode to achieve "Zero Human Intervention" for CLI and TUI projects. By automating terminal interactions, the system can verify complex command-line behaviors, ensuring that implementation matches requirements through direct, observable terminal state validation.
Sources: src/agents/prometheus/plan-template.ts:77-80, README.md