Skip to main content
hty is a headless terminal runtime that lets AI agents, automation scripts, and CI pipelines control interactive programs like vim, git add -p, psql, btop, and gh auth login — programs that ordinarily require a real keyboard and screen. It spawns programs inside a real PTY, maintains a persistent background server across invocations, and exposes a simple CLI for reading the screen and sending input.

Installation

Install hty with a one-line script, Homebrew, or build from source.

Quick Start

Walk through a complete agent workflow in under five minutes.

Commands

Full reference for every hty subcommand and its flags.

Guides

Step-by-step guides for AI agents, CI automation, and remote sessions.

​
How hty works

hty runs a lightweight background server the first time you invoke it. That server owns all PTY sessions and keeps them alive across individual hty calls — so your agent can send one command, do other work, then come back and read the screen later.
1

Start a session

Run any interactive program in a detached PTY session with a human-friendly name.
hty run --name my-session -- git add -p
2

Wait for output

Block until specific text appears on the screen, the screen goes idle, or the process exits.
hty wait my-session --text "Stage this hunk" --timeout 5000
3

Read the screen

Take a snapshot of the full rendered terminal screen at any time.
hty snapshot my-session
4

Send input

Type text, press named keys, or send raw bytes into the session.
hty send my-session --text "y\n"
hty send my-session --key esc

​
Key capabilities

Persistent sessions

Sessions live in the background server and survive across hty invocations. No need to keep a process open.

Screen snapshots

Read the fully rendered terminal screen as plain text or with ANSI color codes at any point.

Smart wait primitives

Block until text appears, the screen goes idle, or the process exits — with configurable timeouts.

Live observation

Watch any session’s screen in real time from another terminal with hty watch, without interfering.

Session replay

Every session is logged to an append-only JSONL file. Replay it later with hty replay.

Remote access

Point $HTY_SOCKET at an SSH tunnel to observe or drive sessions running on another machine.