How do I install the Headless Terminal skill?

Run npx skillmds@latest add tomevault-io/headless-terminal in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Headless Terminal safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Headless Terminal?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Headless Terminal free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Headless Terminal?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Headless Terminal by tomevault-io — Agent Skill

Name: Headless Terminal
Author: tomevault-io

Headless Terminal

Drive interactive terminal programs (vim, emacs, nethack, htop, CLI installers, REPLs, anything curses-based) headlessly via the `ht` CLI. Use when the task needs a program that expects a real TTY — won't run under plain pipes, draws to an alternate screen, or needs keystrokes like arrow keys, Ctrl-C, or function keys. Do not use for non-interactive commands that work fine with plain shell pipes. Use when this capability is needed.

tomevault-io Updated Sep 17, 2026

File contents

ht — headless terminal

ht is a daemon that owns a pseudo-terminal per session and parses output with the same VT engine Ghostty uses. You can launch a TUI, send keystrokes, snapshot the rendered screen, and block until a screen condition is met.

Install ht

Check if the CLI is on PATH; if not, install it:

command -v ht || brew install montanaflynn/tap/ht

Without Homebrew, grab a tarball from the releases page and move the binary onto PATH. macOS (Apple Silicon) and Linux (x86_64/arm64) only.

When to reach for this

Target program draws to the alternate screen / uses (n)curses / reads $TERM.
Needs real keystrokes (arrow keys, <C-c>, <F5>), not just stdin text.
You need to inspect the rendered screen state, not the raw output byte stream.

If the program works with echo ... | cmd, use a plain pipe — don't reach for ht.

Core workflow

ht run --name S <cmd...>           # launch, prints session ID
ht send S "<keys>"                 # type into it
ht view S                          # snapshot screen (plain text)
ht wait S --text "READY"           # block until a condition
ht stop S && ht remove S           # cleanup

ht run prints a short hex session ID. Use --name to label it and reference the session by that name everywhere else — it's easier than juggling IDs.

The one thing agents get wrong

Keystrokes reach the PTY before the program has finished rendering a response. Do not view immediately after send — you'll snapshot a stale screen.

Fold the wait into the send:

ht send S --wait-text "Saved" "ihello<Esc>:wq<CR>"
ht send S --wait-idle 200ms --view "q"

Picking the right wait flag is the hard part — see references/waits.md before writing sends for a new TUI.

Quick pointers

Key notation (vim-style <C-c>, <CR>, <F1>, …): references/keys.md
Wait strategies (idle vs text vs cursor vs change vs duration): references/waits.md
Recipes (edit-a-file, REPL, installer, watch-live, extract text): references/recipes.md
Troubleshooting (exit codes, timeouts, stuck sessions): references/troubleshooting.md

Output formats

ht view --format plain (default) — text grid with a trailing cursor: R,C line. Use the cursor to disambiguate same-glyph entities (e.g. two @s in nethack: the cursor sits on you).
ht view --format ansi — preserves colors/styles; good for showing the user. Also appends the cursor: line.
ht view --format html — embeddable; no cursor line (would break the doc).
ht view --format png --output FILE — rasterized screenshot with window chrome. Use for demos, bug reports, or to let yourself see a session (Claude can read PNGs, can't render SVG).
ht view --json — structured (cursor position, size, text).

Cleanup

Sessions persist across the daemon's lifetime. Always ht stop <sid> + ht remove <sid> when done, or the daemon accumulates zombie records. ht list shows what's live.

Source: montanaflynn/headless-terminal — distributed by TomeVault.

---name: headless-terminaldescription: Drive interactive terminal programs (vim, emacs, nethack, htop, CLI installers, REPLs, anything curses-based) headlessly via the `ht` CLI. Use when the task needs a program that expects a real TTY — won't run under plain pipes, draws to an alternate screen, or needs keystrokes like arrow keys, Ctrl-C, or function keys. Do not use for non-interactive commands that work fine with plain shell pipes. Use when this capability is needed.---# ht — headless terminal`ht` is a daemon that owns a pseudo-terminal per session and parses output with the same VT engine Ghostty uses. You can launch a TUI, send keystrokes, snapshot the rendered screen, and block until a screen condition is met.## Install htCheck if the CLI is on `PATH`; if not, install it:```shcommand -v ht || brew install montanaflynn/tap/ht```Without Homebrew, grab a tarball from the [releases page](https://github.com/montanaflynn/headless-terminal/releases) and move the binary onto `PATH`. macOS (Apple Silicon) and Linux (x86_64/arm64) only.## When to reach for this- Target program draws to the alternate screen / uses (n)curses / reads `$TERM`.- Needs real keystrokes (arrow keys, `<C-c>`, `<F5>`), not just stdin text.- You need to inspect the *rendered* screen state, not the raw output byte stream.If the program works with `echo ... | cmd`, use a plain pipe — don't reach for ht.## Core workflow```ht run --name S <cmd...> # launch, prints session IDht send S "<keys>" # type into itht view S # snapshot screen (plain text)ht wait S --text "READY" # block until a conditionht stop S && ht remove S # cleanup````ht run` prints a short hex session ID. Use `--name` to label it and reference the session by that name everywhere else — it's easier than juggling IDs.## The one thing agents get wrongKeystrokes reach the PTY before the program has finished rendering a response. **Do not `view` immediately after `send`** — you'll snapshot a stale screen.Fold the wait into the send:```ht send S --wait-text "Saved" "ihello<Esc>:wq<CR>"ht send S --wait-idle 200ms --view "q"```Picking the right wait flag is the hard part — see `references/waits.md` before writing sends for a new TUI.## Quick pointers- **Key notation** (vim-style `<C-c>`, `<CR>`, `<F1>`, …): `references/keys.md`- **Wait strategies** (idle vs text vs cursor vs change vs duration): `references/waits.md`- **Recipes** (edit-a-file, REPL, installer, watch-live, extract text): `references/recipes.md`- **Troubleshooting** (exit codes, timeouts, stuck sessions): `references/troubleshooting.md`## Output formats- `ht view --format plain` (default) — text grid with a trailing `cursor: R,C` line. Use the cursor to disambiguate same-glyph entities (e.g. two `@`s in nethack: the cursor sits on you).- `ht view --format ansi` — preserves colors/styles; good for showing the user. Also appends the `cursor:` line.- `ht view --format html` — embeddable; no cursor line (would break the doc).- `ht view --format png --output FILE` — rasterized screenshot with window chrome. Use for demos, bug reports, or to let yourself *see* a session (Claude can read PNGs, can't render SVG).- `ht view --json` — structured (cursor position, size, text).## CleanupSessions persist across the daemon's lifetime. Always `ht stop <sid>` + `ht remove <sid>` when done, or the daemon accumulates zombie records. `ht list` shows what's live.---> Source: [montanaflynn/headless-terminal](https://github.com/montanaflynn/headless-terminal) — distributed by [TomeVault](https://tomevault.io).

Frequently asked questions