feat(tui): opt-in dev reload that restarts the TUI in place - #700

Builds on #669 (merged), which freed ctrl+r: before it, the line editor's plain r also fired on ctrl+r.

Why

To pick up a code change while working on the TUI, you had to quit and then redo any unsaved setup and navigation by hand. That's slow when you keep separate windows for plain and powerline setups.

Usage

CCSTATUSLINE_DEV_RELOAD=1 bun run start --config /tmp/ccstatusline-plain.json

The header shows dev reload: ctrl+r. Press ctrl+r to restart on the latest code exactly where you were. The --config file is optional; it just keeps each window's saved setup separate from your real config.

How it works

• Supervisor. With the variable set, bun run start becomes a small supervisor. It relaunches the same command (runtime, script and original arguments) as a child process, and the child runs the TUI.
• ctrl+r writes a snapshot to a file in a private (0700) temp directory that each supervisor run creates for itself, so a TUI never restores a snapshot left by an earlier run or planted by another user, and exits with code 75 (EX_TEMPFAIL). The supervisor then starts a fresh process, which resumes from the snapshot. The snapshot holds:
  • the unsaved settings
  • the original settings, so the unsaved-changes state and ctrl+s behave as before
  • the current screen, selected line, menu positions, and line editor cursor
• Restoring screens. Screens that only need that data restore in place: main, the line selector and editor, colors, terminal options, global overrides, and powerline. Screens with flow state of their own (confirm dialogs, install and update, import and export) resume on the main menu. An open sub-editor isn't restored; you land on its widget in the line editor.
• Validation. Settings in the snapshot are re-validated against the schema, because the reload may have changed it. A corrupt or invalid snapshot means a normal start.
• Broken code. If the new code fails to start, which happens when you reload mid-edit, the supervisor prints Reload failed (exit N). Fix the code, then press Enter to retry, or q to quit. and keeps the snapshot.
• Exit. A normal exit (ctrl+c or the Exit menu) ends the supervisor and removes the snapshot directory. If the supervisor itself is sent SIGTERM, SIGINT or SIGHUP (kill, or closing the terminal), it passes the signal on to the TUI, waits for it, removes the directory and exits with 128 + the signal, so no TUI is left running on its own.

Without the variable nothing changes: no supervisor, no key, and no header note. The module is only loaded through a dynamic import in the interactive branch. The status-line render path loads the same code as before, about 0.7 KB more for the environment check in the entry.

ItemsEditor gains optional initialSelectedIndex and onSelectedIndexChange props, so the cursor survives a reload. Entering a line still starts at the top, as before.

Update: Drop the snapshot once the settings file is written

• Retrying after a crash no longer brings back settings from before a save. The supervisor hands every TUI it starts the same snapshot path, including the one it relaunches after "Reload failed". Until now only ctrl+r wrote that snapshot, and nothing ever removed it. So with ctrl+r, then a save, then a crash, the retry restored the pre-save settings along with the pre-save original. Deleted widgets came back, Save & Exit was offered for changes that didn't exist, and the next save wrote the older settings over the newer file. Now App deletes the snapshot through a new discardDevReloadSnapshot in src/utils/dev-reload.ts whenever originalSettings changes after the first load. After that load, it only changes once the settings file has been written: ctrl+s, Save & Exit, or an install, update or uninstall recording itself. One effect covers all of those writes without touching each save path, so the change stays inside the dev reload code. A retry after a write loads the file. A crash before any write, which is the case the retry exists for, still resumes from the snapshot on the same screen.

Demo

Update

Dev reload (CCSTATUSLINE_DEV_RELOAD=1) on the demo's default four-widget line, with sample data only. The flow: delete Git Changes, ctrl+r, delete Git Branch, ctrl+s, then the TUI is killed to stand in for a crash and Enter at "Reload failed" retries. Before, the retry reopens on Edit Line 1 with Git Branch back, and the main menu offers Save & Exit for changes that were already saved. After, it opens the saved line (Model, Context Length) on the main menu with nothing unsaved.

Powerline, before and after:

Plain, before and after:

Testing

• Unit tests:
  • mode detection from the environment
  • the supervisor loop with a fake launcher: reload relaunches, a normal exit stops and cleans up, a crash prompts with retry or quit
  • snapshot round-trip, unrestorable and unknown screens going to main, and missing, corrupt or invalid snapshots giving a fresh start
• An Ink test for the line editor's cursor props.
• bun test: 3075 pass. bun run lint: clean.
• Manual run in tmux, end to end:
  • an unsaved change on the line editor's first widget plus ctrl+r gives the same screen, cursor and change, and the main menu still offers "Save & Exit"
  • editing the Model widget's preview text plus ctrl+r makes the new text show up
  • a syntax error plus ctrl+r shows Bun's error and the retry prompt; fixing it and pressing Enter goes back in place
  • ctrl+c exits the supervisor with 0 and removes the snapshot
  • SIGTERM to the supervisor (Bun, and the built dist/ under Node) exits with 143 and leaves no TUI process or snapshot directory; the same at the retry prompt; closing the tmux session (SIGHUP) leaves nothing behind
• Tests for the private snapshot directory (a file planted at the old fixed path isn't restored; the directory is 0700, new per run, and removed) and for passing SIGTERM, SIGINT and SIGHUP on to the TUI
  • without the variable, there's no header note and ctrl+r does nothing
• On today's main: the built CLI's plain and Powerline renders match main under Bun 1.4.2 and Node 26.10.0, and ctrl+r driven in tmux under both replaces the TUI process and resumes on the same line editor widget.

Update:

• New test in src/tui/__tests__/App-dev-reload.test.ts: 'keeps the snapshot for a crash after the reload, but drops it once the settings are saved'. It starts from a snapshot, checks the snapshot survives the load, presses ctrl+s and checks it is gone. Without the fix it fails at that last step. With the fix deliberately changed to drop the snapshot on the first load, both this test's first assertion and the existing resume test fail. The file's beforeEach now also points CLAUDE_CONFIG_DIR at the temp dir, because a save syncs widget hooks into Claude Code's settings.
• bun test (scratch HOME and CLAUDE_CONFIG_DIR): 3189 pass, 0 fail, 9144 expect() calls across 180 files.
• bun run lint: exit 0 (tsc --noEmit and ESLint with --max-warnings=0).
• Node v26.10.0, node node_modules/vitest/vitest.mjs run src/tui/__tests__/App-dev-reload.test.ts src/utils/__tests__/dev-reload.test.ts: 2 files, 20 tests passed.
• Manual run of the real supervisor in a PTY under Bun, with scratch HOME, CLAUDE_CONFIG_DIR and TMPDIR. Steps: ctrl+r, a save, then SIGKILL of the TUI, then Enter at the retry prompt. The TUI reopened on the saved file with no stale widget and no Save & Exit, and the file on disk was unchanged. With the same steps but no save, the TUI still resumed on Edit Line 1 with the unsaved edit.
• Demo recorded with VHS from this branch and from the previous tip, in both Powerline and plain mode.