Skip to content
Back to search

tui-use

MarketplaceWorks with Claude CodeGitHub

tui-use lets agents interact with programs that expect a human at the keyboard — REPLs, debuggers, TUI apps, and anything else bash can't reach.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/onesuper--tui-use/badge.svg)](/listings/onesuper--tui-use)

HTML

<a href="/listings/onesuper--tui-use"><img src="/api/listings/onesuper--tui-use/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**From npm (recommended):**

npm install -g tui-use

**From source:**

git clone https://github.com/onesuper/tui-use.git
cd tui-use
npm install
npm run build
npm link

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 22 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "tui-use",
  3. "metadata": {
  4. "description": "TUI automation for AI agents — interact with REPLs, installers, and TUI apps"
  5. },
  6. "owner": {
  7. "name": "onesuper",
  8. "email": "onsuper.cheng@gmail.com"
  9. },
  10. "plugins": [
  11. {
  12. "name": "tui-use",
  13. "description": "TUI automation for AI agents — Like BrowserUse, but for the terminal",
  14. "version": "0.4.0",
  15. "source": "./",
  16. "author": {
  17. "name": "onesuper",
  18. "email": "onsuper.cheng@gmail.com"
  19. }
  20. }
  21. ]
  22. }
README.md · README · 214 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # tui-use
  3. **Like BrowserUse, but for the terminal.**
  4. tui-use lets agents interact with programs that expect a human at the keyboard — REPLs, debuggers, TUI apps, and anything else bash can't reach.
  5. [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![npm](https://img.shields.io/npm/v/tui-use.svg)](https://www.npmjs.com/package/tui-use)
  6. </div>
  7. ## What is tui-use?
  8. AI agents can run shell commands and call APIs — but they can't interact with programs that expect a human at the keyboard. The moment a REPL waits for input, a debugger hits a breakpoint, or a TUI app renders a menu, agents are stuck.
  9. tui-use fills that gap. Spawn any program in a PTY, read its screen as plain text, send keystrokes — all from the command line. Built for the cases where bash isn't enough: live debugging sessions with gigabytes of in-memory state, interactive REPLs, full-screen TUI apps.
  10. ### Use cases
  11. - **Scientific computing & large in-memory state** — When your variables are arrays with millions of elements that took an hour to compute, you can't dump them to a log file. Drop an agent into a live Python interpreter or pdb session to debug, inspect, and optimize without losing the running process.
  12. - **Debugger sessions** — Drive GDB, PDB, or any interactive debugger. Set breakpoints, step through code, inspect variables — all from an agent, without restarting the process.
  13. - **REPL sessions** — Run code in Python, Node, or any interactive interpreter, inspect the output, and keep going. No more one-shot scripts when you need an interactive session.
  14. - **TUI applications** — Navigate vim, lazygit, htop, fzf, and other full-screen programs that were never designed to be scripted.
  15. Perfect for **Claude Code**, **Cursor**, **Codex**, **Gemini CLI**, **OpenCode** and other AI coding agents.
  16. ### Why not tmux?
  17. tmux is great for humans — but it was never designed for agents.
  18. `tmux send-keys` has no way to signal when a program is done responding. Agents are stuck guessing: `sleep 2` and hope, or poll `capture-pane` in a loop.
  19. tui-use observes every PTY render event directly. `wait` blocks until the screen stabilizes — no sleep, no polling. `wait --text ">>>"` goes further: wait for a semantic signal, not just silence.
  20. ## Features
  21. - **🖥️ Full VT Rendering** — PTY output is processed by a headless xterm emulator. ANSI escape sequences, cursor movement, and screen clearing all work correctly. The `screen` field is always clean plain text.
  22. - **⏱️ Smart Wait** — `wait` blocks until the screen has been stable for a configurable idle window (debounce), so agents never need to guess how long to sleep. Use `wait --text <pattern>` for semantic signals — wait until the program tells you it's ready, not just until it goes quiet.
  23. - **📸 Snapshot Model** — Interacting with a terminal program is just a loop: read what's on screen, decide what to type, repeat. tui-use makes that loop explicit — no async streams, no timing guesswork, no partial output to reassemble.
  24. - **🔍 Highlights** — Every snapshot includes a `highlights` field listing the inverse-video spans on screen — the standard way TUI programs indicate selected items. Agents can read which menu option, tab, or button is currently active without parsing text or guessing from cursor position.
  25. ## Installation
  26. **From npm (recommended):**
  27. ```bash
  28. npm install -g tui-use
  29. ```
  30. **From source:**
  31. ```bash
  32. git clone https://github.com/onesuper/tui-use.git
  33. cd tui-use
  34. npm install
  35. npm run build
  36. npm link
  37. ```
  38. ## OpenAI Codex Plugin
  39. **Note:** You must install the CLI (see Installation section above) before using the plugin — the plugin only provides skill definitions, the CLI provides the actual PTY functionality.
  40. This repo includes a Codex plugin bundle at `plugins/tui-use` and a local repo marketplace at `.agents/plugins/marketplace.json`.
  41. ### Install from this repo
  42. #### Step 1: Open this repository in Codex
  43. Start Codex with this repository as the working directory, or restart Codex if it was already open while you cloned or updated the repo.
  44. #### Step 2: Open the plugin directory
  45. ```
  46. codex
  47. /plugins
  48. ```
  49. #### Step 3: Install the plugin
  50. Choose the `tui-use local plugins` marketplace, open `tui-use`, and select `Install plugin`.
  51. #### Step 4: Start a new thread
  52. Ask Codex to use `tui-use`, or explicitly invoke the installed plugin/skill from the prompt.
  53. ## Claude Code Plugin
  54. **Note:** You must install the CLI (see Installation section above) before using the plugin — the plugin only provides skill definitions, the CLI provides the actual PTY functionality.
  55. ### Install from self-hosted marketplace
  56. #### Step 1: Add the marketplace
  57. ```
  58. /plugin marketplace add onesuper/tui-use
  59. ```
  60. #### Step 2: Install the plugin
  61. ```
  62. /plugin install tui-use@tui-use
  63. ```
  64. #### Step 3: Reload plugins
  65. ```
  66. /reload-plugins
  67. ```
  68. **More agents coming soon...**
  69. ## How It Works
  70. tui-use sits directly on the PTY event stream — every byte the program outputs flows through a headless terminal emulator in real time.
  71. This is what makes `wait` possible:
  72. ```
  73. program outputs → PTY → xterm emulator → render event
  74. → debounce timer resets on each change
  75. → 100ms of silence → wait resolves ✓
  76. ```
  77. `wait --text <pattern>` goes further — it resolves the moment a known prompt appears, giving agents a semantic readiness signal rather than just a silence window.
  78. Behind the scenes, a daemon process manages PTY sessions so they persist across CLI calls.
  79. ## CLI Interface
  80. ### Core Commands
  81. ```
  82. tui-use start <cmd> # Start a program
  83. tui-use start --cwd <dir> <cmd> # Start in specific directory
  84. tui-use start --cwd <dir> "<cmd> -flags" # Quote the full command to pass flags (e.g. git rebase -i)
  85. tui-use start --label <name> <cmd> # Start with label
  86. tui-use start --cols <n> --rows <n> <cmd> # Custom terminal size (default: 120x30)
  87. tui-use use <session_id> # Switch to a session
  88. tui-use type <text> # Type text
  89. tui-use type "<text>\n" # Type with Enter
  90. tui-use type "<text>\t" # Type with Tab
  91. tui-use paste "<text>\n<text>\n" # Multi-line paste (each line + Enter)
  92. tui-use press <key> # Press a key
  93. tui-use snapshot # Get current screen
  94. tui-use snapshot --format json # JSON output
  95. tui-use scrollup <n> # Scroll up to older content
  96. tui-use scrolldown <n> # Scroll down to newer content
  97. tui-use find <pattern> # Search in screen (regex)
  98. tui-use wait # Wait for screen change (default timeout: 3000ms)
  99. tui-use wait <ms> # Custom timeout, e.g. wait 5000
  100. tui-use wait --text <pattern> # Wait until screen contains pattern
  101. tui-use wait --debounce <ms> # Idle time after last change before resolving (default: 100ms)
  102. tui-use wait --format json # JSON output
  103. tui-use list # List all sessions
  104. tui-use use <session_id> # Switch to a session
  105. tui-use info # Show session details
  106. tui-use rename <label> # Rename session
  107. tui-use kill # Kill current session
  108. tui-use daemon status # Check if daemon is running
  109. tui-use daemon stop # Stop the daemon
  110. tui-use daemon restart # Restart the daemon
  111. ```
  112. ## Limitations
  113. - **TUI color/style info is mostly lost** — `screen` contains plain text only; colors and most formatting are stripped. Selected items and active elements are captured in `highlights` via inverse-video detection. Window title and fullscreen mode are captured in `title` and `is_fullscreen`.
  114. ## Troubleshooting
  115. ### Automatic Rebuild Fails
  116. The installer automatically detects your platform and uses a prebuilt binary when available. If no compatible prebuild exists, it will automatically rebuild from source (requires build tools).
  117. **Build tools** (only needed if automatic rebuild fails):
  118. - macOS: `xcode-select --install`
  119. - Linux: `sudo apt-get install build-essential python3 g++`
  120. - Windows: Prebuilt binaries available (no build tools needed)
  121. ## Development
  122. ```bash
  123. git clone <repo_url>
  124. cd tui-use
  125. npm install
  126. npm run build
  127. npm link
  128. # Try it
  129. tui-use start python3 examples/ask.py
  130. tui-use wait
  131. tui-use type "Alice"
  132. tui-use press enter
  133. tui-use wait
  134. tui-use kill
  135. ```
  136. ### Integration Tests
  137. A Claude Code skill is included for running the full integration test suite.
  138. Run the following command in Claude Code:
  139. ```
  140. /tui-use-integration-test
  141. ```
  142. Claude will execute the test suite in order and then report `PASS / FAIL` for each, with actual screen output on any failure.
  143. ## License
  144. [MIT License](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.