remorses/tuistory

What it solves

Tuistory allows AI agents to interact with long-lived terminal processes—such as development servers, REPLs, and interactive CLIs—without blocking their execution. It solves the problem of agents hanging when starting a server or having to rely on blind sleep commands to guess when a process is ready.

How it works

Tuistory wraps terminal commands in named background sessions managed by a relay daemon. This architecture allows both humans and AI agents to connect to the same session. Humans can attach to the terminal interactively (similar to tmux), while agents use a CLI or programmatic API to read logs, wait for specific text patterns (regex), take snapshots of the screen, and send keystrokes into the process.

Who it’s for

• AI Agent Developers: Those building coding agents that need to run and monitor dev servers or use interactive terminal tools.
• TUI Developers: Developers creating terminal user interfaces that need to be automated or tested.
• Automation Engineers: Users who want a programmatic way to control TTY processes.

Highlights

• Reactive Waiting: Replaces blind sleep with wait and wait-idle commands that react instantly to terminal output.
• Shared State: Humans and agents can share the same terminal session, allowing humans to step in and interact with a process an agent started.
• Programmatic Control: Includes a TypeScript library that acts like "Playwright for terminals," enabling precise control over PTYs.
• Visual Inspection: Supports capturing the current terminal screen as text snapshots or PNG images.
• CWD and Env Inheritance: Forwards the full environment and PATH from the calling shell to child processes.
• Idempotent Execution: Prevents "port already in use" errors by reattaching to existing sessions instead of failing.