Headless Terminal

intent

use ht from montanaflynn/headless-terminal when you need a real PTY to drive full-screen terminal programs that break under plain stdin/stdout. this skill matters when redraw behavior, alternate-screen handling, cursor state, or deterministic waits are critical to success. examples: vim, top, htop, git add -p, SSH-driven TUIs, interactive installers, auth prompts, or REPLs. do not use this for ordinary shell commands, line-oriented output, or human-monitored persistent sessions (use tmux for that instead).

inputs

tool availability:

• ht binary on PATH from montanaflynn/headless-terminal (verify with command -v ht)
• standard install: brew install montanaflynn/tap/ht on macOS or download release tarball from https://github.com/montanaflynn/headless-terminal/releases
• caveat: "ht" on Homebrew refers to HTE (executable analyzer), not this terminal CLI; npm package headless-terminal is an old library; always verify the candidate supports ht run / ht send commands

host environment:

• functional PTY kernel support (all modern Linux, macOS, BSD)
• target command or program to drive (vim, SSH session, interactive tool, etc.)
• working directory context if the command needs it

external connections:

• none required (this is a local CLI tool)
• if driving remote TUI over SSH, you need SSH access to the remote host with appropriate credentials/keys

context:

• session name prefix (recommend unique string like demo-$(date +%s) to avoid collisions)
• knowledge of the program's behavior, prompts, wait conditions, and key sequences

procedure

1. preflight check: run command -v ht to confirm the binary is on PATH. if missing, stop and report that ht is not installed; offer to install from the tap or release tarball (do not guess or install random packages named "ht" or "headless-terminal"). if security is a concern, suggest the user review the GitHub repo and release page first.

2. evaluate tool choice: decide whether ht is actually needed. if the task is ordinary shell I/O, line-oriented output without screen state dependency, or no full-screen TUI is involved, use exec with pty=true or plain shell instead. if a human will monitor or resume the session, prefer tmux. stop here if a simpler tool fits.

3. create session: run ht run --name <unique-name> <command...> to spawn the target program in a new named session. example: ht run --name notes vim /tmp/notes.md. capture the session name for all follow-up commands.

4. send keystrokes: use ht send <session-name> "<keys>" --wait-<condition> --view to send input and wait. use the smallest meaningful keystroke sequence; avoid giant pasted blobs. prefer wait conditions in this order: --wait-text "string" (known string appears), --wait-cursor <line>,<col> (cursor lands at predictable position), --wait-idle <duration> (app redraws then settles, e.g. 200ms), --wait-duration <duration> (only as last resort). always include --view to capture the screen after input.

5. inspect state: after each keystroke batch, read the captured view to confirm the screen settled and the program responded correctly. if the screen looks wrong, use ht view <session-name> to get a fresh snapshot before sending more keys. if the screen is stale or blank, check whether the app uses alternate screen mode, requires a larger terminal size, or has already exited.

6. stop and clean up: when the task is done, send exit sequence (e.g., :wq<CR> for vim or exit<CR> for SSH) with --wait-exit to let the program shut down. then run ht remove <session-name> to tear down the session. if the user explicitly requests a persistent session, skip cleanup and hand off the session name.

decision points

ht vs simpler tools:

• if the task is ordinary shell I/O and output is line-oriented (does not depend on screen state), use exec or process with pty=true instead of ht.
• if the task requires a human to monitor or resume the session, use tmux instead of ht.
• if the program needs a real TTY but screen snapshots or explicit wait conditions are not needed, consider exec with pty=true.

missing ht binary:

• if command -v ht fails, stop and report plainly that ht is not installed.
• do not guess or try random packages named "ht" or "headless-terminal".
• if the user is security-sensitive, suggest reviewing the GitHub repo before installation.
• if the user wants to proceed, offer to install from brew install montanaflynn/tap/ht (macOS) or a release tarball (other OS).

wait strategy:

• if the program prints a known string when ready, use --wait-text "string".
• if the cursor lands at a predictable position, use --wait-cursor <line>,<col>.
• if the program redraws and then settles, use --wait-idle <duration> (typical: 200ms to 500ms for most TUIs).
• do not use --wait-duration or blind sleeps unless nothing better exists; always prefer deterministic conditions.

program fails or exits immediately:

• check the command syntax, working directory, and whether the program refuses non-interactive or unknown terminal types.
• if the program uses alternate screen mode and the view appears blank or stale, try a larger terminal size or check if the program has already exited.
• if waits time out, switch to a different wait condition instead of stacking longer sleeps.

session cleanup:

• if the program exits (e.g., --wait-exit succeeds), always run ht remove <session-name> to clean up the session.
• do not leave exited sessions lying around; they consume resources and create confusion for follow-up commands.
• if the user requests a persistent session (rare), skip cleanup and return the session name for human reuse.

output contract

screen capture format:

