xonecas.io
64875
Mc

mini-coder / commit 6ede917

docs: capture vnext direction

xonecas2026-07-31 6ede9179492637a24d1c9ce98ea18dbc35a41fb7 parent c1b6a41

2 files changed

TODO.md+35−8
@@ -4,13 +4,40 @@
44
55 ## TODO
66
7-- [ ] Replace the custom spinner and always-on render loop with cel-tui's managed `Spinner` or `createTicker`.
8-- [ ] Replace the custom select overlay state and input handling with cel-tui's `Select`.
9-- [ ] Refactor tool-call TUI items so running, completed, failed, and aborted calls are unambiguous.
10-- [ ] Show provider-reported usage in the TUI rather than recomputing estimates on each message or tool stream event.
11-- [ ] Path autocomplete in TUI — `Tab` on file paths opens path picker.
12-- [ ] Status bar richness — detailed git counts (staged/modified/untracked/ahead/behind).
7+This prototype version has lived it's course, and I've extracted the insights I wanted from it.
8+In addition to the insights from using this prototype, this feedback also stems from using other coding agents extensively over the past few months. These include Pi Coding Agent, Opencode, Claude Code, Cursor and Codex CLI.
139
14-## Low priority / future enhancements
10+I'm just going to dump all my thoughts into this file, and we can format and structure it with agents.
1511
16-- [ ] List virtualization — adopt cel-tui's `VirtualList` for conversation history if long-session rendering becomes a measured problem.
12+One big takeaway was Pi's "extensible software" foundation, this is amazing and there is a lot of value in putting extensibility first (I even authored and compiled my extensions into a repo ../pi-extensions)
13+
14+Using pi-ai is a great decision, and allows us to mostly ignore provider differences. But as providers continue to iterate on the format of their apis and difer more and more, this might become a limitation.
15+One thing that keeps coming up in my mind is what would an extensible provider api/library would look like. Maybe it could provide the separate building blocks and allow library consumers to assemble them for any provider? I'm not sure about this, but as things evolve, this might be a big deal for mini-coder. (context, a blog post about provider divergence from the pi team: https://earendil.com/posts/session-portability/). Another thing I would have done different would be to flatten the content …
16+
17+Pi won it's place as my main choice, mostly because I was able to bring my prefered features with extensions without much effort. It also feels the best to me, it's minimal system prompt allows for all sorts of tasks, from educational requests to generic Chatbot uses with custom prompts. I've noticed that the heavier the system prompt, the less versatile the coding agent feels to me.
18+
19+Opencode has the best UX and UI, feels modern and nice to use. It's miles ahead of any other terminal coding agent user experience. Pi, Claude Code and Codex all fall short when compared to Opencode's UI. The downside is that the agent implementation of Opencode is very opiniated and while there are plenty of nobs to tweak via configs, it still feels more constrained than using Pi (which is minminal even in it's agent implementation). Claude Code and Codex feel nice with their respective models, …
20+
21+Claude Code, Codex and Cursor are all things I use in a working context (not on this machine). And my feedback about them is mostly negative. All of them hide/mask agent actions, have every feature you can think of, even the ones that might not be the best choices (reasoning summaries instead of traces, generic "subagent is doing things" outputs, server side compaction, and other are examples of patterns that hide agent behaviour from the user).
22+
23+Current mini-coder is not really an enjoyable experience, the app stalls with no UI messaging, there is no logs or telemetry to debug when something doesn't work, the whole UX doesn't feel good, and the input editor is very limitted.
24+
25+Local AI is emerging, I myself am waiting to receive a NVIDIA Spark to run local models at home. Most coding agents support local llms, mostly, but none feels first class and all require verbose configs. It would be a good niche for mini-coder to have first class support for ollama/llama.cpp at least. Maybe the idea of a modular provider api can be applied here too? As part of this I explored what a local AI first agent would look like in ../feather . And the biggest feedback out of it, is that …
26+
27+The features I think fit my idea for mini-coder, and should be part of the core:
28+
29+- Elegant and polished UI, with transparency and readability first. Not noise or spam. First class editting in the prompt input. UI to customize settings, with reasonable defaults.
30+- base agent abilitites on par with Pi, as in: a simple set of tools, compaction to protect context window busts, minimal system prompt, skills support and prompt templates. Context files support AGENTS.md/CLAUDE.md
31+- Opencode style custom agents/subagents, where the model/effort and prompt can be customized and then invoked by the main llm (for example the adversary pi extension I use, or the same for the opencode config).
32+- Extensibility, with agents this is critical so users can add/remove to their wishes.
33+- Agents docs with the coding agent harness: this is awesome, being able to say "help me add X to pi/opencode" is quite the powerful UX.
34+
35+Some words about cel-tui, we made it for mini-coder, and it's a full agent authored spec driven implementation (probably the reason I dislike spec driven projects). It's a good library, and has been dependable and performant, but putting favoritism aside and considering other TUI implementations might be healthy, even if it's to take insights to improve cel-tui. Keep in mind that it's quite cumbersome to iterate over cel-tui, as all changes require a billion edits in specs, docs and code, and if …
36+
37+I'm not sure how to further spec this out, I don't really want to write a massive spec file that becomes a maintenance chore and might contradict with the code or tests. Between the current main branch prototype and the two archived implementations, there is a lot to infer from, both correct and wrong, so I'm weary of just pointing agents to those. Same with the feather code, it has it's downsides.
38+
39+Typescript lessons: I didn't like typebox, and I'm overall pretty tired of typescript types. I'm open to suggestions here, but I'm starting to think that typescript is 90% validating types and avoiding `any`... So a mature type handling dependency might go a long way. Other than that, dependencies need to be considered very carefully, supply chain attacks are more common now, and it's likely going to keep increasing.
40+
41+We don't have pressure, neither time or user pressure at all. The current version is stable, and to be honest I don't think anyone uses mini-coder as their main agent. Even me, I mostly use it as a consistent base for benchmarks, since other harnesses keep getting updates mid benchmarks! This to say, if the correct implemtation requires a lot of work and might take a long time, that is ok. I rather go slow and correct, than to make more design mistakes or introduce bad code/technical dept.
42+
43+next version will kick off whatever direction we ended deciding from this wall of text I call feedback :)
docs/vnext-direction.md+489−0
@@ -0,0 +1,489 @@
1+# mini-coder vNext direction
2+
3+This document captures the product direction and path forward derived from the
4+user's brain dump in [`TODO.md`](../TODO.md), discussion about it, repository
5+history, the archived mini-coder implementations, Feather, Pi extensions, and
6+OpenCode usage.
7+
8+It records intent, decisions, and decision gates. It is deliberately not a
9+complete implementation specification. Code, tests, focused acceptance journeys,
10+and short decision records should remain the detailed sources of truth as vNext
11+evolves.
12+
13+## Product statement
14+
15+mini-coder should be a transparent, extensible terminal coding agent with an
16+excellent input experience, a small auditable core, first-class local and hosted
17+model support, and sessions that remain intelligible and owned by the user.
18+
19+Local and hosted models are peers. Local support should not be a separate or
20+reduced edition, while hosted-provider support should not force local users
21+through verbose cloud-oriented configuration.
22+
23+## Product character
24+
25+mini-coder should combine:
26+
27+- Pi's small agent core, minimal system prompt, versatility, and extension-first
28+ philosophy.
29+- OpenCode's attention to terminal UX and presentation.
30+- Locally owned, readable sessions and transparent agent behavior.
31+- First-class local-model onboarding and context management.
32+- A dependency and maintenance surface small enough for a hobby project to
33+ understand and sustain.
34+
35+Transparency does not require showing every event at full volume. The default UI
36+may summarize information to remain readable, but model requests, reasoning made
37+available by the provider, tool activity, compaction, delegation, errors, and
38+other meaningful work must be visible or directly inspectable. The application
39+must not replace concrete activity with generic messages such as "a subagent is
40+doing things."
41+
42+## Lessons from previous implementations
43+
44+The repository history contains several useful experiments:
45+
46+1. The original implementation owned substantial provider and terminal behavior.
47+ It became expensive to maintain alongside the actual agent.
48+2. The 0.5 implementation adopted pi-ai and cel-tui, but accumulated a broad
49+ feature set and a detailed specification that was costly to keep synchronized
50+ with the code.
51+3. The current prototype recovered a small and understandable core, but removed
52+ too much product structure around observability, editing, extensibility,
53+ provider-neutral presentation, and durable session semantics.
54+4. Feather demonstrated useful local-provider, append-only session, and terminal
55+ ideas. It also showed that owning providers, tools, sessions, context, and the
56+ TUI while avoiding runtime dependencies creates a large maintenance surface of
57+ its own.
58+
59+vNext should therefore not begin as another comprehensive spec-driven rewrite,
60+and it should not grow by attaching features directly to the current mutable TUI
61+state. It should proceed through measured decisions and narrow vertical slices.
62+
63+## Confirmed decisions
64+
65+### Model support
66+
67+Local and hosted providers are equal product paths.
68+
69+The local path should eventually provide straightforward endpoint discovery,
70+health reporting, model discovery, capability and context-window information,
71+and useful defaults for at least Ollama and llama.cpp. It should not require users
72+to reproduce an entire provider model record for a normal setup.
73+
74+### Initial extension surface
75+
76+The first extension API should focus on three demonstrated needs:
77+
78+- tools,
79+- commands,
80+- custom agents.
81+
82+Provider plugins, arbitrary lifecycle hooks, and custom TUI components should not
83+be included until a concrete extension requires them.
84+
85+Extensions are trusted in-process code. mini-coder should state that plainly
86+instead of presenting an application-level plugin permission system as a
87+security boundary.
88+
89+### Initial editor scope
90+
91+The first editor should target ordinary notepad-level input rather than Vim,
92+Emacs, or readline parity.
93+
94+The initial scope is:
95+
96+- multiline insertion and deletion,
97+- predictable cursor movement across lines,
98+- normal selection and clipboard-oriented editing supported by the chosen TUI
99+ and terminal,
100+- reliable typing, deletion, newline handling, and large paste handling,
101+- draft preservation when opening and closing UI controls,
102+- a clear way to attach text files and supported images.
103+
104+The initial scope explicitly excludes:
105+
106+- Vim or Emacs modes,
107+- undo and redo,
108+- persistent input history,
109+- prompt history search,
110+- general filesystem path completion.
111+
112+File attachments are required even though general path completion is deferred.
113+The attachment interaction can be purpose-built rather than making a complete
114+path-completion system a prerequisite.
115+
116+### Diagnostics and telemetry
117+
118+vNext should provide local diagnostics for development and dogfooding. No usage,
119+prompt, error, or performance telemetry should be sent remotely.
120+
121+Local diagnostics should make startup, provider requests, agent phases, tool
122+execution, rendering, cancellation, and failures traceable. Secrets and prompt or
123+tool content should be excluded or redacted by default, with more detailed local
124+logging enabled explicitly when needed.
125+
126+Future opt-in user telemetry is not ruled out. The initial implementation should
127+keep diagnostic event production separate from its local storage or display, but
128+should not build a generalized telemetry platform before another sink exists.
129+
130+### Repository and release strategy
131+
132+The current main branch should be preserved in a new archive branch before vNext
133+work changes it substantially.
134+
135+After that archive exists, vNext may replace the current implementation on main
136+or reuse useful pieces. This should be decided from evidence rather than assuming
137+that either a clean rewrite or incremental migration is inherently better.
138+
139+vNext will not be published to npm until it provides a better overall experience
140+than the currently published version. The archived version remains the behavioral
141+and benchmark baseline during development.
142+
143+## Architectural direction
144+
145+These are starting constraints to validate through the first vertical slice, not
146+a prescribed file tree.
147+
148+### Owned application model
149+
150+pi-ai remains the initial provider implementation, but mini-coder should translate
151+its messages and stream events once at a narrow adapter boundary.
152+
153+The rest of the application should consume small mini-coder-owned values for:
154+
155+- readable user and assistant content,
156+- reasoning content when a provider exposes it,
157+- tool calls and arguments,
158+- tool progress and results,
159+- usage,
160+- model and provider identity,
161+- stop reasons, cancellation, and errors.
162+
163+Presentation code should not repeatedly inspect pi-ai content unions. Provider
164+metadata may be retained as an optional sidecar for same-provider continuation,
165+but it must not be the only carrier of session meaning.
166+
167+A separate modular provider library should remain a research topic until concrete
168+provider divergence demonstrates that pi-ai plus a narrow adapter cannot satisfy
169+mini-coder. vNext should not depend on solving a universal provider abstraction
170+first.
171+
172+### User-owned sessions
173+
174+The local session record should be canonical, readable, versioned, and append-only.
175+It should retain enough normalized information for another model or provider to
176+understand and continue the work without dereferencing provider-owned state.
177+
178+Durable records should include meaningful completed events such as messages, tool
179+calls and results, cancellations, compaction summaries, model changes, and
180+subagent lineage. High-frequency streaming deltas can remain transient.
181+Provider-specific opaque data may be preserved as optional metadata, never as the
182+sole readable record.
183+
184+This follows the session-portability principle that local applications should own
185+an intelligible transcript:
186+<https://earendil.com/posts/session-portability/>.
187+
188+### Distinct state boundaries
189+
190+The application should distinguish:
191+
192+1. **Session history** — the durable semantic record of what happened.
193+2. **Live run state** — waiting, streaming, running a tool, cancelled, or failed.
194+3. **Diagnostic events** — timings and implementation details used to investigate
195+ failures and stalls.
196+
197+The TUI and headless modes should be projections of the same application events.
198+Neither should own agent semantics or provider message conversion.
199+
200+### Transparent custom agents
201+
202+A custom agent should be a configuration over the same agent runtime, with at
203+least:
204+
205+- a name and description,
206+- model and reasoning effort,
207+- its own prompt,
208+- an allowed tool set.
209+
210+The main agent can invoke it through one explicit delegation tool. A delegated run
211+should have isolated context and durable lineage. The UI should show the selected
212+agent and model, current action, elapsed state, final result, and a directly
213+inspectable child transcript.
214+
215+The core should not automatically delegate work or hide child prompts and actions.
216+The existing Exa and adversary extensions are useful acceptance cases for the
217+extension API: one ordinary streaming tool and one tool backed by an isolated
218+agent.
219+
220+### TypeScript and runtime validation
221+
222+Bun and TypeScript remain the preferred implementation environment for vNext.
223+Changing language would discard too much validated provider, extension, and TUI
224+work without addressing the main product problems.
225+
226+TypeScript types should remain local and plain. Runtime schemas should be used at
227+actual trust boundaries such as settings, session records, extension manifests,
228+provider payloads, and tool arguments. A validation dependency should be selected
229+through a small trial against real boundary data, based on readable code, useful
230+errors, package maturity, dependency surface, and JSON Schema interoperability.
231+It should not spread schema-derived types through every internal operation.
232+
233+## TUI and conversation model decision spike
234+
235+Both major conversation models remain open:
236+
237+### Full-screen conversation
238+
239+Potential benefits:
240+
241+- completed and historical rows can be updated or expanded in place,
242+- overlays and rich navigation fit naturally,
243+- the application controls a consistent polished layout,
244+- tool calls and subagents can retain live structured rows.
245+
246+Costs to measure:
247+
248+- long histories require correct virtualization or another bounded rendering
249+ strategy,
250+- terminal-native selection and scrollback may be harder,
251+- resizing, alternate-screen recovery, and rendering bugs become application
252+ responsibilities,
253+- the UI can obscure activity if its state and event handling stall.
254+
255+### Append-only conversation with a bounded live region
256+
257+Potential benefits:
258+
259+- the terminal emulator owns durable scrollback, selection, and much scrolling,
260+- completed output does not need to be continuously rerendered,
261+- memory and rendering work can remain bounded,
262+- terminal history remains available naturally after the application exits.
263+
264+Costs to measure:
265+
266+- committed rows cannot be freely updated in place,
267+- in-flight tool and assistant output need a carefully bounded live area,
268+- overlays and navigation may interact awkwardly with scrollback,
269+- expanded details may need to be appended rather than toggled in place.
270+
271+### Spike method
272+
273+The decision should not be made from library preference or screenshots. Build
274+small disposable prototypes that replay the same deterministic recorded agent
275+events and provide the same editor and attachment interaction.
276+
277+The leading framework candidates are cel-tui and OpenTUI. OpenTUI deserves direct
278+evaluation because it powers OpenCode and provides Bun/TypeScript bindings, input,
279+textarea, scrolling, selection, code, and diff primitives:
280+
281+- <https://github.com/anomalyco/opentui>
282+- <https://opentui.com/>
283+
284+Adopting OpenTUI would not by itself reproduce OpenCode's UX. Its native runtime,
285+prebuilt artifacts, development pace, framework bindings, and supply-chain impact
286+must be evaluated. Retaining cel-tui must include the maintenance cost of any
287+library changes and the current specification/documentation workflow.
288+
289+Do not build every framework and conversation-model combination. Start with the
290+most natural implementation of each conversation model, use the same replay and
291+acceptance cases, and investigate a second implementation only where framework
292+behavior prevents a fair comparison.
293+
294+### Measurements
295+
296+Use a fixed corpus containing long text, reasoning, edits, large and rapidly
297+streaming tool output, failures, cancellations, images or attachment metadata,
298+and nested agent activity.
299+
300+Measure:
301+
302+- startup time,
303+- idle CPU usage,
304+- streaming CPU usage and render latency,
305+- memory use as history grows,
306+- terminal bytes written,
307+- responsiveness with a large history,
308+- scroll behavior and stick-to-bottom behavior,
309+- terminal-native text selection and copying,
310+- resize behavior,
311+- large paste and multiline editing behavior,
312+- overlay and draft preservation,
313+- terminal restoration after normal exit, cancellation, and injected failure,
314+- implementation size and conceptual complexity,
315+- required upstream or local TUI-framework changes,
316+- manual readability and sense of control during real use.
317+
318+For a full-screen design, the large-history test must exercise virtualization or
319+an equivalent bounded strategy. For an append-only design, it must demonstrate
320+that the live region remains correct while the terminal owns a large committed
321+history.
322+
323+Record the result in a short decision note containing evidence, rejected options,
324+and known costs. Spike code should not become production architecture merely
325+because it exists.
326+
327+## Context management for local models
328+
329+Small local context windows make context management a core behavior rather than a
330+late optimization.
331+
332+The initial policy should progress visibly through:
333+
334+1. bounded tool output with explicit omission metadata,
335+2. masking or digesting older observations,
336+3. readable client-controlled summaries with recorded lineage,
337+4. a clear context error when reduction is insufficient.
338+
339+Compaction should affect the provider request projection, not destroy durable
340+session history. Summaries should be inspectable and portable. Provider-side
341+opaque compaction must never be the only surviving representation.
342+
343+Context behavior should be tested with deliberately constrained 8k and 16k local
344+models and tool-heavy tasks, not inferred only from large hosted context windows.
345+
346+## Development path
347+
348+Progress is controlled by exit criteria rather than dates.
349+
350+### Stage 0: preserve and baseline
351+
352+- Commit the direction documents and current brain dump.
353+- Create an archive branch for the current main implementation.
354+- Record the exact archive branch name and commit.
355+- Preserve benchmark results and representative current UX behavior.
356+- Add only narrow local observability if needed to reproduce current stalls.
357+- Define a small set of end-to-end acceptance journeys.
358+
359+Exit when the current implementation can be restored exactly and vNext decisions
360+can be compared against a stable baseline.
361+
362+### Stage 1: decision spikes
363+
364+- Run the full-screen versus append/live TUI spike.
365+- Compare the leading TUI framework choices where necessary.
366+- Exercise a pi-ai-to-mini-coder event adapter with one local and one hosted model.
367+- Exercise the proposed append-only session format, including a truncated final
368+ write and a provider handoff.
369+- Trial runtime validation options against real settings, session, and extension
370+ data.
371+
372+Exit with short evidence-based decisions. Do not implement the whole product in
373+spike form.
374+
375+### Stage 2: walking vertical slice
376+
377+Build one usable path containing:
378+
379+- startup and settings,
380+- one local and one hosted provider path,
381+- normalized application events,
382+- a minimal system prompt,
383+- notepad-level input and file attachments,
384+- streaming assistant output,
385+- `bash`, `read`, and `edit`,
386+- unambiguous request and tool states,
387+- cancellation,
388+- append-only session persistence and resume,
389+- local diagnostics.
390+
391+Exit when this slice can complete and diagnose real coding tasks without hidden
392+stalls.
393+
394+At this point, decide whether continuing from the current source or replacing it
395+produces the smaller, clearer implementation. Reuse current authentication,
396+provider, argument, or tool code where it fits the new boundaries directly. Start
397+fresh where reuse would require parallel message models, compatibility state, or
398+continued coupling between provider, session, and TUI concerns.
399+
400+### Stage 3: UX quality
401+
402+- Complete the initial editor and attachment contract.
403+- Polish readable tool, reasoning, error, and cancellation presentation.
404+- Add settings UI with useful defaults.
405+- Harden scrolling, resizing, selection, terminal restoration, and long sessions.
406+- Keep advanced editing modes, history, and path completion deferred.
407+
408+Exit when regular dogfooding feels materially better than the published version.
409+
410+### Stage 4: local context and provider hardening
411+
412+- Add first-class Ollama and llama.cpp onboarding and diagnostics.
413+- Implement and expose context reduction stages.
414+- Run constrained-context local-model scenarios.
415+- Verify hosted-provider continuation and provider handoff.
416+
417+Exit when local support is genuinely a peer rather than a custom-provider example.
418+
419+### Stage 5: resources and extensions
420+
421+- Add root-to-leaf `AGENTS.md` and `CLAUDE.md` support.
422+- Add prompt templates and progressively disclosed skills.
423+- Add the narrow extension loader and API for tools, commands, and agents.
424+- Validate it with Exa and the adversary agent.
425+- Document extension development from the actual stable API.
426+
427+Exit when users can add those demonstrated behaviors without patching core.
428+
429+### Stage 6: release hardening
430+
431+- Add provider fixtures and contract tests.
432+- Add PTY and TUI tests plus a manual terminal matrix.
433+- Review dependency provenance, install scripts, updates, and locked versions.
434+- Define session migration and export behavior.
435+- Compare correctness, startup, resource use, and UX against the archived version.
436+- Dogfood local and hosted paths before publishing.
437+
438+Publish only when vNext is a better overall experience than the currently
439+published version.
440+
441+## Acceptance journeys
442+
443+The initial product decisions should be checked against a small stable set of
444+journeys rather than a large prose specification:
445+
446+1. A first-time local user reaches an Ollama or llama.cpp model without writing a
447+ verbose provider model object.
448+2. A hosted-provider user can authenticate, choose a model, and use the same agent
449+ and UI behavior.
450+3. A coding turn always exposes whether it is preparing, waiting for a provider,
451+ streaming, running a named tool, cancelled, failed, or complete.
452+4. A multiline prompt can be edited predictably, survives an opened and cancelled
453+ control, accepts a large paste, and includes text or image attachments.
454+5. A provider or rendering stall can be diagnosed from local logs without sending
455+ data elsewhere.
456+6. A long tool-heavy task on a constrained local context shows what was omitted or
457+ summarized while preserving the complete durable transcript.
458+7. A session can continue with another provider from readable local history.
459+8. Exa can be installed as a tool extension without core changes.
460+9. An adversary agent can be configured with its own prompt, model, effort, and
461+ tools; its actions and transcript remain inspectable.
462+10. A long conversation remains responsive and copyable under the chosen
463+ full-screen or append/live presentation model.
464+
465+## Documentation policy
466+
467+Avoid another comprehensive spec that duplicates implementation details.
468+Maintain only:
469+
470+- this product direction document,
471+- the original user feedback in `TODO.md`,
472+- focused acceptance journeys and tests,
473+- short decision records for expensive choices,
474+- extension and user documentation derived from working behavior.
475+
476+Do not prescribe detailed file trees, helper APIs, rendering sketches, or internal
477+state before they are implemented and verified.
478+
479+## Remaining decisions
480+
481+The next decisions should come from the Stage 1 spikes:
482+
483+- full-screen virtualized conversation or append-only conversation with a bounded
484+ live region,
485+- cel-tui, OpenTUI, or another choice justified by the spike evidence,
486+- reuse versus replacement of the current source,
487+- exact normalized session record and provider sidecar shape,
488+- runtime validation dependency,
489+- archive branch name and the commit at which vNext begins.