Headless terminal - Allow agents to run any interactive TUI or CLI

Free

FreeFree tier

Outputs: text

Type

Open Source

Visit Website GitHub (2 stars)

About Headless terminal - Allow agents to run any interactive TUI or CLI

Headless terminal is a CLI tool and daemon that acts as a 'puppeteer for terminal UIs'. It allows users to spawn interactive terminal applications like vim, emacs, htop, or nethack in a background pseudo-terminal session, send keystrokes with vim-style notation, snapshot the screen as text or PNG, and optionally stream the session live to another shell. Under the hood, it uses a Unix-socket daemon that owns a pseudo-terminal per session and pipes output through the libghostty-vt parser for accurate VT emulation. Designed for AI agents, CI tests, demo recording, and follow-along debugging, the tool provides synchronization primitives so the driver knows when the TUI has finished redrawing. It includes commands: ht run, ht send, ht view, ht remove, ht record, ht watch, and ht stop.

Key Features

Spawns interactive TUIs in background pseudo-terminal sessions

Send keystrokes using vim-style notation (e.g., CR, Esc, C-c, F1)

Snapshot the screen as text or PNG image

VT parsing via libghostty-vt (tracks cursor, scrollback, styles)

Synchronization primitives to detect when TUI finishes redrawing

Commands: ht run, ht send, ht view, ht remove, ht record, ht watch, ht stop

Live session streaming to another shell with ht watch

Record keystroke-perfect asciicasts with ht record

Works with any TUI that expects a real tty

Designed for agentic coding, CI testing, demo generation, and debugging

Pros & Cons

Pros

Enables agentic control of TUIs that normally require a human at a keyboard
Uses a real pseudo-terminal, so programs behave as if attached to a tty
VT parser from Ghostty provides accurate terminal emulation (cursor, scrollback, styles)
Can snapshot screen as both text and PNG for easy verification
Live streaming feature aids debugging and pair programming
Open source and free to use

Cons

Requires a Unix-like system due to Unix-socket daemon
Keystroke notation may have a learning curve for non-vim users
No prebuilt binaries provided; must build from source with Go toolchain
Not a standalone GUI application; purely command-line based

Best For

AI agents driving interactive CLIs that require a pseudo-terminalCI testing for interactive TUIs (e.g., script vim and assert screen output)Demo and documentation generation (record and render GIFs or PNGs)Follow-along debugging by streaming a session live to another paneAutomating git add -p, gh auth login, create-next-app, REPLs, debuggers, etc.

FAQ

What can I do with headless terminal?

It allows you to drive interactive TUIs like vim, emacs, htop, or nethack from a CLI or an AI agent. You can spawn sessions, send keystrokes, snapshot the screen, and live-stream the session.

How does headless terminal work?

It runs a Unix-socket daemon that owns a pseudo-terminal per session. The TUI's output is piped through the libghostty-vt parser for accurate VT emulation, tracking cursor position, scrollback, and styles. The driver can send keystrokes and receive screen snapshots.

Can I use headless terminal in CI tests?

Yes. You can boot a TUI, send keystrokes, wait for idle, and assert against the rendered screen (as text or PNG snapshot). The tool covers paths that tools like expect/pexpect cannot handle, such as alternate screen, colors, and cursor position.

Does headless terminal support recording?

Yes. The ht record command allows you to create keystroke-perfect asciicasts that can later be rendered to GIF or used for documentation.

What kind of programs can be driven?

Any interactive TUI or CLI that requires a pseudo-terminal, including vim, emacs, htop, nethack, git add -p, gh auth login, create-next-app, REPLs, debuggers, and more.