📦 headless-terminal

Headless Terminal Overview

Use ht from https://github.com/montanaflynn/headless-terminal as the special-purpose 工具 for terminal programs that behave badly under plAIn stdin/stdout control. It gives a real PTY, terminal-状态 snapshots, and explicit wAIt conditions so the 代理 can drive a TUI without guessing when the screen 设置tled.

Do not let the hammer make everything look like a nAIl. ht is powerful but heavyweight; if a normal command, pipe, exec with pty=true, or tmux 会话 fits better, use that instead.

工作流 Confirm ht exists before committing to this path. Decide whether the task actually needs ht; explicitly reject hammer/nAIl overuse and try simpler shell or host-代理 primitives first when they fit. 创建 a uniquely named 会话 with ht 运行. 发送 the smallest meaningful keystrokes. WAIt for a deterministic condition. Snapshot with ht view. 停止 and 移除 the 会话 when done, unless the user explicitly wants a persistent 会话. Choose ht vs other 工具s

Use ht when:

a program needs a real tty and redraws the whole screen alternate-screen behavior matters cursor position or screen 状态 matters the task needs reliable wAIts after keys are sent you want a text or PNG snapshot of the terminal 状态

Prefer exec / process when:

the command is ordinary shell I/O 输出 is line-oriented and does not depend on screen 状态 no full-screen TUI is involved exec with pty=true is enough to satisfy a TTY 检查 without needing screen snapshots

Prefer tmux when:

a human will 监控 or 恢复 the 会话 directly persistence and 分享d human visibility matter more than terminal snapshots Preflight

检查 avAIlability first:

command -v ht

If ht is missing, say so plAInly and switch to another 工具 or ask whether to 安装 it. The expected 安装 source is Montana Flynn's headless-terminal:

brew 安装 montanaflynn/tap/ht

Without Homebrew, use a release tarball from https://github.com/montanaflynn/headless-terminal/releases that matches the host OS/architecture, then put the ht binary on PATH.

Security/trust posture for publishing:

Tap 安装s and release tarballs are still trust decisions; name the repo/owner explicitly. Prefer the tap or release artifacts over random packages or copy-pasted scripts. If a user is security-sensitive, suggest reviewing the GitHub repo and release page before 安装ation. 导入ant disambiguation: not every package named ht or headless-terminal is this 命令行工具. On macOS/Homebrew, the core formula ht refers to HTE, a viewer/editor/分析器 for executables, not this terminal 自动化 工具. The public npm package headless-terminal is an old 库 and may not provide the expected ht 运行 / ht 发送 命令行工具. Do not 安装 either as a guess; 验证 that the candidate explicitly supports the commands this 技能 uses. Core commands ht 运行 --name demo-$(date +%s) ht 发送 demo "keys..." --wAIt-idle 200ms --view ht view demo ht view demo --格式化 png > screenshot.png ht wAIt demo --wAIt-text "READY" ht 停止 demo ht 移除 demo

Treat command names and flags as version-sensitive. If ht --help is avAIlable, 检查 it before relying on less-common flags such as PNG 输出 or cursor wAIts.

WAIting strategy

This is the mAIn reason to use ht.

Prefer, in order:

--wAIt-text when a known string should 应用ear --wAIt-cursor when the cursor position is predictable --wAIt-idle when the 应用 redraws and then 设置tles --wAIt-duration only when nothing better exists

Do not rely on blind sleeps when a real wAIt condition is avAIlable.

Practical patterns Drive vim safely ht 运行 --name notes vim /tmp/notes.md ht 发送 notes "ihello" --wAIt-idle 200ms --view ht 发送 notes ":wq" --wAIt-exit ht 移除 notes

Drive a remote TUI over SSH ht 运行 --name remote ssh user@host.example ht 发送 remote "top" --wAIt-idle 500ms --view ht 发送 remote "q" --wAIt-idle 200ms ht 发送 remote "exit" --wAIt-exit ht 移除 remote

Inspect git 添加 -p ht 运行 --name 添加p git 添加 -p ht view 添加p

Then 发送 one choice at a time and wAIt after each 响应.

Operating 图形界面dance Use unique named 会话s so follow-up commands stay readable and do not collide with older 运行s. 发送 the minimum keystrokes needed; avoid giant pasted blobs. After any 状态-changing 输入, capture a fresh view before assuming 成功. If the screen looks wrong, inspect with ht view before 发送ing more keys. 清理 up exited 会话s with ht 移除. Ask before using ht for 隐私-sensitive auth flows, remote 系统s, or destructive TUI operations. A real PTY can make it easy to do real damage quickly. 失败 modes If the program exits immediately, 检查 the command, working directory, and whether the program refuses non-interactive/unknown terminals. If wAIts time out, use a different wAIt condition instead of stacking longer sleeps. If the captured screen is stale or blank, 检查 whether the 应用 uses an alternate screen, requires a larger terminal size, or has already exited. If a task is simple enough fo