|
| 1 | +# Instant home prompt and early input at startup |
| 2 | + |
| 3 | +## Identity |
| 4 | + |
| 5 | +- Status: active |
| 6 | +- Integration branch: `dev-nowaker` |
| 7 | +- Development branch(es): `provisional-prompt` (also the upstream PR head, `0dae58048c`); landing branch `provisional-prompt-land` |
| 8 | +- First local commit: `b12845f999` (cherry-pick of `0dae58048c`) |
| 9 | +- Current local commit(s): `b12845f999` |
| 10 | +- Upstream base when introduced: `ecc4916b5a` (upstream `dev`, `provisional-prompt`); `dev-nowaker` stays on `907b3bc518` |
| 11 | +- Last checked against upstream: `ecc4916b5a` (upstream `dev`) |
| 12 | +- Upstream: issue [#53696](https://github.com/anomalyco/opencode/issues/53696), PR [#53698](https://github.com/anomalyco/opencode/pull/53698) |
| 13 | + |
| 14 | +## Original request |
| 15 | + |
| 16 | +Relayed by coordinator `ses_ef8235798ffejGr4sa22eXmVNv` (item 19), quoting the |
| 17 | +user: |
| 18 | + |
| 19 | +> additionally, as a tui feature, default on - both for regular tui, and it's |
| 20 | +> super minimal alternative version - is to start accepting stdin as early as |
| 21 | +> possible; basically even if it's black loading screen, the stdin will be sent |
| 22 | +> to the prompt window (except for enter hit, enters should not perform a |
| 23 | +> submission and be dropped; shift+enters for line breaks totally fine). |
| 24 | +> |
| 25 | +> and also separately, a totally new feature - opencode provisional prompt |
| 26 | +> screen. basically like a replica of our vibeterm loading screen where we can |
| 27 | +> start prompting FAST, without having to wait for opencode to parse all its |
| 28 | +> configs, all agents, plugins etc. |
| 29 | +
|
| 30 | +> and prompt draft fields, both two screens, must react to mouse clicks for |
| 31 | +> caret movement, and the field itself must implement basic terminal things |
| 32 | +> like home, end keys, ^w, ^u etc. |
| 33 | +
|
| 34 | +The full brief also asks for a 0.2 s budget on desktop, m4max and m2pro, layout |
| 35 | +rules shared through a constants-only module, no SQLite on the loading path, a |
| 36 | +cache keyed by the database location, the caret kept across the handover, and |
| 37 | +white "still loading" / red "changed" notices for Enter during loading. |
| 38 | + |
| 39 | +## Goals |
| 40 | + |
| 41 | +- `opencode` paints the home screen (logo, prompt with the cached agent, model, |
| 42 | + variant and colors, shortcuts, cwd, version, a Loading spinner) within about |
| 43 | + 50 ms and is typable by about 70 ms. |
| 44 | +- The prompt edits like the real one: every `input_*` keybind with `tui.json` |
| 45 | + overrides, word wrap, click and drag, paste, undo. |
| 46 | +- Text, caret and selection hand over exactly to the real home prompt. |
| 47 | +- Enter while loading queues the submit. The queued submit goes through once |
| 48 | + the TUI loads, but only when agent/model/variant match the cache; otherwise a |
| 49 | + red notice asks for Enter again. |
| 50 | +- `--mini`, and the TUI with `startup.instant_prompt: false`, capture keys |
| 51 | + invisibly (`startup.early_input`), dropping an Enter typed before raw mode. |
| 52 | + |
| 53 | +## Non-goals |
| 54 | + |
| 55 | +- Existing sessions (`-c`, `-s`) and `--prompt` still start as before; stage 2 |
| 56 | + of item 19 covers the session loading screen. |
| 57 | +- Project-level `tui.json` files are not read by the loading screen; they apply |
| 58 | + once the TUI loads. |
| 59 | + |
| 60 | +## Rationale and constraints |
| 61 | + |
| 62 | +- The main thread cannot service stdin while it evaluates the CLI's module |
| 63 | + graph (0.3-1.7 s blocked on desktop), so a worker thread reads and paints |
| 64 | + keys until the renderer takes over. |
| 65 | +- The component tree renders nothing until the SDK, sync and theme providers |
| 66 | + load. The renderer phase therefore draws the frame from a box on the |
| 67 | + renderer root, not from a component. |
| 68 | +- The cache sits beside the resolved database (`<db>.tui-startup.json`), so |
| 69 | + `OPENCODE_DB`, data directories and channels never share it; the loading path |
| 70 | + never opens SQLite. |
| 71 | +- Draft persistence stays in Vibeterm (item 16): the early text is claimed in |
| 72 | + the prompt's `onMount`, before `handoff.ready`, so a restored orphan draft |
| 73 | + never overwrites it. |
| 74 | +- Rejected: reading stdin on the main thread between imports. Measured key |
| 75 | + latency was 0.6-1.7 s. |
| 76 | + |
| 77 | +## Changes |
| 78 | + |
| 79 | +| Commit | Workday | Change | Stable seam | |
| 80 | +|---|---|---|---| |
| 81 | +| `b12845f999` | 2026-10-06 | Instant home prompt, early input, startup cache, `startup.*` settings | `packages/opencode/src/boot.ts` and `script/build.ts` entrypoints (`OPENCODE_INSTANT_WORKER_PATH`); `packages/tui/src/instant/*`; `InstantPrompt.handover()` before `createCliRenderer` in `packages/tui/src/app.tsx` and `src/cli/cmd/run/runtime.lifecycle.ts`; `InstantPrompt.claim()` in `Prompt` `onMount` and `footer.prompt.tsx` `bind`; `component/instant-screen.ts`; `packages/tui/src/layout.ts`; `config/keybind-definitions.ts`; `core/src/global-path.ts`; `core/src/database/location.ts`; `Startup` in `config/index.tsx`; `test/instant/*` | |
| 82 | + |
| 83 | +## Verification |
| 84 | + |
| 85 | +- `bun typecheck` in `packages/core`, `packages/tui`, `packages/opencode` on |
| 86 | + `provisional-prompt-land`; `bun test` in `packages/tui`: 317 pass, 0 fail. |
| 87 | +- `test/instant/editor.test.ts` runs every editing action from every caret |
| 88 | + position through the instant editor and opentui's `TextareaRenderable` and |
| 89 | + requires identical text, caret and selection; also wrap and caret placement. |
| 90 | +- Manual surface, isolated `XDG_*` and tool/plugin data dirs, throwaway tmux |
| 91 | + socket `iso19`: |
| 92 | + - Instant frame vs loaded TUI: identical rows and colors with a warm cache. |
| 93 | + On a cold cache the frame lacks the model line and the prompt's bottom |
| 94 | + edge, but its rows are aligned. |
| 95 | + - `hello world`, three Left keys, `X`, a click on the second cell and `Y` |
| 96 | + before load show `hYello woXrld`, and the caret carries over; `Z` after |
| 97 | + load gives `hYZello woXrld`. |
| 98 | + - Enter during load: the white notice, then a submit after load. With the |
| 99 | + cache edited to another model: the red notice, then a submit on Enter |
| 100 | + again. |
| 101 | + - Ctrl+C on an empty prompt during load exits with `icanon echo` restored. |
| 102 | + - `--help`, `models`, a missing project directory, `--mini` (caret kept) |
| 103 | + and `startup.instant_prompt: false` all behave as described. |
| 104 | + - The process exits when its tmux server is killed at any time from 0.1 to |
| 105 | + 20 s after launch. |
| 106 | +- Time to typable (pty harness `tmp/latency.py` in the worktree, plus |
| 107 | + opencode-idle-bench `ttp --pure`): |
| 108 | + - desktop (load ~27): 114 ms median, against 4778 ms for `1.18.34-vt-136` |
| 109 | + - m2pro: 72-74 ms, 139 ms on a fresh data dir |
| 110 | + - m4max: 71-73 ms, 131 ms on a fresh data dir |
| 111 | + |
| 112 | + Keystroke-to-screen (`capture-pane` polling) is about 10 ms median, worst |
| 113 | + 83-138 ms, at the handover. |
| 114 | + |
| 115 | +## Timeline |
| 116 | + |
| 117 | +- 2026-10-06 |
| 118 | + [`ses_eebf9a83fffeIQQwW9gVFo5jaO`](../sessions/2026-10-06-tui-instant-prompt.md) |
| 119 | + - `b12845f999`: introduce; upstream issue #53696 and PR #53698; build and |
| 120 | + install on desktop and m4max (`1.18.34-vt-144-907b3bc518`). |
| 121 | + |
| 122 | +## Current maintenance notes |
| 123 | + |
| 124 | +- Drop the fork commit once PR #53698 (or an equivalent) is in upstream `dev`. |
| 125 | +- An upstream bump must check the following: |
| 126 | + - `createCliRenderer` options in `app.tsx` and `runtime.lifecycle.ts` still |
| 127 | + let `handover()` run first and `prependInputHandler` feed the instant |
| 128 | + editor. |
| 129 | + - opentui's `TextareaRenderable` actions still match: the |
| 130 | + `test/instant/editor.test.ts` parity test fails if they drift. |
| 131 | + - The home layout in `routes/home.tsx`, the `Prompt` box structure and the |
| 132 | + home footer/tips plugins still read `layout.ts`. |
| 133 | +- Vibeterm's own provisional loader for new-session tabs is being made aware of |
| 134 | + this screen in item 19b (`ses_eeadda349ffep0Jwwis5g1DJXi`, opencode-tools). |
| 135 | + |
| 136 | +### Upstream integration checklist |
| 137 | + |
| 138 | +- Locate each stable seam in the new upstream tree. |
| 139 | +- Classify the customization as preserved, conflicted, superseded, or removed. |
| 140 | +- Reverse any deliberate uncommitted patch before merging, then reapply its |
| 141 | + canonical patch afterward. |
| 142 | +- Regenerate derived clients or schemas instead of editing generated files. |
| 143 | +- Run the feature's focused tests and affected package typechecks. |
| 144 | +- Build through the host's canonical installer and verify the installed binary. |
| 145 | +- Confirm protected services kept the same PID and start timestamp. |
| 146 | +- Link a new timeline row to the current session record. |
| 147 | +- Update `Last checked against upstream`. |
0 commit comments