• ht view <session-name> returns plain text (UTF-8) representation of the terminal buffer.
• ht view <session-name> --format png returns binary PNG image of the rendered screen (if supported by ht version).
• text snapshots are suitable for parsing output, validating state, or logging.
• PNG snapshots are suitable for human visual inspection, screenshots, or bug reports.

session state:

• a running session persists until ht remove <session-name> is called or the program exits and cleanup runs.
• session names are unique; do not reuse a name until the old session is removed.
• all follow-up commands (send, view, wait, stop) reference the session by name.

success criteria:

• program startup completes without immediate exit; ht view returns non-empty buffer.
• keystroke sequence is sent and the wait condition is met (text appears, cursor lands, or idle timeout expires).
• screen state reflects the expected response (e.g., vim in insert mode, git add -p showing a hunk, SSH prompt visible).
• cleanup commands (stop, remove) complete without error.

outcome signal

immediate feedback:

• ht view <session-name> shows the current screen buffer; inspect it to confirm the program is running and responsive.
• ht send output includes the wait result (success, timeout, or error); if success, the program responded to the keystroke.

visual confirmation:

• screen text or PNG snapshot matches the expected state (e.g., vim shows :wq prompt before exit, git add -p shows the next hunk, SSH prompt is visible).
• cursor position or screen layout reflects the keystroke outcome.

completion:

• ht stop <session-name> returns successfully (program has exited or signal was sent).
• ht remove <session-name> returns successfully and the session is gone (no error on follow-up commands).
• no lingering zombie processes or stale sessions left behind.

failure indicators:

• command -v ht fails: ht is not installed.
• ht run exits immediately: program refused to start (check command, working directory, terminal type).
• ht send wait times out: screen did not reach expected state; use a different wait condition or inspect with ht view.
• ht view returns blank or stale buffer: program may use alternate screen, need larger terminal, or have already exited.
• cleanup commands fail: session may already be gone or orphaned; check with ht list or similar (if available).

practical patterns

drive vim safely

ht run --name notes vim /tmp/notes.md
ht send notes "ihello<Esc>" --wait-idle 200ms --view
ht send notes ":wq<CR>" --wait-exit
ht remove notes

drive a remote TUI over SSH

ht run --name remote ssh user@host.example
ht send remote "top<CR>" --wait-idle 500ms --view
ht send remote "q" --wait-idle 200ms
ht send remote "exit<CR>" --wait-exit
ht remove remote

inspect git add -p interactively

ht run --name addp git add -p
ht view addp
# then send one choice at a time:
ht send addp "y" --wait-idle 300ms --view
ht send addp "n" --wait-idle 300ms --view
# repeat until done, then clean up
ht remove addp

take a PNG screenshot of a running TUI

ht run --name demo htop
ht view demo --format png > screenshot.png
ht send demo "q" --wait-exit
ht remove demo

operating guidance

• use unique session names (e.g., demo-$(date +%s)) so follow-up commands stay readable and do not collide.
• send the minimum keystrokes needed per ht send call; avoid giant pasted blobs that make waits unpredictable.
• after any state-changing input, always capture a fresh view with ht view before assuming success.
• if the screen looks wrong, inspect with ht view before sending more keys.
• clean up exited sessions with ht remove immediately; do not let zombies pile up.
• ask before using ht for privacy-sensitive auth flows, remote systems, or destructive TUI operations. a real PTY makes it easy to do real damage quickly.
• if you discover the task is simple enough for plain shell control, stop using ht and simplify.

failure modes and recovery

program exits immediately:

• check the command syntax, working directory, and whether the program refuses non-interactive or unknown terminals.
• run ht view <session-name> to see the last screen state; may reveal error messages.
• if the program requires a specific TERM setting, try setting TERM=xterm or TERM=xterm-256color before ht run.

waits time out:

• do not stack longer sleeps; instead, switch to a different wait condition (e.g., from --wait-idle 5s to --wait-text "READY").
• use ht view to inspect what the screen actually shows; the condition may be wrong or the program may have crashed.

captured screen is stale or blank:

• check whether the app uses alternate screen mode (may not be rendered in text snapshot).
• try a larger terminal size with ht run --cols 200 --rows 50 (if supported by ht version).
• check if the program has already exited by trying ht send with a dummy keystroke; if it fails, the session is dead.

session cleanup issues:

• if ht remove fails, the session may be orphaned or the daemon may have hung.
• try ht stop <session-name> first to force the program to exit, then ht remove.
• if the daemon itself is stuck, consult ht debug output (if available) or restart the ht daemon.

references

• keys notation: vim-style (e.g., <CR> for carriage return, <Esc> for escape, <C-c> for control-c, <Meta-x> for alt-x, arrows with <Up> <Down> <Left> <Right>)
• wait strategy: prefer --wait-text for known strings, --wait-cursor for predictable cursor positions, --wait-idle for app settle time (200ms to 500ms typical), and --wait-duration only as last resort
• examples: vim edit and save, remote SSH TUI, git add -p workflow, REPL interaction, interactive installer
• github repo: https://github.com/montanaflynn/headless-terminal