Workspace

Terminals, PTYs and isatty

3 day streakD

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.

DepthLesson 5 of 713 min

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.

Figure 5.1

Same command, two kinds of stdout

stdout is a pipe

  1. isatty(1) returns 0
  2. Plain text, no colour codes
  3. No pager: output is written and the program exits
  4. Block-buffered: arrives in bursts
commit 9f2c1e7
Author: Dhruv
    Fix pipe drain in run_command
commit 41b0aa3
…
[exit 0]

stdout is a PTY

  1. isatty(1) returns 1
  2. Adds ANSI colour escapes
  3. Opens less for long output
  4. less waits 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]
Through a pipe, 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?

PipePTY
OutputPlain text, easier to parseANSI escape codes to strip
Pagers and promptsUsually offOn: may wait for input forever
BufferingBlock-buffered, arrives in burstsLine-buffered, arrives live
stdout and stderrSeparateMerged into one stream
Needed forMost commandsInteractive 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.

noninteractive-env.tsTypeScript
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

Hanging installers

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 buffering

Python block-buffers stdout when it is a pipe, so logs appear in bursts. PYTHONUNBUFFERED=1 or python -u streams them live.

Terminal tools

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.

A good place to start

Explore a pattern

A little guidance

Start with a pattern, read through a problem, and mark it solved when the idea clicks. Save anything you want to revisit.

New tutorials are added one at a time. Your bookmarks and solved checkmarks stay in this browser.

Explore the roadmap