@sean.holung/minicode 0.2.3 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # minicode
 
-A lightweight CLI coding agent optimized for **local models** by providing AST-based intelligent context for smaller models running on consumer hardware.
+A lightweight coding agent optimized for **local models** — CLI-first with a built-in web UI. Provides AST-based intelligent context for smaller models running on consumer hardware.
 
 Read operations dominate token usage in typical agent sessions; minicode addresses this by optimizing for **specific languages** — indexing your project at startup with language plugins (TypeScript/JavaScript built-in) and injecting a compact **code map** (signatures only) into the system prompt, plus symbol-level tools (`read_symbol`, `find_references`, `get_dependencies`) so the model reads only what it needs instead of entire files. This keeps prompts lean enough for smaller models in the 20B range, with faster inference and better attention over the relevant code.
 
@@ -46,6 +46,15 @@ or you can also pass it an intial prompt from the start:
 minicode "Add error handling to src/api.ts"
 ```
 
+Start the web UI (chat, session management, project graph data):
+
+```bash
+minicode serve              # http://localhost:4567
+minicode serve --port 8080  # custom port
+```
+
+The serve mode also exposes an **OpenAI-compatible API** at `/v1/chat/completions`, so you can point any client that speaks the OpenAI protocol (OpenWebUI, TypingMind, ChatGPT-Next-Web, Lobe Chat, etc.) at `http://localhost:4567/v1` and use minicode as a backend.
+
 Run a single task and exit (useful for scripts/CI/orchestration):
 
 ```bash
@@ -79,13 +88,9 @@ npm run install:global
 - Agent loop with model tool-use support
 - In-memory session history with trimming
 - Safety guardrails for file paths and shell commands
-- Built-in tools:
-  - `read_file`
-  - `write_file`
-  - `edit_file`
-  - `search` (ripgrep, grep fallback)
-  - `list_files`
-  - `run_command`
+- Built-in tools: `read_file`, `write_file`, `edit_file`, `search`, `list_files`, `run_command`
+- **Web UI** — `minicode serve` starts an HTTP + WebSocket server with a bundled chat client, real-time streaming, session management, and project graph data endpoints
+- **OpenAI-compatible API** — any client that speaks the OpenAI protocol can use minicode as a backend at `/v1/chat/completions`
 - **Context optimization:** Code map in system prompt, `read_symbol`, `find_references`, `get_dependencies`
 - **Plugin system:** Extensible language support (TypeScript built-in)
 

package/dist/src/cli/args.js

@@ -10,12 +10,38 @@ export function parseCliArgs(argv) {
     let oneshot = false;
     let json = false;
     let outFile;
+    let serve = false;
+    let port = 4567;
     const taskParts = [];
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === undefined) {
             continue;
         }
+        if (arg === "serve") {
+            serve = true;
+            continue;
+        }
+        if (arg === "--port") {
+            const value = args[i + 1];
+            if (!value || value.startsWith("-")) {
+                throw new CliUsageError("--port requires a number. Example: --port 8080");
+            }
+            port = Number(value);
+            if (!Number.isFinite(port) || port <= 0) {
+                throw new CliUsageError("--port must be a positive number. Example: --port 8080");
+            }
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--port=")) {
+            const value = arg.slice("--port=".length).trim();
+            port = Number(value);
+            if (!Number.isFinite(port) || port <= 0) {
+                throw new CliUsageError("--port must be a positive number. Example: --port=8080");
+            }
+            continue;
+        }
         if (arg === "--verbose" || arg === "-v") {
             verbose = true;
             continue;
@@ -52,6 +78,8 @@ export function parseCliArgs(argv) {
         oneshot,
         json,
         ...(outFile ? { outFile } : {}),
+        serve,
+        port,
         task: taskParts.join(" ").trim(),
     };
 }
@@ -62,4 +90,7 @@ export function validateCliArgs(args) {
     if (!args.oneshot && (args.json || args.outFile)) {
         throw new CliUsageError("--json and --out are only supported with --oneshot.");
     }
+    if (args.serve && (args.oneshot || args.json || args.outFile)) {
+        throw new CliUsageError("serve mode is mutually exclusive with --oneshot, --json, and --out.");
+    }
 }

package/dist/src/index.js

@@ -210,6 +210,11 @@ async function runOneshot(params) {
 async function main() {
     const cliArgs = parseCliArgs(process.argv);
     validateCliArgs(cliArgs);
+    if (cliArgs.serve) {
+        const { runServe } = await import("./serve/server.js");
+        await runServe(cliArgs.verbose, cliArgs.port);
+        return;
+    }
     if (cliArgs.oneshot) {
         await runOneshot(cliArgs);
         process.exitCode = EXIT_CODE_SUCCESS;

package/dist/src/serve/agent-bridge.js

@@ -0,0 +1,356 @@
+import { CodingAgent, createModelClient } from "@minicode/agent-sdk";
+import { loadAgentConfig } from "../agent/config.js";
+import { computeFileHashes, getWorkspaceCacheDir, loadIndex, saveIndex, } from "../indexer/cache.js";
+import { buildProjectIndex } from "../indexer/project-index.js";
+import { createToolRegistry } from "../tools/registry.js";
+import { listSessions, loadSession, loadSessionByLabel, saveSession, } from "../session/session-store.js";
+export class AgentBridge {
+    agent;
+    config;
+    projectIndex;
+    buildAgent;
+    busy = false;
+    abortController = null;
+    broadcast;
+    verbose;
+    listeners = new Set();
+    pinnedSymbols = new Set();
+    annotations = new Map();
+    constructor(broadcast, verbose) {
+        this.broadcast = broadcast;
+        this.verbose = verbose;
+    }
+    addListener(fn) {
+        this.listeners.add(fn);
+    }
+    removeListener(fn) {
+        this.listeners.delete(fn);
+    }
+    emit(msg) {
+        this.broadcast(msg);
+        for (const fn of this.listeners) {
+            fn(msg);
+        }
+    }
+    async init() {
+        const config = await loadAgentConfig();
+        const modelClient = createModelClient(config);
+        let projectIndex;
+        try {
+            const cacheDir = getWorkspaceCacheDir(config.workspaceRoot);
+            const fileHashes = await computeFileHashes(config.workspaceRoot);
+            const cached = await loadIndex(cacheDir, fileHashes);
+            if (cached) {
+                projectIndex = cached;
+            }
+            else {
+                projectIndex = await buildProjectIndex(config.workspaceRoot);
+                await saveIndex(projectIndex, cacheDir, fileHashes);
+            }
+        }
+        catch {
+            projectIndex = undefined;
+        }
+        const toolRegistry = createToolRegistry(config, projectIndex);
+        // Wrap tool registry execute to inject annotations into tool results
+        const originalExecute = toolRegistry.execute.bind(toolRegistry);
+        toolRegistry.execute = async (name, input) => {
+            const result = await originalExecute(name, input);
+            return this.appendAnnotationsToResult(name, input, result);
+        };
+        this.config = config;
+        this.projectIndex = projectIndex;
+        this.buildAgent = (session, onUiUpdate) => {
+            return new CodingAgent({
+                config,
+                modelClient,
+                toolRegistry,
+                verbose: this.verbose,
+                ...(session ? { session } : {}),
+                ...(projectIndex !== undefined
+                    ? { getCodeMap: (focusSymbols) => projectIndex.getCodeMap(undefined, focusSymbols) }
+                    : {}),
+                onUiUpdate: onUiUpdate ?? ((event) => {
+                    this.emit(event);
+                }),
+                getSystemPromptSuffix: () => this.buildAnnotationSuffix(),
+            });
+        };
+        this.agent = this.buildAgent();
+    }
+    isBusy() {
+        return this.busy;
+    }
+    getConfig() {
+        return this.config;
+    }
+    getAgent() {
+        return this.agent;
+    }
+    async runTurn(message) {
+        if (this.busy) {
+            throw new Error("busy");
+        }
+        this.busy = true;
+        this.abortController = new AbortController();
+        try {
+            this.emit({ type: "turn_start" });
+            const result = await this.agent.runTurn(message, {
+                signal: this.abortController.signal,
+            });
+            this.emit({
+                type: "turn_end",
+                text: result.text,
+                usage: result.usage,
+            });
+            return result;
+        }
+        catch (error) {
+            const msg = error instanceof Error && error.name === "AbortError"
+                ? "Cancelled"
+                : error instanceof Error
+                    ? error.message
+                    : "Unknown error";
+            this.emit({ type: "error", message: msg });
+            throw error;
+        }
+        finally {
+            this.busy = false;
+            this.abortController = null;
+        }
+    }
+    cancel() {
+        if (this.abortController) {
+            this.abortController.abort();
+        }
+    }
+    // Session operations
+    async saveSess(label) {
+        const annotationsObj = this.annotations.size > 0
+            ? Object.fromEntries(this.annotations)
+            : undefined;
+        return saveSession(this.agent.getSession(), label, annotationsObj);
+    }
+    async loadSess(label) {
+        const result = (await loadSessionByLabel(label)) ?? (await loadSession(label));
+        if (!result)
+            return null;
+        this.agent = this.buildAgent(result.session);
+        // Restore annotations from saved session
+        this.annotations.clear();
+        if (result.annotations) {
+            for (const [name, notes] of Object.entries(result.annotations)) {
+                this.annotations.set(name, notes);
+            }
+        }
+        return result;
+    }
+    async listSess() {
+        return listSessions();
+    }
+    // ── Project index queries ──
+    hasIndex() {
+        return this.projectIndex !== undefined;
+    }
+    getSymbols() {
+        if (!this.projectIndex)
+            return [];
+        const symbols = [];
+        for (const sym of this.projectIndex.symbols.values()) {
+            symbols.push({
+                name: sym.name,
+                qualifiedName: sym.qualifiedName,
+                kind: sym.kind,
+                filePath: sym.filePath,
+                startLine: sym.startLine,
+                endLine: sym.endLine,
+                signature: sym.signature,
+                exported: sym.exported,
+            });
+        }
+        return symbols;
+    }
+    getSymbol(name) {
+        if (!this.projectIndex)
+            return undefined;
+        return this.projectIndex.getSymbol(name);
+    }
+    getDependencies(symbolName, depth) {
+        if (!this.projectIndex)
+            return undefined;
+        const cone = this.projectIndex.getDependencyCone(symbolName, depth);
+        if (cone.length === 0)
+            return undefined;
+        return cone.map((sym) => ({
+            name: sym.name,
+            qualifiedName: sym.qualifiedName,
+            kind: sym.kind,
+            filePath: sym.filePath,
+            signature: sym.signature,
+        }));
+    }
+    getReferences(symbolName) {
+        if (!this.projectIndex)
+            return undefined;
+        const sym = this.projectIndex.getSymbol(symbolName);
+        if (!sym)
+            return undefined;
+        // Find all edges pointing TO this symbol
+        const refs = this.projectIndex.dependencyEdges
+            .filter((e) => e.to === sym.qualifiedName || e.to === sym.name)
+            .map((e) => ({ from: e.from, kind: e.kind }));
+        return refs;
+    }
+    getCodeMap(tokenBudget) {
+        if (!this.projectIndex)
+            return undefined;
+        const focus = this.pinnedSymbols.size > 0 ? this.pinnedSymbols : undefined;
+        return this.projectIndex.getCodeMap(tokenBudget, focus);
+    }
+    getGraph() {
+        if (!this.projectIndex)
+            return undefined;
+        const nodes = [];
+        for (const sym of this.projectIndex.symbols.values()) {
+            nodes.push({
+                id: sym.qualifiedName,
+                name: sym.name,
+                kind: sym.kind,
+                filePath: sym.filePath,
+                exported: sym.exported,
+            });
+        }
+        const edges = this.projectIndex.dependencyEdges.map((e) => ({
+            from: e.from,
+            to: e.to,
+            kind: e.kind,
+        }));
+        return { nodes, edges };
+    }
+    getPinnedSymbols() {
+        return [...this.pinnedSymbols];
+    }
+    pinSymbol(name) {
+        if (!this.projectIndex)
+            return false;
+        const sym = this.projectIndex.getSymbol(name);
+        if (!sym)
+            return false;
+        this.pinnedSymbols.add(sym.qualifiedName);
+        return true;
+    }
+    unpinSymbol(name) {
+        if (!this.projectIndex)
+            return false;
+        const sym = this.projectIndex.getSymbol(name);
+        if (!sym)
+            return false;
+        this.pinnedSymbols.delete(sym.qualifiedName);
+        return true;
+    }
+    // ── Annotations ──
+    getAnnotations() {
+        this.evictStaleAnnotations();
+        return Object.fromEntries(this.annotations);
+    }
+    getAnnotationsForSymbol(name) {
+        return this.annotations.get(name) ?? [];
+    }
+    addAnnotation(name, text) {
+        if (!this.projectIndex)
+            return false;
+        const sym = this.projectIndex.getSymbol(name);
+        if (!sym)
+            return false;
+        const trimmed = text.slice(0, 500).trim();
+        if (trimmed.length === 0)
+            return false;
+        const key = sym.qualifiedName;
+        const existing = this.annotations.get(key) ?? [];
+        existing.push(trimmed);
+        this.annotations.set(key, existing);
+        return true;
+    }
+    removeAnnotation(name, index) {
+        const notes = this.annotations.get(name);
+        if (!notes || index < 0 || index >= notes.length)
+            return false;
+        notes.splice(index, 1);
+        if (notes.length === 0) {
+            this.annotations.delete(name);
+        }
+        return true;
+    }
+    clearAnnotations(name) {
+        this.annotations.delete(name);
+    }
+    evictStaleAnnotations() {
+        if (!this.projectIndex)
+            return;
+        for (const name of [...this.annotations.keys()]) {
+            if (!this.projectIndex.getSymbol(name)) {
+                this.annotations.delete(name);
+            }
+        }
+    }
+    buildAnnotationSuffix() {
+        this.evictStaleAnnotations();
+        if (this.annotations.size === 0)
+            return undefined;
+        return `[Annotated symbols: ${[...this.annotations.keys()].join(", ")}]`;
+    }
+    appendAnnotationsToResult(toolName, input, result) {
+        if (this.annotations.size === 0)
+            return result;
+        const inp = input;
+        if (toolName === "read_symbol" || toolName === "find_references" || toolName === "get_dependencies") {
+            const symName = (inp.name ?? inp.symbol ?? inp.query);
+            if (!symName)
+                return result;
+            // Try direct match, then resolve via index
+            let notes = this.annotations.get(symName);
+            if (!notes && this.projectIndex) {
+                const sym = this.projectIndex.getSymbol(symName);
+                if (sym)
+                    notes = this.annotations.get(sym.qualifiedName);
+            }
+            if (notes && notes.length > 0) {
+                return result + `\n[User annotation: ${notes.join("; ")}]`;
+            }
+        }
+        if (toolName === "read_file") {
+            const filePath = inp.path;
+            if (!filePath)
+                return result;
+            const fileAnnotations = [];
+            for (const [name, notes] of this.annotations) {
+                if (!this.projectIndex)
+                    continue;
+                const sym = this.projectIndex.getSymbol(name);
+                if (sym && (sym.filePath === filePath || filePath.endsWith(sym.filePath))) {
+                    fileAnnotations.push(`- ${sym.name}: ${notes.join("; ")}`);
+                }
+            }
+            if (fileAnnotations.length > 0) {
+                return result + `\n[User annotations for symbols in this file:]\n${fileAnnotations.join("\n")}`;
+            }
+        }
+        return result;
+    }
+    // ── Explain ──
+    async explainSymbol(name, onEvent, signal) {
+        if (!this.projectIndex)
+            throw new Error("No project index");
+        const sym = this.projectIndex.getSymbol(name);
+        if (!sym)
+            throw new Error(`Symbol "${name}" not found`);
+        const explainAgent = this.buildAgent(undefined, onEvent);
+        const prompt = `Explain "${sym.name}" (${sym.kind} in ${sym.filePath}).
+Use read_symbol, get_dependencies, find_references to gather context.
+Explain what it does, how it works, what depends on it, and key design decisions.
+Be concise but thorough.`;
+        const opts = signal ? { signal } : undefined;
+        const result = await explainAgent.runTurn(prompt, opts);
+        return result.text;
+    }
+}

package/dist/src/serve/openai-compat.js

@@ -0,0 +1,144 @@
+import { randomUUID } from "node:crypto";
+function sendJson(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString()));
+        req.on("error", reject);
+    });
+}
+export function handleModels(_req, res) {
+    sendJson(res, 200, {
+        object: "list",
+        data: [
+            {
+                id: "minicode-agent",
+                object: "model",
+                created: Math.floor(Date.now() / 1000),
+                owned_by: "minicode",
+            },
+        ],
+    });
+}
+export async function handleChatCompletions(req, res, bridge) {
+    let body;
+    try {
+        const raw = await readBody(req);
+        body = JSON.parse(raw);
+    }
+    catch {
+        sendJson(res, 400, { error: { message: "Invalid JSON body", type: "invalid_request_error" } });
+        return;
+    }
+    const messages = body.messages;
+    if (!messages || messages.length === 0) {
+        sendJson(res, 400, { error: { message: "messages array is required", type: "invalid_request_error" } });
+        return;
+    }
+    // Extract last user message
+    let userMessage;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === "user") {
+            userMessage = messages[i].content;
+            break;
+        }
+    }
+    if (!userMessage) {
+        sendJson(res, 400, { error: { message: "No user message found", type: "invalid_request_error" } });
+        return;
+    }
+    if (bridge.isBusy()) {
+        sendJson(res, 429, { error: { message: "Agent is busy with another request. Try again later.", type: "rate_limit_error" } });
+        return;
+    }
+    const completionId = `chatcmpl-${randomUUID()}`;
+    const created = Math.floor(Date.now() / 1000);
+    if (body.stream) {
+        await handleStreaming(res, bridge, userMessage, completionId, created);
+    }
+    else {
+        await handleNonStreaming(res, bridge, userMessage, completionId, created);
+    }
+}
+async function handleNonStreaming(res, bridge, message, completionId, created) {
+    try {
+        const result = await bridge.runTurn(message);
+        sendJson(res, 200, {
+            id: completionId,
+            object: "chat.completion",
+            created,
+            model: "minicode-agent",
+            choices: [
+                {
+                    index: 0,
+                    message: { role: "assistant", content: result.text },
+                    finish_reason: "stop",
+                },
+            ],
+            usage: result.usage
+                ? {
+                    prompt_tokens: result.usage.inputTokens,
+                    completion_tokens: result.usage.outputTokens,
+                    total_tokens: result.usage.inputTokens + result.usage.outputTokens,
+                }
+                : undefined,
+        });
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : "Unknown error";
+        sendJson(res, 500, { error: { message: msg, type: "server_error" } });
+    }
+}
+async function handleStreaming(res, bridge, message, completionId, created) {
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+    });
+    function sendSSE(data) {
+        res.write(`data: ${JSON.stringify(data)}\n\n`);
+    }
+    // Send initial role chunk
+    sendSSE({
+        id: completionId,
+        object: "chat.completion.chunk",
+        created,
+        model: "minicode-agent",
+        choices: [{ index: 0, delta: { role: "assistant" }, finish_reason: null }],
+    });
+    const listener = (msg) => {
+        if (msg.type === "streaming_chunk" && msg.content) {
+            sendSSE({
+                id: completionId,
+                object: "chat.completion.chunk",
+                created,
+                model: "minicode-agent",
+                choices: [{ index: 0, delta: { content: msg.content }, finish_reason: null }],
+            });
+        }
+    };
+    bridge.addListener(listener);
+    try {
+        await bridge.runTurn(message);
+        sendSSE({
+            id: completionId,
+            object: "chat.completion.chunk",
+            created,
+            model: "minicode-agent",
+            choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
+        });
+        res.write("data: [DONE]\n\n");
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : "Unknown error";
+        sendSSE({ error: { message: msg, type: "server_error" } });
+    }
+    finally {
+        bridge.removeListener(listener);
+        res.end();
+    }
+}