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

Symlink this folder into Sublime packages as vterm:

ln -s /Users/vaclavt/devel/vt/vterm "$HOME/Library/Application Support/Sublime Text/Packages/vterm"

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:

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

Keys: Shift+Enter sends ESC CR (newline in both agents). Shift+PgUp/PgDn page the view over the scrollback instead of reaching the app, as xterm and kitty do — page_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 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). While an app owns the alternate screen the scrollback above it is folded away, kitty-style, and unfolds when the app leaves it.

The caret follows DECSCUSR, so zsh vi-mode can show a block cursor in normal mode. The shell must emit the sequence — add to ~/.zshrc:

function zle-keymap-select zle-line-init {
    case $KEYMAP in
        vicmd) print -n '\e[1 q' ;;  # blinking block
        *)     print -n '\e[5 q' ;;  # blinking bar
    esac
}
zle -N zle-keymap-select
zle -N zle-line-init

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, page_scroll_modifier (the modifier for the PgUp/PgDn page scroll; null gives both 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", 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.

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 or middle button), focus events (1004), 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.

Dev

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 tools/bench_vs_terminus.py   # render cost per frame, against Terminus on the same input

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.