hty
Show HN: Headless terminal in zig allows AI agents to use interactive CLIs
Last verified:
What is hty?
hty is a tool that gives AI agents a way to use interactive TUI (text-based user interface) and CLI (command-line interface) programs by reading the rendered screen and sending keys. Dubbed
hty pricing
Pricing model: Freemium
Free and open-source. Installed via curl | sh single command (curl -fsSL https://raw.githubusercontent.com/LatentEvals/hty/main/scripts/install.sh | sh). No paid tiers mentioned - the tool is a standalone CLI binary with zero dependencies.
hty pros
- Works with any interactive terminal program a human can use
- Persistent sessions survive across CLI invocations
- Full session replay with hty replay through fresh VT engine
- Live watch capability shows what agent sees in real-time
- Single binary with zero dependencies
- Built on Ghostty's production-grade VT engine in Zig
- Wait primitives (--text, --idle, --exit) with timeouts eliminate sleep hacks
- Remote observation via SSH tunnel to sessions on remote machines
- Snapshot output supports plain text, JSON, and ANSI rendering
- Mouse input support for TUIs like btop, lazygit, k9s
- Compound input --seq mixes text, keys, and pauses in one call
- --raw-text flag sends UTF-8 bytes verbatim without escape interpretation
- --remove flag auto-cleans sessions to prevent zombie entries
- --attach streams live PTY output to harness without polling
- Session recording preserved even after hty kill for logs/replay
- Named sessions (--name) make agent code easier to debug
- Fused send --snapshot combines input and screen read in one round-trip
hty cons
- Requires AI agent to understand shell command primitives
- Mouse input only works with apps that explicitly enable mouse mode
- Programs that continuously redraw (like top) never go idle for --idle wait
- Timeout exit code 3 may require --json for clear success/failure distinction
- --attach is mutually exclusive with --snapshot and --wait-until-* flags
- Sessions without --remove accumulate as zombie entries filling the registry
- Learning curve for agent developers to use hty commands effectively
- No native GUI interface - CLI-only tool requiring shell access
Frequently asked questions about hty
What is hty?
hty is Puppeteer for the terminal - a tool that gives AI agents a way to use interactive TUI and CLI programs by reading the rendered screen and sending keys. It wraps any interactive program in a persistent PTY session so your agent reads the terminal like a human does and types like a human would.
How do I install hty?
Install with a single command: curl -fsSL https://raw.githubusercontent.com/LatentEvals/hty/main/scripts/install.sh | sh. Alternatively, install via the skills CLI: npx skills add LatentEvals/hty --skill hty, which teaches the agent when to use hty and handles installing the hty CLI itself.
What programs work with hty?
hty works with any program that runs in a terminal: vim/neovim (modal editors), git add -p (interactive staging), psql (interactive SQL), gh auth login (auth flows), btop/htop (monitoring TUIs), create-next-app (scaffolding wizards), and any other interactive terminal program a human can use.
How do agent sessions work?
An hty session is a pseudoterminal (PTY) process managed by the hty background server. Sessions persist across invocations, are identified by name or UUID, and you reference them with commands like hty run --name demo, hty snapshot demo, hty send demo, hty wait demo, hty kill demo, and hty delete demo.
What wait conditions does hty support?
hty wait supports: --text for substring match (waits for specific string), --regex for POSIX extended regex (matches multiple possibilities), --idle for when rendered screen stops updating (measures rendered screen not raw I/O), and --exit to confirm program finished. All have timeouts and exit code 3 on timeout.
How do I read the terminal screen?
Use hty snapshot SESSION [--json] [--ansi]. Default is plain text. Use --json for structured response with cursor_row, cursor_col, status, and cells grid. Use --ansi for styled ANSI rendering. Pipe JSON to jq for extracting specific parts like .snapshot.buffer or .snapshot.lines[index].
When should I use --raw-text vs --text?
--text processes C-style escapes where becomes newline, becomes tab, \ becomes literal backslash - usually what you want for commands with Enter. Use --raw-text when sending source code, regex, or content with backslashes you don't want interpreted - it sends UTF-8 bytes verbatim without escape processing.
Can I use hty with remote machines?
Yes, hty supports remote observation. SSH tunnel to a remote machine and use hty watch or hty attach to sessions running there. No protocol changes needed - the same commands work for remote sessions as local ones.