vterm/README.md

# vterm

Minimalist terminal for Sublime Text 4, built to run TUI coding agents
(`pi`, `claude`) in a tab. macOS only. No panels, no images,
no build-system integration.

Requires Sublime Text 4 with the Python 3.8 plugin host (build 4149+, for
`View.folded_regions`) and Package Control.

## Install

### With Package Control

vterm is distributed through the shared channel at
[vaclavt/sublime-chanel](https://github.com/vaclavt/sublime-chanel), not the
default one. Open **Preferences → Package Settings → Package Control →
Settings** and put the channel URL in the `channels` array of the right-hand
(User) pane:

```json
{
    "channels": [
        "https://packagecontrol.io/channel_v3.json",
        "https://raw.githubusercontent.com/vaclavt/sublime-chanel/main/channel.json"
    ]
}
```

Keep `https://packagecontrol.io/channel_v3.json` in the list — dropping it
hides every default package. Then run **Package Control: Install Package**
from the Command Palette and pick **vterm**. Upgrades arrive through
**Package Control: Upgrade Package** like any other package.

### From source

Clone the repository into the Sublime Text `Packages` directory as `vterm`:

```sh
git clone https://github.com/vaclavt/vterm.git \
  "$HOME/Library/Application Support/Sublime Text/Packages/vterm"
```

Use one method or the other, not both: an unpacked `Packages/vterm` directory
overrides the `vterm.sublime-package` that Package Control installs.

Either way, dependencies (pyte, ptyprocess, wcwidth) are Package Control
libraries declared in `dependencies.json`. If they are not yet in
`Lib/python38` (e.g. Terminus was never installed), run **Package Control:
Satisfy Libraries** and restart Sublime. Package Control garbage-collects
libraries no package requires, so if imports ever fail after uninstalling
another package, re-run *Satisfy Libraries*.

## Use

Command palette:

- **vterm: Open Terminal** — login shell in a tab (cwd = first project folder,
  else the active file's directory, else `~`)
- **vterm: Open Terminal in Project Folder** — opens the external terminal from
  the settings (Apple Terminal by default) in the project folder of the active file
- **vterm: Clear Screen** (`cmd+shift+k`) — empties the tab, its screen and all
  scrollback, then asks the app to redraw, so the tab looks freshly started
- **vterm: Select Theme** — pick a colour palette, previewing each as you move
  through the list; Esc restores what you had

To launch an agent directly, add your own palette entry or keybinding — `vterm_open`
takes `cmd`, `cwd`, `env` and `title`:

```json
{ "caption": "vterm: pi", "command": "vterm_open", "args": {"cmd": ["pi"], "title": "pi"} }
```

Keys: Shift+Enter sends `ESC CR`, or `CSI 27;2;13~` while the app has xterm
modifyOtherKeys on — pi turns it on and reads a bare `ESC CR` as Alt+Enter,
which submits instead of breaking the line. Shift+PgUp/PgDn page
the view over the scrollback and Shift+Up/Down move it one line, instead of
reaching the app, as xterm and kitty do — `scroll_modifier` moves that to Ctrl,
or turns it off. Copy/paste use the normal Sublime keys, and pastes are
bracketed when the app asks for it. Copying re-joins soft-wrapped lines. The
middle button pastes the current selection straight into the app, X11-style,
without going near the clipboard; it does nothing when nothing is selected. The
wheel scrolls the view normally; while the app tracks the mouse the wheel and
left click go to it instead, and on the alternate screen without tracking each
wheel tick sends arrow keys (alternate scroll, as kitty/iTerm2 do — this is
what scrolls Claude Code's fullscreen UI before it enables mouse reporting).
Sublime raises no wheel event at all for the trackpad (sublime_text#1838): set
a utility such as [LinearMouse](https://linearmouse.app/) to discrete scrolling
for Sublime Text and it arrives as wheel notches like any other. A notch sends the
app three scroll lines, as iTerm2 does; `wheel_lines` lowers that when a swipe
scrolls too far. While an app owns the
alternate screen the scrollback above it is folded away, kitty-style, and
unfolds when the app leaves it.

## Settings

`vterm.sublime-settings`: `auto_close` (close the tab when the process exits;
off leaves it open with a `[process exited with code N]` line),
`scrollback_history_size`, `scroll_modifier` (the modifier that scrolls the
view with PgUp/PgDn and Up/Down; `null` gives all four keys to the app),
`min_columns` / `max_columns`, `terminal` / `parameters` (the external terminal
for *vterm: Open Terminal in Project Folder*; `%CWD%` in `parameters` is
replaced with the project folder, defaulting to Apple Terminal, with kitty
commented out beside it), `debug` (verbose logging to the ST console), plus the
colours:

- `theme` — `"default"` (Terminal.app Basic, light), `"homebrew"`, `"pro"`,
  `"slate"`, `"red-alert"`, or `null` to follow the active Sublime colour scheme. Set it with
  *vterm: Select Theme* or by hand; either way open terminals restyle in place,
  no restart needed.
- `ansi_colors` — override individual base colours, e.g. `{"red": "#ff0000"}`,
  applied on top of the theme.

A light theme is reported to the running agent (OSC 11, DSR 996), so `pi` and
`claude` switch to their light UI to match. An app subscribed to mode 2031 is also
told unprompted when you change the theme mid-session.

## How it works

For the full picture — class inventory, data flows, threading, and a primer on the
terminal protocols — see `Architecture.md`.

- `vterm/emulator.py` — pyte subclasses. The parser is rewritten because stock
  pyte swallows what these agents rely on: `>`/`<`/`=` prefixed CSI, DECRQM `$p`,
  multi-digit OSC. It answers DA1 (Claude Code's query sentinel, which has no
  timeout) and DA2, CPR, XTVERSION + DECRQM 2026 (this is what unlocks Claude
  Code's flicker-free synchronized output on a generic `TERM`), the kitty keyboard
  probe, and OSC 10/11 colour queries; OSC 52 goes to the Sublime clipboard.
  Combining characters are merged as NFC, because Sublime draws decomposed
  sequences badly.
- `vterm/terminal.py` — pty process, reader and renderer threads at ~33 Hz.
  Rendering is held back inside a `?2026` frame, and the pty is resized from the
  view size (TIOCSWINSZ → SIGWINCH). Reads go through an incremental UTF-8
  decoder so a sequence split across chunks is not dropped. The child gets
  `TERM=xterm-256color` and `COLORTERM=truecolor`, with `TERM_PROGRAM` stripped.
  A forced repaint narrows the pty by one column for 250 ms — never ctrl+L, which
  is `/clear` in Claude Code.
- `vterm/render.py` — scrollback and live screen are real view text: dirty rows
  are whole-line replaced, colours are `add_regions` overlays, and the Sublime
  caret doubles as the terminal cursor (DECTCEM turns it into a block, so an app
  drawing its own lands on the same cell; a view with no caret at all loses the
  space key and IME text).
- `vterm/scheme.py` + `vterm/themes.py` — colour scheme rules generated on demand
  per (fg, bg, style) into `Packages/User/vterm/`, truecolor quantized into the
  256 palette to bound the rule table, palette from the selected theme or your
  editor scheme.
- `vterm/keys.py` + generated `Default.sublime-keymap` — every key including the
  printable characters is bound to `vterm_keypress`, so nothing is ever inserted
  into the view: an app that does not echo (vim in normal mode) would otherwise
  leave the character behind. `on_modified` in `vterm/listeners.py` remains the
  fallback for IME and composed input.
- `vterm/mouse.py` — SGR mouse reporting (wheel, click) when the app enables
  tracking; native selection and scrolling otherwise. The trackpad is not
  handled: it reaches no mousemap on macOS and is converted to wheel notches
  outside the plugin.

Supported: alt screen (1049), synchronized output (2026), bracketed paste (2004),
mouse tracking 1000/1002/1003 + SGR 1006 (wheel and left click are reported; no
drag, no right button; the middle button pastes the selection instead of being
reported), focus events (1004),
xterm modifyOtherKeys (`CSI > 4 ; n m`, for the modified keys with no
unambiguous legacy encoding: enter, tab, backspace, space), cursor styles (DECSCUSR —
block/bar and blink/steady via the view's caret settings; underline falls back
to bar, 0 is the default blinking block), scroll regions, autowrap,
50 000 lines of scrollback that ED 3 does not erase (agents repaint with it;
`honor_erase_scrollback` restores the usual meaning),
256-colour and truecolor SGR (truecolor quantized to the 256 palette),
wcwidth-aware wide characters, OSC 0/2 titles,
DEC line drawing (`ESC(0`, so ncurses apps such as mutt or dialog draw real
borders even under a non-UTF-8 locale).
Deliberately absent: the kitty keyboard protocol (legacy encodings are sent
instead), image protocols, Windows, panels.

## Rough edges

- Streaming output is expensive: every scroll marks all rows dirty and each row is
  rewritten over the plugin-host IPC boundary. A per-row cache skips rewriting rows
  whose content did not change, but a genuinely changing full screen still costs
  real CPU. Batching the colour regions across a frame is the known next fix.
- Editing `vterm/*.py` needs a **Sublime restart**. Submodules are deliberately
  not purged on reload, because rebuilding the terminal registry silently orphans
  open tabs; an orphaned tab shows a "disconnected" status and stops accepting
  input, so close it and open a new one.
- CJK and emoji rely on wcwidth agreeing with Sublime's font metrics; where they
  disagree the caret can drift.
- Trackpad scrolling needs a helper on macOS: Sublime never delivers it to a
  plugin (sublime_text#1838), so set a utility such as
  [LinearMouse](https://linearmouse.app/) to discrete/linear scrolling for
  Sublime Text. It then arrives as wheel notches and scrolls the app, three
  lines a notch unless `wheel_lines` says otherwise. Without
  one, the trackpad does nothing in a full-screen app; the mouse wheel,
  `shift+pageup/pagedown` and `shift+up/down` work regardless.

## Dev

```sh
python3 tests/test_emulator.py   # emulator, query responder, clear — chunked and char-by-char
python3 tests/test_imports.py    # modules import, keymap parses, command/flag/theme wiring
python3 tests/test_render.py     # render layer on a fake view: trimming, selection, colouring
python3 tests/test_commands.py   # theme picker, live restyle, generated scheme
python3 tests/harness_live.py CMD SECONDS [--send TEXT]   # run a real app in the emulator, dump the screen
python3 tools/gen_keymap.py      # regenerate Default.sublime-keymap
python3 benchmarks/bench_vs_terminus.py   # render cost per frame, against Terminus on the same input
python3 benchmarks/profiling.py           # feed-path hotspots, per-char micro-benches of draw
```

`harness_live.py` is the useful one: it drives a real `pi` or `claude` through the
emulator with no Sublime involved, and prints the queries answered plus the
resulting screen. Tests import pyte/ptyprocess/wcwidth from Sublime's
`Lib/python38` (pure Python, so any Python 3 runs them).

Code style is in `CODE.md`, working agreements in `CLAUDE.md`.