---
name: terminal-harness
which: [tmux, wezterm]
description: "Use when driving or observing an interactive terminal program, including CLIs, TUIs, nested agents, long-running jobs, and terminal E2E tests."
license: GPLv3
compatibility: "Requires an active tmux or WezTerm control context; tmux also supports detached fallback sessions."
---

# Terminal Harness

Drive an interactive program in a terminal that the agent and user can both observe.

## Choose a Provider

1. Use tmux when `TMUX` and `TMUX_PANE` are set and `tmux` is available.
2. Otherwise use WezTerm when `WEZTERM_PANE` is set and `wezterm cli list` succeeds.
3. Otherwise use a detached tmux session when `tmux` is available, then ask the user to attach before continuing observable work.
4. If none applies, report the missing control context and stop.

Read only the selected provider reference:

- [tmux](references/tmux.md)
- [WezTerm](references/wezterm.md)

A future provider needs one reference file and one selection rule here.
Do not create a generic wrapper or common script.

## Harness Contract

- Create one app pane by splitting the current visible pane.
- Prefer a right split; use a lower split when the app needs more width.
- Use a new window only when splitting is unavailable or leaves insufficient space.
- Add another pane only when the tested workflow requires a concurrent product process.
- Keep notes and orchestration outside product panes.
- Launch the program in its working directory through the provider, not by typing setup commands into the pane.
- Record the provider and stable pane ID immediately.

## Drive the App

1. Observe an app-specific ready state before sending input.
2. Send literal text and control keys as separate actions.
3. After each action, capture the current viewport and wait for a visible state change.
4. Poll observable state with a short bound; never use a blind sleep as control flow. Use the wait-until-marker loop from the provider reference.
5. Treat process names as hints, not proof that the app is ready or idle.
6. Use the agent shell for setup, file inspection, and independent verification.

Interrupts are explicit test actions.
Never send `C-c` as generic input clearing.
If input merges, reaches the wrong process, or cannot be attributed, mark that pane polluted and stop using its later output as evidence.

Text capture does not prove colors, layout, animation, cursor behavior, or visual stability.
When those matter, activate the app pane and use an available screenshot or desktop-driving skill.

## Evidence and Lifecycle

- Capture the command, cwd, provider, pane ID, relevant viewport states, and resulting artifacts.
- Distinguish product failures from harness failures.
- Verify app claims through files, processes, browser state, or other external effects.
- Leave the app pane available for inspection unless the user requested cleanup.
- Report the pane ID and provider-specific focus, inspection, and cleanup commands.