xonecas.io
64875
Mc

mini-coder / commit ddcaf7d

feat: docs and relaxed config

Users can now configure in the TUI

xonecas2026-09-28 ddcaf7d8850003ba3f55f37a6963603ef44b468a parent 67f38c9

6 files changed

README.md+13−7
@@ -4,9 +4,12 @@
44
55 # mini-coder
66
7-A fast, transparent, config-first terminal coding agent. One provider request at a time, no
8-hidden machinery: `edit`, `read`, and `bash`, an append-only JSONL session log, and a config
9-file that decides everything.
7+Minimalistic terminal coding agent, with an emphasis on giving you control of what is sent to
8+the model, and visibility into the model's actions.
9+
10+Beautiful TUI with Tokyo Night colors, more to come soon.
11+
12+We try to render diffs when the agent uses bash to edit, only for the current working directory; changes outside it aren't tracked.
1013
1114 ## Install
1215
@@ -16,8 +19,10 @@ npm i -g mini-coder
1619
1720 ## Configuration
1821
22+You can use `/login` and `/provider` to configure in the TUI. Changes are saved to your config.
23+
1924 Global config lives at `~/.config/mini-coder/config.json` (`$XDG_CONFIG_HOME/mini-coder/config.json`
20-if set). There is no project-local config and no override flags.
25+if set). You can also configure your provider and model there:
2126
2227 ```json
2328 {
@@ -26,7 +31,7 @@ if set). There is no project-local config and no override flags.
2631 }
2732 ```
2833
29-Only `provider` and `model` are required. Defaults for the rest:
34+Defaults for the rest:
3035
3136 ```json
3237 {
@@ -40,8 +45,9 @@ Only `provider` and `model` are required. Defaults for the rest:
4045 }
4146 ```
4247
43-- `provider` / `model` — any model from the `pi-ai` catalog. Invalid pairs fail with a
44- list of available models for that provider. Requires a discoverable api key from the environment (Like: OPENCODE_API_KEY).
48+- `provider` / `model` — any model from the `pi-ai` catalog. Requires a discoverable api key
49+ from the environment (like `OPENCODE_API_KEY`). When neither is set, the agent launches;
50+ sending a message reports that no model is configured.
4551 - `sessionsDir` — where append-only session JSONL files are written. (no relative paths for now, absolute paths only).
4652 - `systemPrompt` — the base of the system prompt. Skills and agent files, if
4753 enabled, are appended after it.
src/agent.ts+14−6
@@ -27,6 +27,7 @@ export type AgentEvent =
2727 | { type: "toolOutput"; chunk: string }
2828 | { type: "toolResult"; name: string; text: string; isError: boolean; diffs?: FileDiff[] }
2929 | { type: "message"; message: AssistantMessage }
30+ | { type: "noModel" }
3031 | { type: "error"; message: string }
3132 | { type: "cancelled" }
3233 | { type: "complete" };
@@ -46,7 +47,8 @@ export const NO_INTERACTION: Interaction = {
4647 /** What one turn needs, shared by both projections: the TUI and `--print`. */
4748 export interface AgentOptions {
4849 models: Models;
49- model: Model<Api>;
50+ /** The selected model, or null until one is configured or chosen in the TUI. */
51+ model: Model<Api> | null;
5052 systemPrompt: string;
5153 tools: Tool[];
5254 /** The configured tool names, kept so a model switch can rebuild `tools`. */
@@ -65,6 +67,12 @@ interface AgentRun extends AgentOptions {
6567 export async function runAgentTurn(run: AgentRun): Promise<void> {
6668 const { messages, session, signal, interaction, onEvent } = run;
6769
70+ const model = run.model;
71+ if (model === null) {
72+ onEvent({ type: "noModel" });
73+ return;
74+ }
75+
6876 const cancelled = (): void => onEvent({ type: "cancelled" });
6977 const failed = (message: string): void => onEvent({ type: "error", message });
7078
@@ -105,9 +113,9 @@ export async function runAgentTurn(run: AgentRun): Promise<void> {
105113
106114 onEvent({ type: "phase", phase: "preparing" });
107115 session.appendRequest({
108- provider: run.model.provider,
109- model: run.model.id,
110- api: run.model.api,
116+ provider: model.provider,
117+ model: model.id,
118+ api: model.api,
111119 thinkingEffort: run.thinkingEffort,
112120 systemPrompt: run.systemPrompt,
113121 tools: run.tools,
@@ -117,7 +125,7 @@ export async function runAgentTurn(run: AgentRun): Promise<void> {
117125 const context = { systemPrompt: run.systemPrompt, tools: run.tools, messages };
118126 let stream;
119127 try {
120- stream = run.models.streamSimple(run.model, context, {
128+ stream = run.models.streamSimple(model, context, {
121129 reasoning: run.thinkingEffort === "off" ? undefined : run.thinkingEffort,
122130 signal,
123131 sessionId: session.id ?? undefined,
@@ -186,7 +194,7 @@ export async function runAgentTurn(run: AgentRun): Promise<void> {
186194 try {
187195 result = await executeTool(call.name, validateToolCall(run.tools, call), {
188196 signal,
189- supportsImages: acceptsImages(run.model),
197+ supportsImages: acceptsImages(model),
190198 onOutput: (chunk) => onEvent({ type: "toolOutput", chunk }),
191199 });
192200 } catch (error) {
src/cli.ts+10−6
@@ -1,6 +1,6 @@
11 import process from "node:process";
22 import { clampThinkingLevel, contentText, type AssistantMessage, type Message, type UserMessage } from "@earendil-works/pi-ai";
3-import { loadConfig, resolveModel } from "./config.ts";
3+import { configPath, loadConfig, resolveModel } from "./config.ts";
44 import { buildSystemPrompt } from "./prompt.ts";
55 import { acceptsImages, toolSchemas } from "./tools/index.ts";
66 import { Session } from "./session.ts";
@@ -32,6 +32,7 @@ async function runPrint(prompt: string, ctx: AgentOptions): Promise<number> {
3232
3333 let failed = false;
3434 let cancelled = false;
35+ let noModel = false;
3536 try {
3637 await runAgentTurn({
3738 ...ctx,
@@ -41,7 +42,10 @@ async function runPrint(prompt: string, ctx: AgentOptions): Promise<number> {
4142 onEvent: (event) => {
4243 if (event.type === "toolCall") process.stderr.write(`[tool] ${event.name}\n`);
4344 else if (event.type === "toolOutput") process.stderr.write(event.chunk);
44- else if (event.type === "error") {
45+ else if (event.type === "noModel") {
46+ noModel = true;
47+ process.stderr.write(`[error] no model configured; add "provider" and "model" to ${configPath()}\n`);
48+ } else if (event.type === "error") {
4549 failed = true;
4650 process.stderr.write(`[error] ${event.message}\n`);
4751 } else if (event.type === "cancelled") {
@@ -60,11 +64,11 @@ async function runPrint(prompt: string, ctx: AgentOptions): Promise<number> {
6064 }
6165
6266 const last = messages.filter((message): message is AssistantMessage => message.role === "assistant").at(-1);
63- if (!failed && !cancelled && last !== undefined) {
67+ if (!failed && !cancelled && !noModel && last !== undefined) {
6468 const text = contentText(last.content, "");
6569 if (text !== "") process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
6670 }
67- return failed || cancelled ? 1 : 0;
71+ return failed || cancelled || noModel ? 1 : 0;
6872 }
6973
7074 async function main(): Promise<void> {
@@ -76,9 +80,9 @@ async function main(): Promise<void> {
7680 models,
7781 model,
7882 systemPrompt: buildSystemPrompt(config),
79- tools: toolSchemas(config.tools, acceptsImages(model)),
83+ tools: toolSchemas(config.tools, model !== null && acceptsImages(model)),
8084 toolNames: config.tools,
81- thinkingEffort: clampThinkingLevel(model, config.thinkingEffort),
85+ thinkingEffort: model === null ? config.thinkingEffort : clampThinkingLevel(model, config.thinkingEffort),
8286 session,
8387 };
8488
src/config.ts+6−14
@@ -51,8 +51,8 @@ const ConfigSchema = Type.Object(
5151 discoverAgentFiles: Type.Boolean({ default: true }),
5252 skillsDirs: Type.Array(Type.String(), { default: [] }),
5353 tools: Type.Array(ToolNameSchema, { default: ["edit", "read", "bash"] }),
54- provider: Type.String(),
55- model: Type.String(),
54+ provider: Type.Optional(Type.String()),
55+ model: Type.Optional(Type.String()),
5656 thinkingEffort: Type.Union(
5757 [
5858 Type.Literal("off"),
@@ -76,7 +76,7 @@ function configDir(): string {
7676 return join(base, "mini-coder");
7777 }
7878
79-function configPath(): string {
79+export function configPath(): string {
8080 return join(configDir(), "config.json");
8181 }
8282
@@ -134,7 +134,7 @@ const API_FACTORY: Record<CustomApi, () => ReturnType<typeof openAICompletionsAp
134134 "google-generative-ai": googleGenerativeAIApi,
135135 };
136136
137-export function resolveModel(config: Config): { models: MutableModels; model: Model<Api> } {
137+export function resolveModel(config: Config): { models: MutableModels; model: Model<Api> | null } {
138138 const models = builtinModels({ credentials: createCredentialStore(config.authFile) });
139139 for (const provider of config.customProviders) {
140140 const name = provider.name ?? provider.id;
@@ -166,14 +166,6 @@ export function resolveModel(config: Config): { models: MutableModels; model: Mo
166166 );
167167 }
168168
169- const model = models.getModel(config.provider, config.model);
170- if (!model) {
171- const known = models
172- .getModels(config.provider)
173- .map((m) => m.id)
174- .slice(0, 12);
175- const hint = known.length ? ` (available: ${known.join(", ")})` : "";
176- throw new Error(`config model: unknown model "${config.model}" for provider "${config.provider}"${hint}`);
177- }
178- return { models, model };
169+ if (!config.provider || !config.model) return { models, model: null };
170+ return { models, model: models.getModel(config.provider, config.model) ?? null };
179171 }
src/tui/commands.ts+4−2
@@ -15,8 +15,8 @@ import { commonPrefix } from "./complete.ts";
1515 export interface CommandContext {
1616 /** The collection the running command may reach, e.g. to start a login. */
1717 models: Models;
18- /** The model the session is currently running. */
19- model: Model<Api>;
18+ /** The model the session is currently running, or null before one is chosen. */
19+ model: Model<Api> | null;
2020 /** Switches the running session to `model`. */
2121 select(model: Model<Api>): void;
2222 /** Sets the running session's thinking level. */
@@ -149,6 +149,7 @@ const thinking: Command = {
149149 name: "thinking",
150150 description: "set the thinking level",
151151 async run(ctx): Promise<void> {
152+ if (ctx.model === null) throw new Error("no model configured");
152153 const levels = getSupportedThinkingLevels(ctx.model);
153154 const level = (await ctx.prompt({
154155 type: "select",
@@ -164,6 +165,7 @@ const model: Command = {
164165 name: "model",
165166 description: "choose a model for the current provider",
166167 async run(ctx): Promise<void> {
168+ if (ctx.model === null) throw new Error("no model configured");
167169 const providerId = ctx.model.provider;
168170 const models = await ctx.models.getAvailable(providerId, { signal: ctx.signal });
169171 await chooseModel(ctx, providerId, models);
src/tui/tui.ts+15−3
@@ -379,7 +379,12 @@ class Tui {
379379 /** The startup and selection banner: provider, model, and thinking effort. */
380380 private pushBanner(): void {
381381 this.separator = true;
382- this.push(`mini-coder · ${this.opts.model.provider}/${this.opts.model.id} · ${this.opts.thinkingEffort}`);
382+ const model = this.opts.model;
383+ this.push(
384+ model === null
385+ ? "mini-coder · no model configured"
386+ : `mini-coder · ${model.provider}/${model.id} · ${this.opts.thinkingEffort}`,
387+ );
383388 this.separator = true;
384389 }
385390
@@ -399,7 +404,9 @@ class Tui {
399404
400405 /** Sets the running session's thinking level, clamped to the current model. */
401406 private setThinking(level: ModelThinkingLevel): void {
402- this.opts.thinkingEffort = clampThinkingLevel(this.opts.model, level);
407+ const model = this.opts.model;
408+ if (model === null) return;
409+ this.opts.thinkingEffort = clampThinkingLevel(model, level);
403410 this.pushBanner();
404411 this.render();
405412 }
@@ -590,6 +597,9 @@ class Tui {
590597 case "error":
591598 this.endTurn(red(`! ${event.message}`));
592599 break;
600+ case "noModel":
601+ this.endTurn(red("! no model configured"));
602+ break;
593603 case "cancelled":
594604 this.endTurn(red("! cancelled"));
595605 break;
@@ -704,9 +714,11 @@ class Tui {
704714 * emphasis, so only the phase half is dimmed.
705715 */
706716 private statusLine(): string {
717+ const model = this.opts.model;
718+ if (model === null) return dim("no model configured");
707719 const usage = contextUsageLine(
708720 estimateContextTokens(this.messages, this.opts.systemPrompt, this.opts.tools),
709- this.opts.model,
721+ model,
710722 );
711723 if (this.paused || this.phase === "pausing") {
712724 return `${dim("paused - type steering, Enter to submit")} · ${usage}`;