Skillget

termscope

agent
Security Audit
Fail
Health Warn
  • License — License: MPL-2.0
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 6 GitHub stars
Code Fail
  • rm -rf — Recursive force deletion command in install.sh
Permissions Pass
  • Permissions — No dangerous permissions requested
Purpose
This tool is a headless terminal emulator that allows users to programmatically spawn, interact with, and capture the state of command-line interfaces. It is primarily designed for automating TUI testing, CI pipelines, and AI agent workflows.

Security Assessment
The overall security risk is Medium. While the tool itself does not request dangerous system permissions, the primary concern lies in its installation method. The recommended installation script is piped directly into the shell (`curl ... | sh`), and the automated scan flagged the presence of a recursive force deletion command (`rm -rf`) inside this script. Users should carefully inspect the install script or bypass it entirely by building the application from source. Once installed, the CLI naturally executes shell commands and interacts with the terminal as its core function, but it does not make unauthorized network requests or contain hardcoded secrets.

Quality Assessment
The code quality and maintenance appear solid. It uses a recognized open-source license (MPL-2.0), has a clear README, and is actively maintained, with its last push occurring today. However, the project has extremely low community visibility, currently sitting at only 6 GitHub stars. This means it has not undergone widespread peer review or community testing. Furthermore, because it is written in Zig, a newer programming language, finding community support or auditing the dependency tree might be more challenging for some developers compared to more established languages.

Verdict
Use with caution: While the active maintenance and clear purpose are positives, you should avoid the installation script due to flagged `rm -rf` usage and instead build from source.
SUMMARY

Headless terminal emulator CLI powered by libghostty-vt

README.md

termscope

Headless terminal emulator CLI powered by libghostty-vt.

Spawn any command in a real virtual terminal, interact with it programmatically, and capture the state — all from a single binary with zero runtime dependencies. Built for AI agents, CI pipelines, and TUI testing. Inspired by Playwright-style automation, but for the terminal.

Install

curl -fsSL https://raw.githubusercontent.com/mwunsch/termscope/main/install.sh | sh

Or build from source (requires Zig 0.15.x):

git clone https://github.com/mwunsch/termscope.git
cd termscope
zig build -Doptimize=ReleaseSafe

Quick Start

Snapshot a TUI

termscope snapshot -- htop
termscope snapshot --format json -- btop
termscope snapshot --format svg -o screenshot.svg -- my-tui

Interact then capture

termscope exec \
  --wait-for-text "Search:" \
  --type "hello" \
  --press RET \
  --wait-idle 200 \
  --snapshot \
  -- my-tui

Assert in CI

termscope exec --expect "Connection refused" -- my-app
# exit 0 if found, exit 1 if not

Drive from an agent (session mode)

termscope session -- vim test.txt

Reads JSON-line requests from stdin, writes JSON-line responses to stdout:

{"id":1,"method":"snapshot"}
{"id":1,"result":{"cols":80,"rows":24,"cursor":[0,0],"screen":"primary","title":"vim","text":"..."}}

{"id":2,"method":"type","params":{"text":"ihello world"}}
{"id":2,"result":{}}

{"id":3,"method":"press","params":{"key":"ESC"}}
{"id":3,"result":{}}

{"id":4,"method":"query"}
{"id":4,"result":{"cols":80,"rows":24,"cursor":[0,12],"cursor_style":"block","cursor_visible":true,"title":"vim","alt_screen":true}}

{"id":5,"method":"close"}
{"id":5,"result":{"exit_code":0}}

Key Notation

Emacs-style, the established standard:

Notation Meaning
C-c Ctrl+C
M-x Alt+X
RET Enter
TAB Tab
ESC Escape
SPC Space
DEL Backspace
<up> <down> <left> <right> Arrow keys
<f1> … <f12> Function keys
C-x C-s Key sequence

Output Formats

Format Use
text (default) Numbered lines, optimized for LLMs
spans Text + per-line style runs
json Structured JSON
html Styled <pre> with <span> elements
svg Visual screenshot

Session Protocol

Method Params Response
snapshot format? Snapshot data
type text {}
press key {}
wait_for_text pattern, timeout? {found, row, col}
wait_for_idle duration? {}
wait_for_cursor row, col, timeout? {}
query — Terminal state
resize cols, rows {}
close — {exit_code}

Errors: {"id":N,"error":{"code":"...","message":"..."}}. The session continues on errors.

Agent Skill

npx skills add mwunsch/termscope

Reviews (0)

No results found