BetterTerminal

BetterTerminal — build spec

A real macOS terminal emulator that's genuinely better than Terminal.app: tabs, split panes, search, themes, a command-history rail with exit codes, jump-to-prompt, and a plain-English bar for people who have never used a terminal. Real PTY login shells — job control, vim/htop/ssh all work.

• App: ~/Applications/BetterTerminal.app (double-click) · fallback ~/Documents/BetterTerminal.command
• Source: ~/Documents/projects/apps/BetterTerminal/
• Version 1.1.0 · Python 3.11 (uv venv) + aiohttp + ptyprocess + pywebview (Cocoa/WKWebView)

Plain-English layer (v1.1)

web/plain.js is a pure, offline resolver: resolve(text, ctx) -> {ok, cmd, explain, danger}.

• 48 intents in one ordered array, each {id, group, label, match(n, ctx), build(m, ctx), preview}.

Order matters — first match wins, so specific phrases come before generic verbs.

• Path resolution (resolvePath) is the heart: {cwd, listing} context from

/api/ls lets it match real folder names fuzzily (score by exact/flat/prefix/ substring/token overlap), map synonyms ("desktop" → ~/Desktop), and refuse to invent paths — it returns candidates for a "did you mean" chip instead. Unambiguous home folders win immediately; loose words (photos/music/videos) only map to the system folder when no local folder of that name exists.

• Teaching: every translation shows the command plus a glossary explanation

(cd = change folder); the History rail keeps the real command.

• Safety: danger results (delete/move/copy/kill/install/git push) open a

confirm dialog showing the exact command; the UI never runs them silently.

• Guide tab: the same intents rendered as a searchable cheat sheet, with the

resolved command or a <placeholder> pattern under each phrase.

• Rescue: exit code 127 + command not found: X in the buffer → Levenshtein

suggestion toast with one-click "Run grep" buttons.

• Never blocks shell users: looksLikeShell() runs first — flags, pipes,

paths, quotes, globs and bare known commands pass through untouched.

Architecture

Python owns the terminals; the UI is a web front-end in a native window.

1. pty_session.py — PtySession spawns a real login shell via ptyprocess

(own session + controlling tty) and registers the master fd on the asyncio loop with loop.add_reader. Non-blocking read/write with an output buffer, incremental UTF-8 decoding, TIOCSWINSZ resize, killpg for signals.

2. server.py — aiohttp on 127.0.0.1 with a per-launch random token required

on /ws and /api/* (no other local page can drive your shell). /ws bridges bytes to a PTY; the first frame carries the real terminal geometry so the prompt never reflows. Also /api/ls (folder listings for the resolver), /api/git, /api/clipboard, /api/open, /api/title, /api/stats.

3. web/ — xterm.js (vendored locally) + app.js: tab tree, split-pane tree,

search (addon-search), WebLinks, OSC hooks, sidebar, palette, English bar.

4. main.py — picks a free port, runs the server in a thread, opens a pywebview

window at http://127.0.0.1:PORT/?t=TOKEN. Flags: --command, --cwd, --shell, --no-window (headless tests), --port, --token.

Shell integration (the clever bit)

shell/ is a ZDOTDIR shim. zsh reads .zshenv/.zprofile/.zshrc/.zlogin from there; each shim re-sources the user's real file, then .zshrc installs OSC hooks: OSC 7 = cwd, OSC 133;A/B/C/D = prompt start / input start / output start / command finished + exit code. The UI parses these to drive the status bar, the history rail (command text is read back out of the xterm buffer between the B and C marks), and jump-to-prompt markers. OSC 52 (remote clipboard write) is swallowed for security.

Pitfalls learned

• (( ${+functions[add-zsh-hook]} )) silently evaluated false in this shell →

the hooks never installed. Use autoload -Uz add-zsh-hook then add-zsh-hook precmd/preexec, with an array-append fallback.

• Do not default to the xterm WebGL renderer — it painted a blank pane.

Default is the DOM renderer; WebGL is an opt-in setting.

• macOS menu bar steals shortcuts: clear keyEquivalent on conflicting menu

items (⌘D dictation, ⌘F fullscreen) after webview.start.

• The launcher execs Python, so set processName + setApplicationIconImage_

at runtime to brand the Dock/menu.

• Restarting a shell must invalidate the old WebSocket's handlers (generation

counter) or its onclose re-marks the new session as dead.

• ZDOTDIR also moves zsh's default HISTFILE to $ZDOTDIR/.zsh_history, which

hides the user's real history. Re-export HISTFILE="$HOME/.zsh_history" from the shim's .zshenv unless the user set one.

• A match that returns a boolean throws away regex capture groups. Use the

rx(re, guard) helper so build() always gets a match array; a bare const m = ...; if (m === true) m = null pattern crashes on .replace.

• .hidden is both an attribute and a class name. The bar is hidden with a

CSS class (classList.toggle('hidden')), so test probes must use classList.contains('hidden') — reading el.hidden silently returns false.

• Test the guide against itself: resolve every guide label and assert it

lands on its own intent id. That caught 5 mislabelled/misrouted phrases (get/move stolen by the navigation verb, "go back to the last folder" not matching its own regex).

• ⌘ does not always render in terminal fonts — write "Cmd-E" in text sent to

the terminal, keep ⌘ for the UI chrome.

Rebuild / test

python3 tools/make_icon.py    # icon HTML -> PNG -> AppIcon.icns
python3 tools/build_app.py    # ~/Applications/BetterTerminal.app + .command
tools/run_tests.sh            # both Playwright suites (103 checks) on a temp server

tests/debug.py, tests/debug2.py, tests/debug_keys.py, tests/pty_hooks.py, tests/shim_check.py = targeted debuggers. BT_SNAPSHOT=/tmp/x.png + BT_SNAPSHOT_DELAY=7 saves a PNG of the real WKWebView's pixels (in-process snapshot, no screen-recording permission).