Typing into a focused child while its emulator viewport was
scrolled up left the keystroke heading to the PTY but the input
box invisible below the visible region — it looked like typing
did nothing. processStdin's flushForward now sets
pendingViewportBottom whenever bytes are actually injected, so
the existing post-loop handler snaps the viewport and repaints.
Wheel events and Ctrl-B paths are untouched: both are intercepted
before reaching forward, so wheel still scrolls into history and
Ctrl-B is still the explicit escape hatch. Only bytes that would
actually reach the child PTY trigger the snap.
Sidebar rows that overflow the rail width used to spill characters
into the main viewport. They now truncate with a trailing "…"
when unfocused (or when the focused name still fits). The focused
row whose name overflows runs a pause-scroll-pause marquee: 1 s
hold on the head, ~150 ms per cell scroll, 1 s hold on the tail,
snap back. The row's geometry never moves while it animates, so
nothing below shifts.
A dedicated 150 ms goroutine flips sidebarDirty only while a row
is actively animating; the chrome ticker does the actual repaint.
Idle is a single cheap wakeup. focus / spawn / exit / restart all
reset the marquee state so the new focused row starts from frame
zero. When the row's budget is tight, the trailing timer
indicator drops before the name ellipses since the name is the
only identifier the row carries.
clampVisible() is a defensive net inside write(): even if a row's
decoration size were mis-computed, it will not spill past the
sidebar band into the PTY area.
The top tab bar compared against focusedID, so stepping into a
sub-agent dropped the parent tab's highlight even though the user
was still inside that thread. activeAgentID already walks the
parent chain to the top-level root for the sidebar's agent tree
— reuse it for the tab strip too.
Bundles the in-flight work into the second tagged release. See
CHANGELOG.md `[0.0.2] - 2026-05-15` for the full per-change list.
Highlights:
- libghostty-vt was building in zig's silent Debug default, capping
the full pipeline at 34-63 fps. Makefile now defaults to
ReleaseFast (.mise.toml pins zig 0.15.2 so the build is
reproducible). End-to-end pipeline now runs at 930-2030 fps —
27-32× faster, with 7-16× headroom over a 120 fps target.
- --debug[=DIR] and --profile[=DIR] flags capture full PTY logs,
pprof data, and per-hot-path metrics (chunks/sec, mean/max
latencies, cache hit rates) for offline analysis. Nothing
pollutes stdout/stderr.
- ASCII-video benchmark suite (8-colour / truecolor / Bad-Apple
patterns at 30/60/120 fps) plus a renderer microbenchmark set
for stable A/B comparisons across changes.
- Click-and-drag text selection from alt-screen TUIs (codex) now
works — host mouse mode follows the focused child's screen side
instead of being permanently armed.
- Long claude session resume + codex steady-state rendering pay
less per chunk: drawSidebar deferred to the chrome ticker,
emulator.Title CGO poll gated on a containsOSC scan.
- Vendor-TUI orientation: MCP initialize.instructions, the
spawn_agent tool description, and help('spawning') all spell
out the anti-patterns (shell-out, perl-into-socket) that
produced codex's stray top-level tabs.
Added .mise.toml pinning zig = "0.15.2" (the minimum the vendored
Ghostty commit requires) and taught the Makefile to resolve zig
through mise when available, falling back to PATH. Contributors run
`mise install` once and `make deps` just works.
Re-ran the pipeline benchmarks after rebuilding libghostty-vt with
ReleaseFast (same hardware, AMD Ryzen 7 7800X3D):
Debug ReleaseFast speedup
Pipeline 8-colour @120fps 63 fps 2030 fps 32x
Pipeline truecolor @120fps 34 fps 931 fps 27x
Emulator-only truecolor 34 fps 2051 fps 60x
7-16x headroom over 120 fps for the heaviest workload (truecolor
full-screen redraws). Static library size 33 MiB -> 13 MiB.
TODO.md baseline numbers updated to reflect post-fix throughput;
the "Debug-mode lib" finding is folded into the result it produced
rather than left as an open item.
Added a full ASCII-video benchmark suite that hammers the renderer
with 30 KiB / 70 KiB full-screen frames at 30, 60, and 120 fps
targets — both renderer-only and full-pipeline (em.Write + renderer
+ stdout). Each stream benchmark reports µs/frame, fps_ceiling, and
percent of the per-frame budget consumed.
The pipeline benchmarks revealed we were missing 120 fps by a wide
margin (190%-350% of budget at 120fps, 60-90 fps ceiling). Isolating
em.Write confirmed libghostty-vt is the bottleneck — 16-29 ms per
truecolor frame, library file at 33 MiB.
Root cause: the Makefile invoked `zig build` with no
-Doptimize, and Zig's standardOptimizeOption defaults to Debug. So
the shipped libghostty-vt was unoptimised. Fixed by pinning
ReleaseFast in the Makefile (override via GHOSTTY_VT_OPTIMIZE for
debug builds of the upstream lib).
Existing checkouts need `make clean-deps && make deps` to pick up
the rebuild.
Live metrics (--profile):
- New metricsTracker instruments OnPTYOut, viewport renderer,
stdout writes, libghostty-vt Write/Title CGO calls, sidebar /
tabbar / status draws (with cache-hit accounting), snapshot
replays, and the chrome ticker (so we can see ticker fires that
did nothing).
- Writes metrics.jsonl (one snapshot per second) and metrics.json
+ summary.txt on exit, alongside the existing pprof files.
- All record* methods are nil-safe so disabled paths pay only a
cheap nil check; counters are atomic so the per-PTY-chunk hot
path stays lock-free.
Benchmark suite (go test -bench=.):
- Three workload fixtures — plain ASCII, SGR-styled lines, and a
ratatui-style cursor-shuffling burst — plus a containsOSC
microbenchmark. Reports ns/op, MB/s, allocs/op, B/op.
- Initial baseline numbers added to TODO under the perf-audit
section, alongside two new findings (renderer allocs ~1 per 4
bytes on styled chunks; styled throughput tops out near
90 MB/s) those benchmarks surfaced.
Codebase sweep for perf issues outside the per-PTY-chunk path that
recent CHANGELOG work already covered. Ten findings under a new
"Perf Audit (auto-generated)" section in TODO.md — anchored to
file:line, classified MEDIUM/LOW, with a sketched fix per entry.
None landed as code changes; review pending.
- Add --debug[=DIR] / --profile[=DIR] flags that write run artefacts
(patterm.log, events.jsonl, per-child raw PTY captures, CPU + heap
+ goroutine pprof) to a dir without polluting stdout/stderr.
- Strengthen vendor-TUI orientation in three places (MCP
initialize.instructions, the spawn_agent tool description, and
help('spawning')) to head off codex's habits of poking the Unix
socket via perl and shelling out to launch peers — both bypass
caller identity and produce orphaned top-level tabs.
- Fix click-and-drag text selection from alt-screen TUIs. Host SGR
mouse reporting now follows the focused child's screen side
instead of being permanently armed; alt-screen TUIs that need
mouse re-enable it themselves and the toggle is forwarded.
- Move drawSidebar() off the per-PTY-chunk hot path. Long claude
session resume was paying a full sidebar rebuild for every
scrolled chunk; the chrome ticker now drains a dirty flag at 60 Hz.
- Gate the per-chunk Title() CGO poll on a containsOSC scan so
codex/ratatui's many SGR-only chunks no longer pay a CGO call each.
- Palette's per-child "Kill <name>" action is now labelled "Close <name>"
(action kind unchanged; still SIGTERM). Matches the existing "Close
agent: …" context entry and reads less violent for a graceful term.
- New "New Terminal" palette entry spawns a bare interactive $SHELL pane
via LaunchTerminal (kind=terminal). Replaces the default "shell"
process preset that was seeded on first run.
- Exited KindTerminal entries are now dropped from the session in
reapChild — terminals have no restart path, so leaving them behind as
greyed rows in the Processes sidebar was just clutter. processList
also filters defensively.
Classifies every running child as idle/working/thinking/permission/error
using one of three pluggable strategies (output_activity,
osc_title_stability, osc_title_status) plus optional regex promoters
applied to the tail of recent output. State and last-match reason are
exposed via MCP on ProcessInfo and get_process_status. Per-preset
configuration lives on a new preset.IdleDetection block with bundled
defaults for the first-party claude/codex/opencode presets.
OSC title plumbing is exposed as Emulator.Title(), polled from the
session pump after each emulator write so title-change activity feeds
into the classifier without an extra cgo callback.
The MCP timer surface expands to match Solo: timer_set,
timer_fire_when_idle_any/all, timer_cancel, timer_pause, timer_resume,
timer_list. timer_wait is now a thin wrapper that shares the same
manager so it shows up in timer_list while pending. Timer bodies are
delivered to the owner process through the existing
InjectAsOrchestrator path. Top-level (non-agent) callers can attach
timers to a specific process via owner_process_id; omitting it grants
universal cancel/pause/resume/list privileges.
The sidebar gains a state glyph per process row and appends a
nearest-timer indicator when one is pending or paused.
Tests: idle_test.go covers the classify() pure function across the
three strategies and regex promotion; timers_test.go covers the
manager. Harness scenarios cover output_activity, osc_title_stability,
osc_title_status, and regex promotion, plus timer_set delivery,
cancel, pause/resume, idle_any-on-transition, idle_all-pending, and
idle_all-already-satisfied. A new wait_until_mcp harness step type
polls an MCP method until an assertion holds.
When opened with Ctrl-K, the palette now prepends entries for whatever
is currently focused:
- Focused scratchpad: Delete / Rename (inline form) / Edit (fire-and-
forget zed launch with stdio detached so the TUI is not suspended).
- Focused agent: Rename (inline form) / Close.
- Focused process: Rename / Delete (drops the entry; SIGKILL if alive)
/ Stop (SIGTERM, keep entry) / Restart (same argv).
The rename UX is a single-field inline form that mirrors the existing
spawn-process form, so the modal-input contract is unchanged.
scratchpad.Store grows Delete / Rename / Path so the palette can act
on a pad file by name. focusedPad is plumbed onto uiState ahead of the
scratchpad-focus UI work; until that lands it stays empty and the
scratchpad-context entries simply never surface.
Tested with palette_context_test.go and a new rename_process_via_palette
harness scenario.
The stdin loop's scratchpad-input branch ran before the palette branch
and silently dropped every byte except a handful of app-level chords,
so palette typing and Esc never reached the palette while a pad was
focused. Skip the pad-input branch whenever st.palette != nil.
closePalette also called repaintFocused() on cancel / no-op action
paths, which paints the empty focused-child slot (focusedID == "" while
a pad is focused) and leaves the palette's top border drawn over the
pad. Route those branches through a restoreView helper that picks
repaintFocusedPad when a pad is focused.
Switching from a pad to a child via the palette now clears the pad
focus and wipes the viewport, matching focusProcess's pad-exit path.
Adds a harness scenario (palette_over_scratchpad) that opens a pad,
opens the palette, types a query, and verifies that Esc leaves the
pad correctly repainted with no palette chrome lingering.
Switches CLI flag parsing from Go's stdlib `flag` to spf13/pflag so
`--project` (and the internal `--socket` / `--identity` / `--scenario`
flags) are the only accepted form; single-hyphen long flags like
`-project` are now rejected. Help output renders the canonical `--`
form.
Adds `patterm --version`, which prints the build version, short commit,
and build date (e.g. `patterm v0.0.1 (commit abc1234, built 2026-05-14)`).
The version string is injected at build time — `make patterm` derives it
from `git describe --tags --always --dirty`, and the release workflow
injects the pushed tag. Commit/date come from the Go toolchain's
embedded VCS info via `runtime/debug.ReadBuildInfo`, so no manual
bumping is required.
Bundles the in-flight work into the first tagged release. See
CHANGELOG.md `[0.0.1] - 2026-05-14` for the full per-change list.
Highlights:
- Sidebar / chrome stability: clamp absolute cursor positioning and
printable bytes to the viewport so long-running TUIs (claude, codex)
can't spray into the right rail; bound tab bar's row clear to the
viewport width so the rail isn't wiped on every tab redraw; flag
scroll escapes (RI/IND/NEL/SU/SD/IL/DL) and clamp `CSI 0/1/2 J`/`K`
to viewport columns.
- Palette: "Spawn process…" form, macros (`sw `, `k `, `sp `), kill
entries mark the focused tab, dead agents drop out of the switch
list.
- Sidebar: split into Processes (session-wide) + Agent Tree
(per-active-agent) sections; relaunch indicator; Ctrl+W/S walks the
combined list, Ctrl+A/D steps tabs.
- MCP: protocol handshake (`initialize`, `tools/list`, `tools/call`,
`ping`), `mcp_injection.kind = cli_override / config_env` so codex
and opencode pick up the server with no file writes, `lifecycle`
help topic and tool-description cleanup-duty pointers.
- Lifecycle: orchestrator-spawned children cascade-killed when the
parent dies; orchestrator-injected prompts end with CR + delayed
Enter so claude submits cleanly.
Add a `lifecycle` help topic spelling out that the caller owns the
processes it spawns and should `close_process` when a sub-agent or
spawned child is no longer needed. The `spawn_agent` and `spawn_process`
descriptions advertised via `tools/list` now restate the same duty
inline (with a pointer to `help('lifecycle')`), so vendor TUIs see the
expectation at the moment they reach for the tool. The `spawning` topic
and `topics` index cross-reference the new content.
Bundles two already-staged improvements that fall in the same area:
- OnChildSpawned primes the snapshot-replay budget for new panes so
diff-based vendor TUIs come up clean without a manual Ctrl+W/Ctrl+S
refresh.
- TODO drops the three items now actioned (prompt-injection preface,
agent cleanup duty, opencode→claude view corruption) and keeps the
unicode `<?>` entry with the investigation notes.
Codex (Ratatui) emits an 8x RI burst on startup right after setting
DECSTBM. RI at the top of the scroll region scrolls the region down,
and DECSTBM only constrains rows -- so the scroll spans every column
and drags the right-rail session-tree entries down with the main pane.
The chrome cache then hid the clobber because the computed sidebar
frame was unchanged.
The viewport renderer now flags any chunk containing RI / IND / NEL /
SU / SD / IL / DL and OnPTYOut drops the sidebar cache when the flag
is set, so the next drawSidebar repaints over the drift.
Adds unit tests for the new flag and a harness regression scenario
(sidebar_survives_ri_scroll) that fails without the fix.
This batches the in-flight [Unreleased] block from CHANGELOG.md into a
single commit. Highlights:
- Real MCP protocol layer (initialize / tools/list / tools/call) so
vendor MCP clients can complete the handshake against the per-PID
socket. Legacy direct-dispatch preserved for the harness.
- New mcp_injection kinds — cli_override for codex, config_env for
opencode — joining the existing env-var and config_file paths so
patterm can slot into more agents without touching their real
config or auth.
- Ctrl+A/D and Ctrl+W/S focus navigation across tabs and intra-tab
process lists, recognised in legacy / kitty CSI u / xterm
modifyOtherKeys encodings.
- Palette macros (sw / k / sp ) and reordering so open sessions
surface above spawn-new entries.
- Two-row tab bar, sidebar/tabbar/status chrome cache, viewport-wipe
on agent spawn, CR-terminated orchestrator injections, and split-
Enter PTY writes so paste-detecting TUIs see Enter as a key event.
Also fixes the bug logged in TODO: claude's Ctrl+O tool-call expansion
emits CSI 0 J, which the viewport renderer was forwarding verbatim —
wiping the sidebar to the right of the cursor and leaving the chrome
cache convinced nothing had changed. CSI 0 J and CSI 1 J are now
translated into per-row ECH sequences clamped to the viewport, same
as CSI 2 J and CSI K already were.
Agent guides (CLAUDE.md / AGENTS.md) now spell out the
TODO->CHANGELOG workflow so completed items land in the changelog
rather than as ticked entries left behind in TODO.
Module renamed github.com/harrybrwn/patterm → github.com/hjbdev/patterm
across imports.
Chrome:
- Palette redrawn with rounded box-drawing borders, accent left-bar
for the selected item, dim hints, and a separator-aware footer.
- Tab bar grew from 1 row to 3: labels with breathing room, a dim
argv subtitle truncated to each tab's width, and an accent thick
underline for the focused tab with a faint divider extending across
the rest of the host width. Layout, viewport-renderer, and screen-
renderer tests updated for the new mainTop.
- Sidebar reuses the same palette: accent section headers, `▎`
selection marker, `●`/`○` status glyphs, dim previews.
- Shared SGR constants moved into internal/app/style.go.
Palette input:
- Adjacent duplicate arrow events (legacy `\x1b[B` + kitty
`\x1b[57353u` for one keypress, or two of the same form) are now
collapsed via peekArrowEvent + chunk-level dedupe in processStdin.
- On open, push `\x1b[>0u` onto the host's kitty keyboard stack so
palette input is in plain legacy mode regardless of what the child
pushed (codex/ratatui pushes its own flags which had been leaking
to the host). Popped on close.
Tab-switch repaint (repaintFocused):
- Use the emulator's SerializeVT bytes (with SGR / cursor / DECSTBM
/ tabstops) instead of plain text, fed through the per-focused
viewport renderer so the shifter translates row positions.
- Prelude resets host SGR / DECOM / DECSTBM (pinned to viewport) /
cursor visibility before the replay, so leftover modes from the
previously-focused child don't distort the new snapshot.
- Re-emit the saved cursor as a child-space CUP after the
serialized bytes so the host cursor lands at the emulator's
actual position (overriding DECSTBM's home side-effect and the
tabstop-setup CHA sequences) AND the renderer's vr.row/vr.col
get re-synced via trackCSI.
- cursorShifter now carries childRows and rewrites empty
`\x1b[r` to `\x1b[<mainTop>;<mainBottom>r` (host coords) — the
default (1,1) shifted to (4,4) was producing a one-row scrolling
region that scroll-exploded the replay.
- After the snapshot lands, nudge the focused child with a one-row
PTY winsize toggle so the kernel emits SIGWINCH and ratatui-style
TUIs throw away their diff state and emit a fresh frame.
Codex still renders incorrectly after a focus switch; see TODO.md
"Switch-back render divergence" for the deep investigation handoff.
Codex (and other ratatui-based children) pushes kitty keyboard flags
onto the host terminal, so Ctrl-K arrives as `\x1b[107;5u` instead of
0x0B and the palette open never fired. With "report event types" also
on, the release event `\x1b[107;5:3u` followed the press and tripped
the palette's "unknown ESC sequence → cancel" branch, making the
palette flash and close.
Add a small CSI scanner / kitty CSI u decoder and use them in two
places: matchCtrlK now accepts the legacy byte, the kitty CSI u form,
and xterm modifyOtherKeys; the palette's input handler consumes whole
CSI sequences, ignores non-press events, and decodes Enter/Esc/
Backspace/arrows/Ctrl-U-N-P in their kitty forms. Ctrl-K Ctrl-K
forwards the raw matched bytes so nested TUIs that asked for kitty
input still receive kitty input.
Rename list_children/read_output/kill/send_message_to to their SPEC §7
process_id-shaped names; drop report_to_parent (direction inferred by
send_message) and policy_check (replaced by per-project trust gating).
Add the SPEC's missing tools: start_process, restart_process,
close_process, rename_process, select_process, get_process_status,
get_project_status, get_process_raw_output, search_output,
get_process_ports, whoami, help.
Process model now distinguishes agent/terminal/command kinds with
opaque p_<6hex> IDs. Command entries are session-persistent so they
survive PTY exit and can be Restart'd. Status enum gains starting and
stopped. screen_version, port detection, and bracketed-paste send_input
land alongside.
Trust gating (internal/trust) replaces the regex policy: command-preset
spawns return needs_trust on first use; the user confirms in a
status-line modal and the grant persists to
\$XDG_DATA_HOME/patterm/projects/<key>/trust.json.
Tests cover send_message direction inference (parent↔child, sibling
rejection, nil caller paths) and trust grant persistence across reopen.
Replaces the original child_id-keyed tool set with a soloterm-inspired
process-entry model: opaque process_ids, three kinds (agent/terminal/command),
session-persistent command entries with disk-persisted trust grants, and a
single bidirectional send_message in place of the send_message_to /
report_to_parent split. Adds whoami, help, get_project_status, rename_process,
select_process, close_process, search_output, get_process_ports, and a richer
send_input with key/paste support and optional wait_ms tail. Updates §3
(trust.json), §8 (self-discovery via whoami/help), §9 (renamed tools in the
permissions loop), §11 (idle exposed via list_processes), §14 (resolves the
scratchpad-revision and trust-persistence questions, opens content-hashed
trust), and §15 (build-order tool names).
