remorses/tuistory

tuistory – “tmux for AI agents”

What it is – A Node‑JS CLI (and library) that runs any terminal command inside a managed PTY session. The session lives in the background, can be inspected, waited on, typed into, or screenshot‑ed by an AI‑driven agent, while a human can attach to the same session at any time to see exactly what the agent sees.

Why it matters for AI/ML – Current LLM‑based coding agents often need to start a dev server or REPL, then poll or sleep until the process is ready. tuistory gives those agents deterministic, event‑driven control:

• Read logs (tuistory read),
• Wait for specific output (tuistory wait "ready"),
• Take a snapshot or screenshot of the terminal screen,
• Type or press keys into the process, and
• Restart/close the process – all via fast CLI calls that return immediately.

How it works

1. tuistory -- <command> launches the command in a background PTY and registers a session name (auto‑derived from the cwd and command, e.g. myapp-next-dev).
2. A tiny daemon keeps all sessions in memory and exposes a local WebSocket server (bound to 127.0.0.1) for CLI tools and agents to talk to the PTY.
3. Humans can tuistory attach to any session, which behaves like tmux attach – they see the live terminal, can interact, then detach with Ctrl+C twice.
4. Agents use the same CLI (or the programmatic API) to read output, wait for patterns, type, press keys, capture screenshots, etc.

Key CLI commands

Command	Purpose
tuistory -- <cmd>	Start a new session (or re‑attach if it already exists).
tuistory read -s <name> [--all]	Return new stdout since the last read (or the whole buffer).
tuistory wait -s <name> <pattern>	Block until the given text/regex appears.
tuistory wait-idle -s <name>	Block until the terminal has been silent for a configurable delay.
tuistory snapshot -s <name> [--trim]	Get the current screen as plain text.
tuistory screenshot -s <name>	Save the screen as a PNG image.
tuistory type -s <name> "text"	Type characters into the process, one by one.
tuistory press -s <name> <key>	Send a key or chord (e.g. ctrl c).
tuistory restart -s <name>	Restart the original command in the same session.
tuistory close -s <name>	Terminate the process and drop the session.
tuistory attach -s <name>	Human‑only interactive attach (like tmux).
tuistory sessions	List all active sessions.

Programmatic API – The same functionality is exposed as a TypeScript library:

import { launchTerminal } from 'tuistory'
const sess = await launchTerminal({ command: 'claude', cols:150, rows:45 })
await sess.waitForText('Claude Code')
await sess.type('what is 2+2?')
await sess.press('enter')
const out = await sess.read()
sess.close()

The API mirrors the CLI: type, press, text, read, waitForText, click, close, etc.

Typical workflow for an LLM‑based coding agent

# 1️⃣ Start the tool (e.g. a web dev server) in a background session
tuistory -s dev -- pnpm dev

# 2️⃣ Wait until the server prints "ready"
tuistory -s dev wait "ready" --timeout 30000

# 3️⃣ Agent can now run further actions, e.g. open a browser, run tests, etc.
# 4️⃣ When a human wants to see what’s happening:
#    $ tuistory attach -s dev

All steps are non‑blocking for the agent, eliminating the need for arbitrary sleep calls.

Installation

npm install -g tuistory   # global CLI
# or as a project dependency
npm install tuistory

Run tuistory --help for the full option list.

Who should use it

• Developers building LLM‑orchestrated automation (e.g., Claude Code, Auto‑GPT style agents) that need reliable terminal interaction.
• Test engineers who want to script interactive CLI tools (REPLs, debuggers) without flaky sleeps.
• Anyone who already uses tmux for background processes but wants a machine‑readable interface.

Related projects – tuistory powers the author’s termcast (a Raycast‑like terminal UI) and kimaki (Discord bot agents that control TUIs).

License – MIT.