Skip to content
Back to search

tui-use

MarketplaceWorks with Claude CodeGitHub

Let any AI agent drive interactive terminal programs: vim, git rebase -i, npm init, ssh, REPLs, htop.

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

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

HTML

<a href="/listings/pavanmanishd--tui-use"><img src="/api/listings/pavanmanishd--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.

tui-use needs Node.js 22 or later on macOS or Linux. On Windows, use WSL. Prebuilt terminal binaries ship for x64 and arm64, so nothing is compiled during install.

Claude Code

claude mcp add tui-use -- npx -y @pavanmanishd/tui-use@1.0.0 mcp

The plugin adds the same server plus a skill that tells Claude when to use tui-use instead of the shell:

/plugin install tui-use --marketplace pavanmanishd/tui-use

Codex

`~/.codex/config.toml`:

[mcp_servers.tui-use]
command = "npx"
args = ["-y", "@pavanmanishd/tui-use@1.0.0", "mcp"]

Cursor

`~/.cursor/mcp.json`:

{
  "mcpServers": {
    "tui-use": { "command": "npx", "args": ["-y", "@pavanmanishd/tui-use@1.0.0", "mcp"] }
  }
}

Gemini CLI

`~/.gemini/settings.json`:

{
  "mcpServers": {
    "tui-use": { "command": "npx", "args": ["-y", "@pavanmanishd/tui-use@1.0.0", "mcp"] }
  }
}

OpenCode

`opencode.json`:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tui-use": {
      "type": "local",
      "command": ["npx", "-y", "@pavanmanishd/tui-use@1.0.0", "mcp"],
      "enabled": true
    }
  }
}

Claude Desktop

`claude_desktop_config.json`:

{
  "mcpServers": {
    "tui-use": { "command": "npx", "args": ["-y", "@pavanmanishd/tui-use@1.0.0", "mcp"] }
  }
}

Any agent with a shell

npm install -g @pavanmanishd/tui-use@1.0.0
tui-use start "npm init" --name init
tui-use send init --text "my-app" --key enter

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 · 11 lines
  1. {
  2. "name": "tui-use",
  3. "owner": { "name": "pavanmanishd" },
  4. "plugins": [
  5. {
  6. "name": "tui-use",
  7. "source": "./plugins/claude-code",
  8. "description": "Drive interactive terminal programs (vim, git rebase -i, ssh, REPLs, htop, installers) from Claude Code."
  9. }
  10. ]
  11. }
