Repolode
Submit
onesuper

onesuper/tui-use

A CLI that lets AI agents drive interactive terminal programs like REPLs, debuggers and TUI apps through a PTY.

View on GitHub
Stars
270
Forks
25
Open issues
2
Last commit
6 months ago

What is it?

tui-use is a command-line tool that gives AI agents a way to work with programs that expect a human at the keyboard. It spawns a program inside a pseudo-terminal, renders its output through a headless xterm emulator, and exposes the current screen as clean plain text. An agent can then send keystrokes, read the result, and decide what to do next.

The tool targets cases where ordinary shell commands fall short, such as a Python or pdb session holding large in-memory state, a GDB debugging session, a Node REPL, or full-screen apps like vim, lazygit, htop and fzf. A daemon keeps PTY sessions alive across separate CLI calls, so a process does not need to restart between steps.

Instead of sleeping and polling, the `wait` command resolves once the screen has been stable for a configurable idle period, or once a given text pattern appears. Each snapshot also lists inverse-video highlighted regions, which show the active menu item or tab. Installation is via npm, and the project ships plugin bundles for Claude Code and OpenAI Codex.

Key features

  • 01Runs any program in a PTY and renders its output with a headless xterm emulator.
  • 02Provides screen snapshots as plain text, optionally in JSON format.
  • 03Waits for the screen to settle or for a specific text pattern to appear.
  • 04Reports inverse-video highlighted spans so agents can see the active selection.
  • 05Keeps sessions alive across CLI calls through a background daemon.
  • 06Supports typing, pasting, special key presses, scrolling and regex search on screen.

Use cases

  • Debugging a long-running Python session without losing its in-memory state.
  • Driving GDB or pdb breakpoints and variable inspection from an agent.
  • Letting an AI coding agent navigate full-screen tools like vim or lazygit.
  • Running interactive REPL sessions where each step depends on the previous output.

Quick start

  1. 1

    Install the CLI from npm

    npm install -g tui-use
  2. 2

    Start a program in a PTY session

    tui-use start python3 examples/ask.py
  3. 3

    Wait for the screen to settle, then type a response and press Enter

    tui-use wait
  4. 4

    Take a snapshot of the current screen

    tui-use snapshot

Things to know

  • Colors and most text formatting are stripped from the screen output; only highlights, title and fullscreen state are kept.
  • Requires a separate CLI install before the Claude Code or Codex plugins work.

Topics

#terminal#cli#pty#ai-agents#repl#debugging#tui

FAQ

What is tui-use?
A CLI that lets AI agents drive interactive terminal programs like REPLs, debuggers and TUI apps through a PTY. tui-use is a command-line tool that gives AI agents a way to work with programs that expect a human at the keyboard. It spawns a program inside a pseudo-terminal, renders its output through a headless xterm emulator, and exposes the current screen as clean plain text. An agent can then send keystrokes, read the result, and decide what to do next.
Is tui-use free to use? What license does it have?
tui-use is open source under the MIT license. Check the license terms before using it in commercial products.
Is tui-use still maintained?
No commits for 6+ months. The last commit to tui-use was on Apr 11, 2026.
What can I use tui-use for?
Debugging a long-running Python session without losing its in-memory state. Driving GDB or pdb breakpoints and variable inspection from an agent. Letting an AI coding agent navigate full-screen tools like vim or lazygit. Running interactive REPL sessions where each step depends on the previous output.
How do I install tui-use?
Install the CLI from npm: npm install -g tui-use Start a program in a PTY session: tui-use start python3 examples/ask.py Wait for the screen to settle, then type a response and press Enter: tui-use wait Take a snapshot of the current screen: tui-use snapshot
Where can I get tui-use?
The source code and installation instructions are on GitHub: https://github.com/onesuper/tui-use

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects