# Hive.terminal Tools Pty Sessions

Use when you need state across calls, building env vars, navigating with cd, driving...

- Repository: https://github.com/aden-hive/hive (11131 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add aden-hive/hive --skill hive.terminal-tools-pty-sessions -g -a claude-code -y`
Codex: `npx skills add aden-hive/hive --skill hive.terminal-tools-pty-sessions -g -a codex -y`
Cursor: `npx skills add aden-hive/hive --skill hive.terminal-tools-pty-sessions -g -a cursor -y`
Gemini CLI: `npx skills add aden-hive/hive --skill hive.terminal-tools-pty-sessions -g -a gemini-cli -y`

## Description

Use when you need state across calls, building env vars, navigating with cd, driving REPLs (python -i, mysql, psql, node), or responding to interactive prompts (sudo password, ssh host-key confirmation, mysql connection). Teaches the prompt-sentinel exec pattern (default mode), raw I/O for REPLs (raw_send=True then read_only=True), the one-in-flight-per-session rule, and the close-or-leak-against-the-cap discipline. Bash on macOS, never zsh; explicit shell=/bin/zsh is rejected. Read before calling terminal_pty_open.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Persistent PTY sessions

PTY sessions are how you talk to interactive programs, programs that detect a terminal (`isatty()`) and behave differently when they don't see one. Use a session when:

- You need state to persist across calls (`cd`, env vars, sourced scripts)
- You're driving a REPL (`python -i`, `mysql`, `psql`, `node`, `irb`)
- A program demands an interactive prompt (`sudo`, `ssh`, `npm login`, `gh auth login`)

For everything else, `terminal_exec` is simpler. Sessions cost more (per-session bash process, ring buffer, idle-reaping bookkeeping) and have a hard cap (`TERMINAL_TOOLS_MAX_PTY`, default 8).

## Why PTY (and not subprocess pipes)

Subprocess pipes break on every interactive program. The moment a program calls `isatty()` and sees False, it disables prompts, color, line-editing, password masking, progress bars, sometimes refuses to start. PTY makes us look like a real terminal so these programs work the same as in your shell.

The cost: PTY output includes terminal escape codes (cursor moves, color codes). The session captures them as-is; if you need clean text, strip ANSI escapes in your processing layer.

## Bash on macOS, by deliberate policy

`terminal_pty_open` always invokes `/bin/bash`, regardless of the user's `$SHELL`. macOS users: yes, even when zsh is your interactive default. This is the **terminal-tools-foundations** policy applied to PTYs.

Reasons:
- zsh has command/builtin classes (`zmodload`, `=cmd` expansion, `zpty`, `ztcp`) that bypass bash-shaped security checks
- One shell behavior across platforms eliminates "works on Linux, breaks on macOS" surprises
- Bash is universal: any shell you've used will accept the bash subset

The bash invocation uses `--norc --noprofile` so user dotfiles don't leak in. PS1 is set to a unique sentinel for prompt detection. PS2 is empty. PROMPT_COMMAND is empty.

## Three modes of `terminal_pty_run`

### 1. Default: send command, wait for prompt sentinel

The rest: https://github.com/aden-hive/hive/blob/HEAD/core/framework/skills/_preset_skills/terminal-tools-pty-sessions/SKILL.md