Tmux Subagent Integration
Relevant source files
The following files were used as context for generating this wiki page:
Tmux Subagent Integration provides the OhMyOpenCode ecosystem with a persistent, interactive terminal environment. This integration allows agents to move beyond simple shell command execution by enabling full interactive sessions, real-time feedback loops, and the ability to run complex Terminal User Interface (TUI) applications or REPLs.
The system utilizes Tmux to maintain session state across agent turns, preventing the loss of environment variables or process context that typically occurs with standard one-shot execution methods. This capability is central to the project's "Ultrawork" philosophy, where agents act as autonomous engineers capable of deep, persistent work.
Sources: README.md:162-164, src/agents/sisyphus.ts:167-170
Architecture and Components
The integration is built upon a hierarchy of specialized agents and tools that interact with the terminal environment. The orchestration layer, primarily managed by the Sisyphus agent, determines when a persistent terminal session is required versus simple command execution.
Orchestration Flow
Sisyphus acts as the central conductor, delegating tasks to subagents like Hephaestus or Atlas. When a task requires interactive verification or long-running processes (like a dev server or a debugger), Sisyphus utilizes the Tmux-backed interactive environment.
The diagram shows how Sisyphus manages the lifecycle of interactive tasks through the Tmux environment.
Sources: src/agents/sisyphus.ts:40-52, README.md:179-183
Key Components
| Component | Role | Description |
|---|---|---|
| Sisyphus | Orchestrator | Decides when to initiate interactive sessions based on task complexity. |
| Interactive Bash | Tool | Provides the interface for agents to send keystrokes and read terminal output. |
| Tmux Manager | Backend | Handles the lifecycle of Tmux sessions, windows, and panes. |
| Atlas | Verifier | Uses interactive sessions to perform "Hands-on QA" and verify visual/TUI outputs. |
Sources: README.md:179-183, src/agents/atlas/gpt-prompt-sections.ts:153-157
Interactive Verification (Hands-on QA)
A critical use case for the Tmux integration is the Hands-on QA phase. Standard agents often rely solely on exit codes or log files, which may miss visual bugs or interactive logic failures. The Tmux integration allows the Atlas agent to "see" the terminal state.
Phase 3: Hands-on QA Protocol
For any user-facing feature or CLI tool, Atlas follows a mandatory protocol using the interactive terminal:
- TUI/CLI Testing: Run the command using
interactive_bash. - Keystroke Simulation: Send specific keystrokes to navigate menus or trigger behaviors.
- Output Validation: Verify that the terminal output matches expected text patterns or UI states.
- Edge Case Handling: Trigger error conditions (e.g., malformed input) and observe the interactive error handling.
Sources: src/agents/atlas/gpt-prompt-sections.ts:153-162, src/agents/prometheus/plan-template.ts:187-194
Sequence of Interactive QA
This sequence illustrates how Atlas interacts with a TUI application to verify behavior.
Sources: src/agents/atlas/gpt-prompt-sections.ts:157-162, src/agents/prometheus/plan-template.ts:187-194
Plan-Driven Execution
The Prometheus planner incorporates Tmux-based verification into every work plan. In the generated .sisyphus/plans/*.md files, tasks are assigned "QA Scenarios" that explicitly require interactive tools.
Scenario Configuration
Every task must define at least one happy path and one failure scenario using the following interactive parameters:
- Tool: Specified as
interactive_bashorplaywright(if UI-related). - Steps: Exact actions, including specific keystrokes or commands.
- Expected Result: Binary pass/fail conditions observable in the terminal.
- Evidence: Paths to captured terminal output or evidence files (e.g.,
.sisyphus/evidence/task-1.txt).
Sources: src/agents/prometheus/plan-template.ts:182-205, src/agents/prometheus/plan-template.ts:211-215
// Example QA Scenario from Prometheus Plan Template
Scenario: [Happy path - what SHOULD work]
Tool: [interactive_bash (tmux)]
Preconditions: [Exact setup state]
Steps:
1. [Run command with specific flags]
2. [Send keystrokes to navigate TUI]
3. [Assert terminal buffer contains "Success"]
Expected Result: [Concrete, observable pass/fail]
Evidence: .sisyphus/evidence/task-{N}-{scenario-slug}.txt
Sources: src/agents/prometheus/plan-template.ts:187-194
Implementation Constraints
Agents using the Tmux subagent integration are bound by specific operating rules to ensure session stability:
- Persistence: Agents must use
session_idto continue existing terminal sessions instead of spawning new ones, which saves tokens and preserves environment state. - Evidence Mandatory: A task is considered incomplete without evidence captured from the interactive session.
- Anti-Slop: Agents are forbidden from "guessing" terminal output; they must read the actual buffer.
- Parallelism: While multiple
task()calls can be fired in parallel, interactive sessions within a single project context are typically sequential to prevent state collision.
Sources: src/agents/sisyphus.ts:248-261, src/agents/atlas/gemini-prompt-sections.ts:150-155, src/features/builtin-commands/templates/init-deep.ts:28-35
Conclusion
Tmux Subagent Integration transforms the agent from a stateless script executor into a stateful, interactive engineer. By leveraging persistent terminal sessions and mandatory hands-on QA, OhMyOpenCode ensures that complex TUI applications and CLI tools are verified with the same rigor as standard source code.