# TUI Puppeteering with tmux

> Use when automating or testing TUI/CLI applications - provides isolated tmux sessions with scripts for input, output capture, and state verification

- **Type:** Skill
- **Install:** `agentstack add skill-tilework-tech-nori-skillsets-tui-puppeteering-with-tmux`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tilework-tech](https://agentstack.voostack.com/s/tilework-tech)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [tilework-tech](https://github.com/tilework-tech)
- **Source:** https://github.com/tilework-tech/nori-skillsets/tree/main/.claude/skills/tui-puppeteering-with-tmux
- **Website:** https://www.npmjs.com/package/nori-skillsets

## Install

```sh
agentstack add skill-tilework-tech-nori-skillsets-tui-puppeteering-with-tmux
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
/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

```bash
# 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

```bash
# 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.
```bash
# 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

```bash
/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

```bash
/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):

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

## Assert-Act-Assert Loop

```bash
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:

```bash
cat _failure.log
```

For manual inspection mid-test:

```bash
$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
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](https://github.com/tilework-tech)
- **Source:** [tilework-tech/nori-skillsets](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tilework-tech-nori-skillsets-tui-puppeteering-with-tmux
- Seller: https://agentstack.voostack.com/s/tilework-tech
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.