TUI Puppeteering with tmux

TUI Puppeteering

CRITICAL: Use ONLY the bundled scripts in /home/clifford/Documents/source/nori/skillsets/.claude/skills/tui-puppeteering-with-tmux/ to interact with tmux. Direct tmux commands risk destroying user sessions. The bundled scripts enforce isolation automatically.

Workflow

Add to TodoWrite before ANY interaction:

1. Write a Test Plan (required before execution)
2. Start session with tui-start
3. Assert-Act-Assert loop: verify state, send input, verify result
4. Cleanup with tui-stop

Test Plan (Mandatory)

Before running any commands, output a plan block:

"Let me try pressing enter then quiting"

Plan: Start ./my-app, expect "Welcome". Press Enter, expect "Menu". Press 'q' to exit.

Scripts

All scripts use hardcoded socket nori-agent-sock for isolation.

tui-start

/home/clifford/Documents/source/nori/skillsets/.claude/skills/tui-puppeteering-with-tmux/tui-start  ""

Creates isolated session with 120x40 geometry, runs command, disables status bar.

tui-assert

# Fixed string match (default)
/home/clifford/Documents/source/nori/skillsets/.claude/skills/tui-puppeteering-with-tmux/tui-assert  "" [timeout]

# Regex match
/home/clifford/Documents/source/nori/skillsets/.claude/skills/tui-puppeteering-with-tmux/tui-assert  -E "" [timeout]

Default timeout: 5s. On failure, writes _failure.log.

sleep 2 # Never blindly sleep

tui-assert "mytest" "Ready>" 10 tui-assert "mytest" -E "Error:.*code [0-9]+" 5

tui-send

# Literal text (no Enter)
/home/clifford/Documents/source/nori/skillsets/.claude/skills/tui-puppeteering-with-tmux/tui-send  ""

# Special keys
/home/clifford/Documents/source/nori/skillsets/.claude/skills/tui-puppeteering-with-tmux/tui-send  --keys "Enter"
/home/clifford/Documents/source/nori/skillsets/.claude/skills/tui-puppeteering-with-tmux/tui-send  --keys "C-c"

Use --keys for: Enter, Escape, Tab, Space, BSpace, Up, Down, Left, Right, C-a to C-z, F1-F12.

Escape key timing: Sending Escape immediately followed by another key may be interpreted as Alt+key.

# BAD: May become Alt+j
$SCRIPTS/tui-send "$SESSION" --keys "Escape"
$SCRIPTS/tui-send "$SESSION" --keys "j"

# GOOD: Add delay after Escape
$SCRIPTS/tui-send "$SESSION" --keys "Escape"
sleep 0.2
$SCRIPTS/tui-send "$SESSION" --keys "j"

tui-capture

/home/clifford/Documents/source/nori/skillsets/.claude/skills/tui-puppeteering-with-tmux/tui-capture 

Returns current screen content. Use for debugging mid-flow.

Optional flags (rarely needed):

| Flag | Use Case | |------|----------| | -e | Preserve ANSI color codes (for testing colored output) | | -S N | Include N lines of scrollback history | | -a | Capture inactive buffer instead of active |

These flags are rarely needed. The default captures what the user sees.

• -e: Only if explicitly testing colors
• -S: Only if output scrolled off screen
• -a: Only if app uses altscreen AND you need the hidden buffer

tui-stop

/home/clifford/Documents/source/nori/skillsets/.claude/skills/tui-puppeteering-with-tmux/tui-stop 

Kills session and cleans up. Always call when done, even on failure.

tmux-isolated

For any direct tmux commands (cleanup, advanced usage):

/home/clifford/Documents/source/nori/skillsets/.claude/skills/tui-puppeteering-with-tmux/tmux-isolated 

Assert-Act-Assert Loop

SCRIPTS="/home/clifford/Documents/source/nori/skillsets/.claude/skills/tui-puppeteering-with-tmux"
SESSION="test-feature"

# Start
$SCRIPTS/tui-start "$SESSION" "./my-app"

# ASSERT initial state
$SCRIPTS/tui-assert "$SESSION" "Welcome" 10

# ACT
$SCRIPTS/tui-send "$SESSION" "hello"
$SCRIPTS/tui-send "$SESSION" --keys "Enter"

# ASSERT result
$SCRIPTS/tui-assert "$SESSION" "Response:" 10

# Cleanup
$SCRIPTS/tui-stop "$SESSION"

Debugging Failures

On assertion failure, check the auto-generated log:

cat _failure.log

For manual inspection mid-test:

$SCRIPTS/tui-capture "$SESSION"

Safety

NEVER use tmux kill-server without the isolated socket—it destroys ALL user sessions. Only use tui-stop or tmux-isolated kill-session -t .

Verification

Run the test suite to verify scripts work:

bash /home/clifford/Documents/source/nori/skillsets/.claude/skills/tui-puppeteering-with-tmux/test_tui_scripts.sh

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tilework-tech
• Source: tilework-tech/nori-skillsets
• License: Apache-2.0
• Homepage: https://www.npmjs.com/package/nori-skillsets

Install and usage instructions live in the source repository linked above.