# Terminal-first architecture

The PTY is the source of truth. Chat is a readable projection with the raw terminal always available.

Canonical: https://panevibe.com/docs/terminal-first/
Source: https://github.com/brandonmlicea/panevibe

## The one decision

A coding CLI is a terminal program: ANSI escapes, cursor movement, raw-mode input, resize signals, and process signals are part of its behavior. PaneVibe runs the real binary in a real pseudo-terminal instead of rebuilding the agent loop behind a request API.

The byte stream is parsed into semantic chat events for readability, while the raw stream remains one keystroke away. A parser gap can be cosmetic, but it cannot remove the underlying capability.

## System shape

- IDE surface: Next.js and React render chat, terminal, editor, browser, files, diffs, and worktrees.
- Agent harness: local transport connects PTYs, parsing, policy, indexing, and browser control.
- Real CLI: Claude, Codex, a shell, or another executable runs as its own process in its own working directory.

`Architecture`

```text
IDE surface  →  agent harness  →  real CLI in a PTY
 code + browser    context + actions      source of truth
```

## Fault boundaries

Every pane is an independent process with its own working directory, history, and lifecycle. Closing one pane tree-kills only that process tree. Panics unwind rather than abort so one command failure does not take down every window.