How is isolation maintained?

An isolated tmux socket at .tmp/tmux-agent.sock and a dedicated agent-cli session ensure your testing does not touch existing user tmux sessions.

How do I exit safely if the UI ignores input?

Attempt double Ctrl+C (C-c C-c) to exit; if that fails, kill the pane/session as a fallback.

How do I verify the CLI finished correctly?

After exit, capture the final pane and review the summary to confirm the expected exit state and messages.

cli-tmux

npx machina-cli add skill nibzard/skills-kit/tmux --openclaw

Files (1)

SKILL.md

2.7 KB

cli-tmux skill: run & test the CLI using tmux

Use this skill when

The user asks to test the CLI end-to-end and it is interactive (TUI prompts, key navigation).
A command needs a real TTY or long-running process (dev server) that should keep running while we do other tasks.

Golden rules

Prefer scripts/tmuxctl.sh over raw tmux commands for repeatability.
Use an isolated tmux server socket so we don't interfere with the user's real tmux sessions.
Use a predictable session name: agent-cli.
Always capture pane output after each interaction and summarize it before proceeding.
Always clean up: stop the TUI and kill the session at the end (unless the user wants it left running).

tmuxctl.sh wrapper (preferred)

Prefer scripts/tmuxctl.sh over raw tmux commands for repeatability:

scripts/tmuxctl.sh start - Create new tmux session
scripts/tmuxctl.sh run ./bin/ourcli - Run command in the session
scripts/tmuxctl.sh keys Down Down C-m - Send keystrokes
scripts/tmuxctl.sh capture - Capture pane output
scripts/tmuxctl.sh stop - Stop the TUI (double Ctrl+C)
scripts/tmuxctl.sh kill - Kill the session

Our CLI/TUI specifics

To exit the TUI, send double Ctrl+C: C-c then C-c.
If double Ctrl+C doesn't exit, fallback to killing the tmux pane/session.

Standard tmux setup (isolated socket)

Socket path: .tmp/tmux-agent.sock
Session: agent-cli
Pane target: agent-cli:0.0

Create session (if missing)

Ensure .tmp/ exists.
Start detached session in repo root:
- tmux -S .tmp/tmux-agent.sock new-session -d -s agent-cli -c "$PWD"

Start the CLI

Send the run command (replace with our real command):
- Example: ./bin/ourcli OR pnpm ourcli OR go run ./cmd/ourcli
Use:
- tmux -S .tmp/tmux-agent.sock send-keys -t agent-cli:0.0 "<COMMAND HERE>" C-m

Interact

Send keys as needed:
- Enter: C-m
- Up/Down: Up / Down
- Quit: C-c C-c (double)

Capture output (after each step)

tmux -S .tmp/tmux-agent.sock capture-pane -t agent-cli:0.0 -p

End-to-end CLI test recipe

Start session (or reuse if running).
Launch CLI command.
Capture initial screen and confirm expected prompt/state.
Perform the requested flows (send keys + capture after each step).
Exit TUI with C-c C-c, capture output to confirm exit.
Kill session (unless user asked to keep it).

Cleanup

Preferred:
- Send C-c C-c, then tmux ... kill-session -t agent-cli
If tmux is wedged:
- tmux -S .tmp/tmux-agent.sock kill-server

Source

git clone https://github.com/nibzard/skills-kit/blob/main/skills/tmux/skills/tmux/SKILL.mdView on GitHub

Overview

cli-tmux enables end-to-end testing of interactive CLIs/TUIs inside an isolated tmux session. It covers starting a session, sending keys, capturing output, and cleanly stopping with double Ctrl+C. This approach preserves real-TTY behavior without interfering with the user's existing tmux sessions.

How This Skill Works

The workflow uses a dedicated tmux socket (.tmp/tmux-agent.sock) and a predictable session name (agent-cli). Prefer the scripts/tmuxctl.sh wrapper to start, run, send keys, capture, stop, and kill, with a pane-output capture after each interaction. Cleanup involves stopping the TUI with double Ctrl+C and killing the session (or the server if needed).

When to Use It

Interactive CLI/TUI testing where the application prompts and navigates menus
When a command requires a real TTY or long-running background process (e.g., dev servers)
Automated end-to-end flows that must run while you perform other checks
Reproducing flaky interactive prompts by scripting keystrokes
Isolated testing in CI without interfering with local tmux sessions

Quick Start

Step 1: Start isolated session: scripts/tmuxctl.sh start
Step 2: Run the CLI: scripts/tmuxctl.sh run ./bin/ourcli
Step 3: Interact and capture; then stop: scripts/tmuxctl.sh capture; scripts/tmuxctl.sh stop

Best Practices

Prefer scripts/tmuxctl.sh for repeatability over raw tmux commands.
Use an isolated socket at .tmp/tmux-agent.sock to avoid affecting user tmux sessions.
Use a predictable session name: agent-cli (pane target agent-cli:0.0).
Capture pane output after each interaction and summarize it before proceeding.
Clean up by stopping the TUI (double Ctrl+C) and killing the session, or killing the server if wedged.

Example Use Cases

Start a new isolated session and run ./bin/ourcli, then capture the initial screen.
Navigate a TUI menu with Up/Down keys and capture output after each move.
Run a long-running CLI (server) in the session while performing checks in parallel.
Exit the TUI with double Ctrl+C and verify the final screen capture.
Clean up by issuing kill to ensure the isolated socket is closed.

Frequently Asked Questions

Add this skill to your agents