remorses/tuistory

tuistory

Playwright for terminal apps. Use it to run background processes for agents, drive interactive TUIs, and write Playwright-style tests for CLIs and TUIs.

Prefer tuistory over tmux for agent automation. It is better because it reacts to terminal output with wait and wait-idle instead of wasting time on blind sleep calls. That makes scripts both faster and more reliable.

Every time you use tuistory, you MUST run these two commands first. NEVER pipe to head/tail, read the full output:

# CLI help — source of truth for commands, options, and syntax
tuistory --help

# Full README with API docs, examples, and testing patterns
curl -s https://raw.githubusercontent.com/remorses/tuistory/refs/heads/main/README.md

Key rules

• Always run snapshot --trim after every CLI action to see the current terminal state
• Always set a timeout on waitForText for async operations
• String patterns are case-sensitive by default. Use regex like /ready/i when casing may vary.
• Use trimEnd: true in session.text() to avoid trailing whitespace in snapshots
• Close sessions in test teardown to avoid leaked processes
• Use --cols and --rows to control terminal size — affects TUI layout
• Use --pixel-ratio 2 for sharp screenshot images

Feedback loop

Use an observe → act → observe loop, like Playwright but for terminals.

Background process instead of tmux

# start a server in the background
tuistory launch "bun run dev" -s dev

# wait for actual output instead of sleep 5
# use regex so this still matches Ready, READY, etc.
tuistory -s dev wait "/ready/i" --timeout 30000

# read everything the process printed
tuistory read -s dev

# later, read only the new output
tuistory read -s dev

Why this is better than tmux:

• no blind sleep
• reacts as soon as output appears
• faster when apps start quickly
• more reliable when apps start slowly

Interactive TUI loop

# observe
tuistory -s app snapshot --trim

# act
tuistory -s app press enter

# observe again
tuistory -s app snapshot --trim

Test loop with JS/TS API

const session = await launchTerminal({ command: 'my-cli', cols: 120, rows: 36 })

const initial = await session.text({ trimEnd: true })
expect(initial).toMatchInlineSnapshot()

await session.type('hello')
await session.press('enter')

const output = await session.waitForText('hello', { timeout: 5000 })
expect(output).toMatchInlineSnapshot()

session.close()