# Tuistory

Drive and test terminal apps (especially the Cline CLI TUI in apps/cli) through...

- Repository: https://github.com/cline/cline (71178 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add cline/cline --skill tuistory -g -a claude-code -y`
Codex: `npx skills add cline/cline --skill tuistory -g -a codex -y`
Cursor: `npx skills add cline/cline --skill tuistory -g -a cursor -y`
Gemini CLI: `npx skills add cline/cline --skill tuistory -g -a gemini-cli -y`

## Description

Drive and test terminal apps (especially the Cline CLI TUI in apps/cli) through tuistory, named background PTY sessions that agents can read, wait on, snapshot, screenshot, and type into. Like Playwright/tmux for terminals, with reactive waiting instead of blind `sleep`. Use this skill when you need to: - Manually test or reproduce bugs in the interactive Cline TUI (`bun run cli -i`) from a headless environment - Run a dev server or any long-lived/interactive process in the background without hanging your tool call - Write or extend Playwright-style e2e tests for the TUI (`bun run test:e2e:tuistory` in apps/cli) - Capture text snapshots or styled PNG screenshots of a TUI screen as evidence

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# tuistory

[tuistory](https://github.com/remorses/tuistory) wraps any terminal command in a named background PTY session backed by a Ghostty terminal emulator. Agents interact with the session via short CLI calls that return instantly; humans can `tuistory attach` to the same session to watch or intervene. No real terminal or display (`DISPLAY`) is needed, it works fully headless, which makes it the preferred way for cloud agents to exercise the Cline TUI.

It is installed as a devDependency of `@cline/cli`, so the pinned binary resolves when you run from `apps/cli`:

```bash
cd apps/cli
bunx tuistory --help   # source of truth for commands, options, and syntax
```

For full upstream docs: `curl -s https://raw.githubusercontent.com/remorses/tuistory/refs/heads/main/README.md`

## Driving the Cline TUI headlessly

Launch the TUI in an isolated environment so you don't touch real user config (`~/.cline`):

```bash
cd apps/cli
DATA_DIR=$(mktemp -d) && HOME_DIR=$(mktemp -d)
bunx tuistory -s cline --cols 120 --rows 36 \
  --env HOME=$HOME_DIR --env CLINE_DATA_DIR=$DATA_DIR \
  --env CLINE_DISABLE_CLINE_PASS_NOTICE=1 --env CLINE_TELEMETRY_DISABLED=1 \
  -- bun src/index.ts --provider anthropic -m claude-sonnet-4-6 -k test-key
```

The dummy `-k test-key` renders the full chat UI; only an actual agent turn would fail. For recorded LLM turns, use the VCR cassettes described in `apps/cli/src/tests/helpers/env.ts` (`CLINE_VCR=playback` + `CLINE_VCR_CASSETTE`). Real turns need a provider credential (e.g. `ANTHROPIC_API_KEY`, `CLINE_API_KEY`).

Then use an **observe → act → observe** loop:

```bash
# Wait reactively for the chat view, never use sleep
bunx tuistory -s cline wait "What can I do for you?" --timeout 30000

# Act, then always observe the resulting screen state
bunx tuistory -s cline type "/settings"
bunx tuistory -s cline snapshot --trim
bunx tuistory -s cline press enter
bunx tuistory -s cline snapshot --trim

The rest: https://github.com/cline/cline/blob/HEAD/.cline/skills/tuistory/SKILL.md