Terminals, PTYs and isatty
Programs behave differently when they think a person is watching. Learn what a pseudo-terminal is, and why git log hangs in one harness and not another.
Programs ask isatty(fd) to learn whether a descriptor is a terminal. If stdout is a terminal, they assume a person is reading: they add colour codes, line-buffer output, show progress bars and open a pager for long output. If stdout is a pipe, they assume another program is reading: plain text, block buffering, no prompts.
Same command, two kinds of stdout
stdout is a pipe
isatty(1)returns 0- Plain text, no colour codes
- No pager: output is written and the program exits
- Block-buffered: arrives in bursts
commit 9f2c1e7
Author: Dhruv
Fix pipe drain in run_command
commit 41b0aa3
…
[exit 0]stdout is a PTY
isatty(1)returns 1- Adds ANSI colour escapes
- Opens
lessfor long output lesswaits for a keypress
\x1b[33mcommit 9f2c1e7\x1b[m
Author: Dhruv
Fix pipe drain in run_command
: ← less is waiting for input
…
[still running at timeout]git log writes plain text and exits. Through a PTY, it sees a terminal, adds colour and opens less, which waits for a keypress that never comes.What a PTY is
A pseudo-terminal is a pair of devices. The program sees the follower side, which behaves like a real terminal. The harness holds the leader side and plays the role of the keyboard and screen. Line discipline in the kernel handles echo, Ctrl-C and window size between them. Terminal emulators, SSH and tmux are all built on PTYs.
Pipe or PTY for an agent tool?
| Pipe | PTY | |
|---|---|---|
| Output | Plain text, easier to parse | ANSI escape codes to strip |
| Pagers and prompts | Usually off | On: may wait for input forever |
| Buffering | Block-buffered, arrives in bursts | Line-buffered, arrives live |
| stdout and stderr | Separate | Merged into one stream |
| Needed for | Most commands | Interactive programs, REPLs, TUIs |
Most harnesses default to pipes and set environment variables that suppress interactive behaviour. Offer a PTY only for tools that genuinely need a terminal, and then give the model a way to send keystrokes and a timeout.
export const NONINTERACTIVE_ENV = {
CI: "1", // many tools disable prompts and spinners
PAGER: "cat",
GIT_PAGER: "cat",
GIT_TERMINAL_PROMPT: "0", // fail instead of asking for credentials
NO_COLOR: "1",
TERM: "dumb",
DEBIAN_FRONTEND: "noninteractive",
PIP_NO_INPUT: "1",
};
// And give stdin nothing to wait for:
// spawn(cmd, { stdio: ["ignore", "pipe", "pipe"], env: { ...safeEnv, ...NONINTERACTIVE_ENV } })With stdin set to ignore, a program that reads input gets EOF immediately instead of waiting forever.
Where you will meet it
apt-get install without -y waits on a prompt. Under a pipe with stdin open, the agent's tool simply hangs until its timeout.
Python block-buffers stdout when it is a pipe, so logs appear in bursts. PYTHONUNBUFFERED=1 or python -u streams them live.
VS Code's terminal and agent terminals use node-pty to give commands a real PTY, then render the escape codes.
Check yourself
Answer out loud before you open each one.
Why does the same command print differently under a harness?
It calls isatty on stdout. A pipe is not a terminal, so it disables colour, paging and line buffering.
Why might git log hang a PTY-based tool?
It detects a terminal, opens a pager, and the pager waits for keyboard input.
What does setting stdin to ignore achieve?
Reads from stdin return EOF at once, so prompts fail fast instead of blocking.
Try it
Run ls --color=auto | cat and ls --color=auto and compare. Then run python3 -c 'import sys; print(sys.stdout.isatty())' both directly and piped through cat.