---
name: pty
description: PTY sessions for long-running processes, interactive input, signal sending (Ctrl+C), and live output tailing — use instead of bash when the process can't be run to completion synchronously
license: MIT
compatibility: opencode
metadata:
  provides:
    - shell
---

## When to Use PTY

Use `pty_spawn` instead of `bash` when:
- The process runs in the background or long-running (dev servers, watchers, etc.)
- The command requires interactive input
- You need to send signals (Ctrl+C, Ctrl+D) mid-run
- You want to tail output while the process is still running

## Key Sequences

| Action | Data |
|--------|------|
| Ctrl+C (interrupt) | `\x03` |
| Ctrl+D (EOF) | `\x04` |
| Ctrl+Z (suspend) | `\x1a` |
| Enter | `\n` |

Send with `pty_write`: `data="\x03"`

## Reading Output

Use the `pattern` parameter in `pty_read` to filter lines by regex:

```
pattern="error|ERROR"       # find errors
pattern="ERROR|WARN|FATAL"  # find warnings and errors
pattern="failed.*connection" # more specific match
```

`pattern` filters first, then `offset`/`limit` apply to the matches — original line numbers are preserved.

## Checking Status

- `pty_list` — see all running/exited sessions
- `pty_read` with high `offset` or omit offset to see latest output
- To tail last N lines: `offset = totalLines - N`

## Cleanup

- `pty_kill` with `cleanup=false` (default) — stops process, keeps buffer for reading
- `pty_kill` with `cleanup=true` — stops process and frees buffer entirely

## notifyOnExit

Set `notifyOnExit=true` to receive a message when the process exits, including exit code and last output line. Useful for build processes where you want to be notified on completion rather than polling.