README.md · README · 268 lines · 1 finding marked
  1. # tui-use
  2. Let any AI agent drive interactive terminal programs: vim, `git rebase -i`, `npm init`, ssh, REPLs, debuggers, htop, installers and database shells.
  3. Coding agents run shell commands one at a time, without a terminal. A command that waits for input hangs until the tool times out, a full-screen program prints escape codes, and a REPL forgets everything between turns. tui-use gives the agent a real terminal that it can read and type into across as many turns as it needs.
  4. ```
  5. claude mcp add tui-use -- npx -y @pavanmanishd/tui-use@1.0.0 mcp
  6. ```
  7. ![Claude Code squashing three commits with git rebase -i through tui-use](assets/demo.gif)
  8. Claude Code (Opus) squashing three commits with `git rebase -i` through tui-use. It rewrites the todo list with `:2,3s/^pick/squash/`, replaces the combined commit message and saves. This is the terminal the agent drove, as tui-use recorded it.
  9. ## What the agent sees
  10. Every call that changes something returns the screen as numbered text. The cursor is shown as `[x]`, and highlighted text, such as the selected item in a menu, is wrapped in `«…»`.
  11. ```
  12. session s1 · git rebase -i HEAD~3 · 120x40 · cursor 2:1 · alt · running · idle 310ms
  13. ───
  14. 1│pick 3f2a1c0 Add parser
  15. 2│[s]quash 9b4e7d2 Fix parser edge case
  16. 3│squash 1d8c5aa Rename parser module
  17. 4│
  18. 5│# Rebase 7c0e2b1..1d8c5aa onto 7c0e2b1 (3 commands)
  19. …
  20. 40│"~/repo/.git/rebase-merge/git-rebase-todo" 27L, 1189C
  21. ```
  22. After the first screen, `tui_send` returns only the rows that changed:
  23. ```
  24. session s1 · python3 · 120x40 · cursor 6:5 · normal · running · idle 312ms
  25. ───
  26. 4│>>> sum(x) * 2
  27. 5│42
  28. 6│>>> [ ]
  29. (3 of 40 rows changed)
  30. ```
  31. ## Install
  32. tui-use needs Node.js 22 or later on macOS or Linux. On Windows, use WSL. Prebuilt terminal binaries ship for x64 and arm64, so nothing is compiled during install.
  33. ### Claude Code
  34. ```
  35. claude mcp add tui-use -- npx -y @pavanmanishd/tui-use@1.0.0 mcp
  36. ```
  37. The plugin adds the same server plus a skill that tells Claude when to use tui-use instead of the shell:
  38. ```
  39. /plugin install tui-use --marketplace pavanmanishd/tui-use
  40. ```
  41. ### Codex
  42. `~/.codex/config.toml`:
  43. ```toml
  44. [mcp_servers.tui-use]
  45. command = "npx"
  46. args = ["-y", "@pavanmanishd/tui-use@1.0.0", "mcp"]
  47. ```
  48. ### Cursor
  49. `~/.cursor/mcp.json`:
  50. ```json
  51. {
  52. "mcpServers": {
  53. "tui-use": { "command": "npx", "args": ["-y", "@pavanmanishd/tui-use@1.0.0", "mcp"] }
  54. }
  55. }
  56. ```
  57. ### Gemini CLI
  58. `~/.gemini/settings.json`:
  59. ```json
  60. {
  61. "mcpServers": {
  62. "tui-use": { "command": "npx", "args": ["-y", "@pavanmanishd/tui-use@1.0.0", "mcp"] }
  63. }
  64. }
  65. ```
  66. ### OpenCode
  67. `opencode.json`:
  68. ```json
  69. {
  70. "$schema": "https://opencode.ai/config.json",
  71. "mcp": {
  72. "tui-use": {
  73. "type": "local",
  74. "command": ["npx", "-y", "@pavanmanishd/tui-use@1.0.0", "mcp"],
  75. "enabled": true
  76. }
  77. }
  78. }
  79. ```
  80. ### Claude Desktop
  81. `claude_desktop_config.json`:
  82. ```json
  83. {
  84. "mcpServers": {
  85. "tui-use": { "command": "npx", "args": ["-y", "@pavanmanishd/tui-use@1.0.0", "mcp"] }
  86. }
  87. }
  88. ```
  89. ### Any agent with a shell
  90. ```
  91. npm install -g @pavanmanishd/tui-use@1.0.0
  92. tui-use start "npm init" --name init
  93. tui-use send init --text "my-app" --key enter
  94. ```
  95. ## MCP tools
  96. | Tool | What it does |
  97. |---|---|
  98. | `tui_start` | Starts a program and returns its first screen. Takes `command`, `cwd`, `env`, `cols`, `rows`, `name` and `wait`. |
  99. | `tui_send` | Types `text`, a `secret_env` value and `keys` (or an ordered `input` list), waits, and returns the new screen as a diff by default. `paste: true` sends the text as a bracketed paste. |
  100. | `tui_snapshot` | Returns the screen without sending input. `styles: "none"` drops the `«…»` marks. |
  101. | `tui_wait` | Waits without sending input, for builds and installs. |
  102. | `tui_scrollback` | Reads output that scrolled off the screen, by line range (such as `[-50, -1]`) or by `search`. |
  103. | `tui_manage` | Lists sessions, kills one (SIGTERM, then SIGKILL after 2 s), resizes one, or returns the path of its recording. |
  104. Saving and quitting vim in one call:
  105. ```json
  106. { "session": "s1", "input": [{ "key": "esc" }, { "text": ":wq" }, { "key": "enter" }] }
  107. ```
  108. Key names are `enter`, `tab`, `esc`, `backspace`, `delete`, `up`, `down`, `left`, `right`, `home`, `end`, `pageup`, `pagedown`, `space`, `f1` to `f12` and any single character, optionally prefixed with `ctrl+`, `alt+` or `shift+` (for example `ctrl+c` or `shift+tab`). An unknown key name is an error, never typed as text.
  109. ### Waiting
  110. By default, a call returns once the program has printed something and then stayed quiet for 300 ms with an unchanged screen, or after 5 seconds. If the program is still drawing, such as a spinner or a slow install, the response ends with a note saying so. For slow programs, pass a wait object:
  111. | Field | Returns when |
  112. |---|---|
  113. | `text` | this substring is on screen |
  114. | `regex` | this pattern matches the screen |
  115. | `gone` | this substring has left the screen |
  116. | `idle_ms` | there has been no output for this long |
  117. | `exit` | the program exits |
  118. | `timeout_ms` | the time limit is reached (default 5000, max 600000) |
  119. Conditions combine with OR, and the response names the one that fired.
  120. ## CLI
  121. The CLI offers the same operations to agents that only have a shell. Sessions live in a background daemon, so they survive between shell calls.
  122. ```
  123. tui-use start "npm init" --name init
  124. tui-use send init --text "my-app" --key enter
  125. tui-use send init --input esc ":wq" enter
  126. tui-use snapshot init --diff
  127. tui-use wait init --text "Is this OK?" --timeout 10000
  128. tui-use scrollback init --search error
  129. tui-use list
  130. tui-use kill init
  131. tui-use attach init
  132. tui-use replay ~/.local/share/tui-use/recordings/20261121-101500-s1.cast
  133. ```
  134. `--json` prints the raw response. Exit codes are 0 for success, 1 for a request error, 2 for a usage error and 3 when a wait times out. Quote commands that have their own flags, as in `tui-use start "git rebase -i HEAD~3"`.
  135. ## Watching or taking over
  136. `tui-use attach <session>` mirrors a session in your terminal while the agent works. Anything you type goes to the program as well, and the agent's screen header shows `human attached (rw)` while you are attached. Press `ctrl+]` to detach; the session keeps running.
  137. ## Configuration
  138. `~/.config/tui-use/config.json`, with every key optional:
  139. ```json
  140. {
  141. "maxSessions": 8,
  142. "idleTimeoutMinutes": 30,
  143. "scrollbackLines": 10000,
  144. "recordings": true,
  145. "recordingRetentionDays": 7,
  146. "deny": ["^rm -rf /", "^sudo "]
  147. }
  148. ```
  149. `deny` is a list of regular expressions. A command that matches one is refused before anything runs. An unknown key stops the daemon from starting, so a typo can't be silently ignored.
  150. ## Security
  151. - tui-use runs commands as you, with the environment of the agent that asked. It adds no privilege that the agent's shell tool didn't already have, and it is not a sandbox.
  152. - One daemon per user listens on a unix socket in a directory only you can read. Clients refuse to connect if that directory is a symlink, belongs to another user, or is readable by other users.
  153. - `secret_env` names an environment variable of the tui-use process, for example one set in your MCP config. Its value is typed into the program and replaced with `***` wherever it would appear in a screen, scrollback, search result or recording. List such variables in `TUI_USE_SECRETS` (for example `TUI_USE_SECRETS=SSH_PASS,DB_PASS`) so they are not copied into the environment of the programs tui-use starts.
  154. - Sessions an MCP client starts are killed when that client disconnects. Other MCP clients can read them but cannot type into them.
  155. - Every session is recorded as an asciinema v2 file under `~/.local/share/tui-use/recordings`. Recordings never contain input and are deleted after 7 days.
  156. ## Known limitations
  157. - Highlight marks compare each cell's background with the most common background on screen. When two buttons have different colours, as in `gum confirm`, both are marked and the snapshot doesn't show which one is active. Use the program's shortcut key, such as `y` or `n`, instead.
  158. - Settle detection can't tell a spinner from real progress. For slow programs, pass a `wait` with `text`, `regex` or `gone`.
  159. - Redaction matches the exact secret. A program that prints it in altered form, such as masked or split by escape codes, is not caught.
  160. - There is no mouse input yet, and no native Windows support (WSL works).
  161. ## TUI-Bench
  162. TUI-Bench is a set of 40 interactive tasks covering editors, git, prompts, REPLs, full-screen apps, ssh and pickers. Each task runs in a Docker container and is scored by a scripted checker. The runner drives real agent CLIs (Claude Code, Gemini CLI and OpenCode) twice per task, once with only the shell tool and once with tui-use added, and reports success rate, turns, tokens and wall time. See [bench/README.md](bench/README.md) to reproduce it.
  163. ### Results
  164. Claude Code 2.1.329 on all 40 tasks, with 3 repeats per cell (480 runs):
  165. | Model | Shell only | With tui-use | Median turns (shell / tui-use) | Median tokens (shell / tui-use) | Median wall time (shell / tui-use) |
  166. |---|---|---|---|---|---|
  167. | Claude Opus 5.5 | 99% | 100% | 4 / 8 | 84k / 151k | 17 s / 20 s |
  168. | Claude Haiku 5.5 | 99% | 100% | 4 / 5 | 90k / 114k | 15 s / 14 s |
  169. - With only a shell, Claude Code still finished almost every task. When a program needed a terminal (htop, ssh password prompts, whiptail, vimdiff), it usually wrote its own Python `pty.fork()` driver on the spot. Both failures were `htop-kill` runs without tui-use.
  170. - With tui-use available, the agent chose it in 129 of 240 runs (Opus in 80 of 120, Haiku in 49 of 120), mostly for editors, prompts, pickers, full-screen apps and ssh. Those runs took more turns and tokens than the shell runs, because the agent reads the screen between steps instead of scripting blind.
  171. - For a frontier model with Python available, tui-use doesn't decide whether an interactive task gets done. It replaces improvised pty scripts with one tool the agent can see and type into, and the agent uses it when it is there.
  172. OpenCode with DeepSeek V4.1 Flash, run through T3 Code on six interaction-heavy tasks with one repeat, passed all 12 runs in both conditions ([details](bench/results/delegated-opencode-2026-11-22/report.md)). Gemini CLI and the open-weight models in [bench/runner/matrix.json](bench/runner/matrix.json) have not been run yet; they need `GEMINI_API_KEY` and `OPENROUTER_API_KEY`.
  173. Two caveats apply. The Claude runs used a Claude subscription token, so Claude Code inside the containers also loaded that account's organization policy, equally in both conditions. And a single repeat for the OpenCode batch is too few to separate small differences. The raw results are in [bench/results/claude-full-2026-11-22](bench/results/claude-full-2026-11-22).
  174. ## Compared with other tools
  175. Based on each project's README in November 2026.
  176. | | tui-use | terminal-use (`tu`) | mcp-interactive-terminal | pexpect-mcp | tmux MCP servers |
  177. |---|---|---|---|---|---|
  178. | MCP server | yes | no, CLI only | yes | yes | yes |
  179. | CLI for agents with only a shell | yes | yes | no | no | no |
  180. | Terminal emulator | xterm.js | alacritty | xterm.js | none (pexpect) | tmux |
  181. | Input, wait and new screen in one call | yes | no, separate commands | yes | not documented | varies |
  182. | Diff of changed rows | yes | not documented | not documented | no | not documented |
  183. | Selected items marked in text | yes | not documented | not documented | no | not documented |
  184. | Secrets kept out of output | yes | not documented | not documented | not documented | not documented |
  185. | Human can watch live | yes, and type | yes, watch only | not documented | not documented | yes (tmux attach) |
  186. | Mouse input | not yet | yes | not documented | not documented | not documented |
  187. | Recordings | asciinema | not documented | not documented | not documented | not documented |
  188. | Benchmark | TUI-Bench | no | no | no | no |
  189. ## Development
  190. ```
  191. npm ci
  192. npm run lint && npm run typecheck
  193. npm test # unit tests
  194. npm run test:integration # real programs in real terminals; the ssh test needs Docker
  195. ```
  196. ## License
  197. Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

Ratings and comments

Sign in to rate this skill.

Sign in

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