Skip to content
Back to search

terminal-control

Control, inspect, test, and capture real terminal applications for agents and TUI review.

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/anomalyco/terminal-control with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/anomalyco/terminal-control'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/anomalyco--terminal-control/badge.svg)](/listings/anomalyco--terminal-control)

HTML

<a href="/listings/anomalyco--terminal-control"><img src="/api/listings/anomalyco--terminal-control/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

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

Source builds require Rust 1.93 or newer, Zig 0.15.2, Git, and network access while the pinned Ghostty terminal core is built. Video export also requires `ffmpeg`.

cargo install --locked terminal-control
termctrl --help

Or install the current repository head:

cargo install --locked --git https://github.com/anomalyco/terminal-control terminal-control

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.

README.md · README · 271 lines

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

  1. # Terminal Control
  2. Control, inspect, test, and capture real terminal applications for agents and TUI review.
  3. [![crates.io](https://img.shields.io/crates/v/terminal-control.svg)](https://crates.io/crates/terminal-control)
  4. [![CI](https://github.com/anomalyco/terminal-control/actions/workflows/ci.yml/badge.svg)](https://github.com/anomalyco/terminal-control/actions/workflows/ci.yml)
  5. ![OpenCode answering a playful terminal request](https://raw.githubusercontent.com/anomalyco/terminal-control/main/docs/screenshots/opencode-haikus.png)
  6. Saved from one live OpenCode session using `start`, `send`, and `save`.
  7. ## Install
  8. Source builds require Rust 1.93 or newer, Zig 0.15.2, Git, and network access while the pinned
  9. Ghostty terminal core is built. Video export also requires `ffmpeg`.
  10. ```bash
  11. cargo install --locked terminal-control
  12. termctrl --help
  13. ```
  14. Or install the current repository head:
  15. ```bash
  16. cargo install --locked --git https://github.com/anomalyco/terminal-control terminal-control
  17. ```
  18. ## Set Up Your Agent
  19. Terminal Control is built for agents first. Install the skill so your coding agent knows the workflow:
  20. ```bash
  21. npx skills add anomalyco/terminal-control --skill terminal-control
  22. ```
  23. Or expose sessions as structured MCP tools instead of shell commands (stdio server):
  24. ```bash
  25. termctrl mcp
  26. ```
  27. MCP screen reads and interactions return the current frame immediately. Agents can opt into
  28. quiet-output settling with `settleMs` and `deadlineMs` when a specific transition requires it.
  29. `list_sessions` returns running sessions by default and accepts `state`, `command`, and `cwd`
  30. filters for bounded server-side discovery.
  31. | MCP task | Tools |
  32. | --- | --- |
  33. | Discover | `list_sessions`, `get_session_status` |
  34. | Observe and drive | `get_screen`, `save_screen`, `send_input`, `send_mouse`, `interact`, `resize_session` |
  35. | End processes | `stop_session` |
  36. Then ask for terminal work in ordinary language:
  37. ```text
  38. Use terminal-control to open my TUI, press through the setup flow, and save a screenshot of the final screen.
  39. ```
  40. ```text
  41. Record yourself using the terminal app, mark the important moments, and export a short MP4 demo.
  42. ```
  43. The skill teaches the safe workflow: start named sessions, wait for visible text, send exact input, inspect screens, save artifacts, record timelines, and stop sessions when finished.
  44. ## Read A Screen
  45. `show` runs a program in a PTY and prints its settled visible screen to stdout. No files are created.
  46. ```bash
  47. termctrl show --cols 100 --rows 32 -- my-terminal-app
  48. ```
  49. Wait for the app to mount and interact before reading:
  50. ```bash
  51. termctrl show --cols 100 --rows 32 --wait-for "Commands" \
  52. -s ctrl-p text:model enter -- my-terminal-app
  53. ```
  54. Other stdout representations are explicit:
  55. ```bash
  56. termctrl show --format json -- my-terminal-app
  57. termctrl show --format svg -- my-terminal-app
  58. ```
  59. ## Save Evidence
  60. `save` writes only the artifact formats you request:
  61. ```bash
  62. termctrl save --format png --out captures/home.png -- my-terminal-app
  63. termctrl save --format png --format txt --out captures/model -- my-terminal-app
  64. ```
  65. The second command writes `captures/model.png` and `captures/model.txt`. Raw ANSI artifacts can contain sensitive terminal data and require explicit `--format ansi`.
  66. ## Drive A Live Session
  67. Use a named session when several interactions target the same running application:
  68. ```bash
  69. termctrl start demo --host opentui --cols 112 --rows 34 -- my-terminal-app
  70. termctrl wait demo "Ready"
  71. termctrl send demo text:help enter
  72. termctrl show demo
  73. termctrl show demo --format semantic
  74. termctrl save demo --format png --out captures/help.png
  75. termctrl stop demo
  76. ```
  77. - `send` accepts `text:<value>`, named keys (`enter`, `escape`, arrows, `tab`, `shift-tab`, `backspace`, `delete`, `home`, `end`, `page-up`, `page-down`), and `ctrl-a` through `ctrl-z`. Pipe exact bytes with `--stdin`.
  78. - `mouse demo move 12 4` hovers at zero-based column 12, row 4; `mouse demo click 12 4` clicks. Use `down`, `move`, then `up` to drag; `--button right`, `--shift`, `--alt`, and `--ctrl` are supported. The app must enable mouse reporting (hover needs any-event tracking).
  79. - `show NAME` reads immediately; `wait` returns as soon as text is visible. Its five-second default is a maximum, not a fixed delay. Use it instead of sleeping.
  80. - `status` reports running/exited state, command, cwd, viewport, and recording path. `list` shows running sessions; use `--state`, `--command`, or `--cwd` to filter discovery, and `--all` to include every retained or unavailable entry.
  81. - `prune --dry-run` previews retained exited sessions and stale sockets; `prune` removes them without deleting recording artifacts.
  82. - `resize demo --cols 132 --rows 38` tests responsive layouts.
  83. - `restart demo` relaunches with the stored command, cwd, viewport, and recording settings.
  84. - An exited session keeps its final screen for `show` until stopped.
  85. For fast automation, batch a known `send` → `wait` → `show` transition in one shell call, or use
  86. MCP `interact` with `waitFor`. Leave typing unpaced unless the demo needs it; reserve PNG saves
  87. for visual checks and export video after the interactions.
  88. OpenTUI applications such as OpenCode need the opt-in host handshake:
  89. ```bash
  90. termctrl start demo --host opentui --cols 112 --rows 34 -- opencode
  91. termctrl wait demo "/connect"
  92. ```
  93. For normal-screen tools and log-like processes, read retained scrollback with `logs`:
  94. ```bash
  95. termctrl logs demo
  96. termctrl logs demo --ansi > captures/demo-output.ansi
  97. ```
  98. Full-screen alternate-screen TUIs do not produce useful logs; read their visible screen with `show`.
  99. ## Semantic UI Snapshots
  100. Terminal Control gives applications launched with `--host opentui` a private
  101. `TERMCTRL_SEMANTIC_SOCKET`. Cooperating applications can provide structured UI semantics without
  102. changing terminal output:
  103. ```bash
  104. termctrl start demo --host opentui -- my-tui
  105. termctrl show demo --format semantic
  106. ```
  107. Applications without a semantic provider return an empty snapshot. See
  108. [docs/semantic-protocol.md](docs/semantic-protocol.md) for the protocol and the OpenTUI adapter.
  109. ## Share A Session With A Human
  110. `run` keeps the application visible and interactive in your current terminal pane while agents control the same PTY through the named session commands:
  111. ```bash
  112. termctrl run -- nvim
  113. termctrl run editor --cwd ~/src/project -- nvim
  114. ```
  115. Without `NAME`, the session name is the executable basename (`nvim` above); a name collision is an error, never a suffixed name. No tmux or multiplexer involved.
  116. ## Record And Export Video
  117. Record a timeline, mark moments while it runs, then export an edited MP4:
  118. ```bash
  119. termctrl start demo --record captures/demo.termctrl --host opentui -- opencode
  120. termctrl wait demo "Ask anything"
  121. termctrl mark demo before-prompt
  122. termctrl send demo --pace-ms 35 'text:Write a terminal haiku. End with DONE.' enter
  123. termctrl wait demo "DONE" --timeout 60000
  124. termctrl mark demo after-answer
  125. termctrl stop demo
  126. termctrl markers captures/demo.termctrl
  127. termctrl show --recording captures/demo.termctrl --at-marker after-answer
  128. termctrl video captures/demo.termctrl --edit captures/demo.json --footer --out captures/demo.mp4
  129. ```
  130. An edit plan selects marker ranges with per-clip speed, captions, and optional end holds:
  131. ```json
  132. {
  133. "clips": [
  134. {
  135. "from": "before-prompt",
  136. "to": "after-answer",
  137. "speed": 4,
  138. "caption": "The agent answers inside the live terminal UI"
  139. }
  140. ]
  141. }
  142. ```
  143. Without `--edit`, export preserves recorded timing. `--footer` renders captions, timecode, and branding in a bottom bar. `--tail-ms 0` removes the default one-second final hold. Keep speeds low enough for text to stay readable.
  144. ### Show Mouse Interactions
  145. Mouse visualization is opt-in at export, independent of the terminal's text cursor:
  146. ```bash
  147. termctrl start pointer-demo --record captures/pointer.termctrl -- my-mouse-enabled-tui
  148. termctrl wait pointer-demo "Ready"
  149. termctrl mouse pointer-demo move 12 4
  150. termctrl mouse pointer-demo click 12 4
  151. termctrl stop pointer-demo
  152. termctrl video captures/pointer.termctrl --pointer-overlay --out captures/pointer.mp4
  153. ```
  154. The overlay uses a neutral outlined arrow, smooth 220ms travel arriving at the input instant,
  155. subtle press compression, and short fades. Pointer exports default to 60 fps (otherwise 20);
  156. `--fps` overrides either default. `--pointer-reduced-motion` keeps fades without travel or scaling.
  157. Edits preserve alignment through cuts, speed changes, holds, and resizes. No animation changes
  158. the real input or adds delays. Only typed `mouse` operations provide pointer evidence; raw bytes
  159. and human input forwarded by `run` are not inferred. `show` and `save` remain unadorned terminal state.
  160. New recordings use format v2; current readers also accept v1. Older binaries must be updated to
  161. read v2 recordings. Restart older named sessions before using the new mouse command.
  162. Recordings are JSON Lines files containing terminal output and typed input; they can include prompts or secrets. Treat them as sensitive.
  163. ## Pipes And ANSI Streams
  164. Capture piped command output, or render an existing ANSI/VT stream without launching a process:
  165. ```bash
  166. termctrl save --pipe --format png --cols 100 --rows 16 --out captures/log -- my-command
  167. printf '\033[44;97m terminal output \033[0m\n' | termctrl show --input -
  168. ```
  169. One-off `show` and `save` own disposable processes: after the read or save, the launched process tree is terminated. Use `start` for long-running applications.
  170. ## TypeScript Testing
  171. `@kitlangton/terminal-control` on npm wraps the driver as typed test sessions with bundled native binaries — no Rust toolchain needed:
  172. ```bash
  173. bun add -d @kitlangton/terminal-control vitest
  174. ```
  175. ```ts
  176. import { TerminalControl } from "@kitlangton/terminal-control"
  177. await using terminal = await TerminalControl.make()
  178. await using session = await terminal.launch({ command: ["my-tui"] })
  179. await session.screen.waitForText("Ready")
  180. await session.keyboard.press("Enter")
  181. expect(await session.screen.text()).toMatchSnapshot()
  182. ```
  183. See [docs/typescript-client.md](docs/typescript-client.md) for artifacts, recordings, Vitest matchers, and configuration.
  184. ## More Documentation
  185. - [docs/rust-library.md](docs/rust-library.md) — embed the shot engine and sessions in Rust, plus versioned JSON schemas.
  186. - [docs/driver-protocol.md](docs/driver-protocol.md) — the `termctrl driver` JSON Lines protocol for external tooling.
  187. - [docs/semantic-protocol.md](docs/semantic-protocol.md) — the application semantic socket handshake and snapshot contract.
  188. - [docs/typescript-client.md](docs/typescript-client.md) — the npm test client in full.
  189. - [docs/releasing.md](docs/releasing.md) — aligned crates.io, npm, and GitHub release process.
  190. ## Notes
  191. - Persistent sessions use owner-only local Unix sockets and are supported on macOS and Linux.
  192. - `--host opentui` answers startup probes needed by current OpenTUI applications.
  193. - Terminal state and reflow use the statically linked Ghostty terminal core; renderers export PNG, SVG, JSON, text, and raw ANSI artifacts.
  194. - Run `termctrl <command> --help` for dimensions, timing, color, rendering, and output options.

Ratings and comments

Sign in to rate this skill.

Sign in

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