@sean.holung/minicode 0.2.0 → 0.2.2

package/README.md

@@ -2,6 +2,8 @@
 
 A lightweight CLI coding agent optimized for **local models** by providing AST-based intelligent context for smaller models running on consumer hardware.
 
+> minicode gives local models a dependency-aware map of your codebase, so agents read less, reason better, and ship changes faster.
+
 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.
 
 ## Quick Start (LM Studio)
@@ -21,7 +23,7 @@ OPENAI_BASE_URL=http://localhost:1234/v1
 OPENAI_API_KEY=
 MAX_STEPS=50
 MAX_TOKENS=4096
-MAX_CONTEXT_TOKENS=120000
+MAX_CONTEXT_TOKENS=60000
 WORKSPACE_ROOT=.
 COMMAND_TIMEOUT_MS=30000
 MAX_FILE_SIZE_BYTES=1000000
@@ -46,6 +48,20 @@ or you can also pass it an intial prompt from the start:
 minicode "Add error handling to src/api.ts"
 ```
 
+Run a single task and exit (useful for scripts/CI/orchestration):
+
+```bash
+minicode --oneshot "Find TODOs and summarize action items"
+# short flag
+minicode -1 "Refactor parseArgs and run tests"
+
+# JSON output (for pipeline parsing)
+minicode --oneshot --json "Summarize recent changes"
+
+# Write final output to a file (suppresses terminal response output)
+minicode --oneshot --out result.txt "Generate release notes"
+```
+
 **Requirements:** Node.js 22+, LM Studio (or any OpenAI-compatible local server), `rg` in PATH (recommended). Set `MODEL` to match the model name in LM Studio.
 
 ### Install from source
@@ -81,6 +97,8 @@ For a deep technical walkthrough of AST parsing, dependency graph construction,
 
 For agent-loop internals (session lifecycle, tool execution, streaming, loop detection, and model client behavior), see [docs/AGENT_RUNTIME.md](docs/AGENT_RUNTIME.md).
 
+For the proposed reusable package architecture and public interfaces for a standalone runtime SDK, see [docs/SDK_SPEC.md](docs/SDK_SPEC.md).
+
 minicode reduces token usage by indexing your project and providing targeted tools:
 
 - **Code map** — A compact project skeleton (signatures only) is injected into the system prompt so the model can orient itself without reading full files.
@@ -110,6 +128,17 @@ The graph powers:
 - **`find_references`** — Returns symbols that call or reference a given symbol.
 - **`read_symbol`** — Shows "Used by", "Calls", and "Referenced Types" derived from the graph.
 
+### Why this differs from a tree-sitter-first approach
+
+Tree-sitter-focused agents are excellent for fast, generic syntax parsing across many languages. minicode takes a different path for TypeScript/JavaScript by using the TypeScript compiler AST to build a project symbol graph and drive graph-aware tools.
+
+Advantages of this approach in minicode:
+
+- **Dependency-aware navigation** — tools can follow call/type/inheritance edges (`calls`, `references`, `extends`, `implements`) instead of relying on text-only search.
+- **Higher-signal context under tight budgets** — code-map ranking prioritizes exported and highly referenced symbols so key APIs survive truncation.
+- **Targeted reads for local models** — symbol-level tools (`read_symbol`, `find_references`, `get_dependencies`) reduce unnecessary file reads and improve attention on relevant code.
+- **Fast iterative indexing** — syntax-only AST parsing (without full type-checking) keeps startup and reindexing lightweight while preserving structural code intelligence.
+
 ## Plugin System
 
 ### Supported Languages
@@ -228,6 +257,20 @@ npm run dev -- --verbose "Fix the bug"
 npm run dev -- -v
 ```
 
+One-shot mode in development:
+
+```bash
+npm run dev -- --oneshot "Fix lint errors and explain changes"
+npm run dev -- --oneshot --json "Summarize TODOs"
+npm run dev -- --oneshot --out result.txt "Draft changelog"
+```
+
+### Exit codes
+
+- `0`: Success
+- `1`: Runtime failure
+- `2`: CLI usage/validation error (for example, `--oneshot` without a prompt)
+
 ## Scripts
 
 - `npm run dev` - start the CLI in TypeScript mode
@@ -237,5 +280,3 @@ npm run dev -- -v
 - `npm run lint` - run ESLint on TypeScript source and tests
 - `npm test` - run Node test suite
 
-
-

package/dist/src/cli/args.js

@@ -0,0 +1,65 @@
+export class CliUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CliUsageError";
+    }
+}
+export function parseCliArgs(argv) {
+    const args = argv.slice(2);
+    let verbose = false;
+    let oneshot = false;
+    let json = false;
+    let outFile;
+    const taskParts = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined) {
+            continue;
+        }
+        if (arg === "--verbose" || arg === "-v") {
+            verbose = true;
+            continue;
+        }
+        if (arg === "--oneshot" || arg === "-1") {
+            oneshot = true;
+            continue;
+        }
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--out") {
+            const value = args[i + 1];
+            if (!value || value.startsWith("-")) {
+                throw new CliUsageError("--out requires a file path. Example: --out result.txt");
+            }
+            outFile = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--out=")) {
+            const value = arg.slice("--out=".length).trim();
+            if (value.length === 0) {
+                throw new CliUsageError("--out requires a non-empty file path. Example: --out=result.txt");
+            }
+            outFile = value;
+            continue;
+        }
+        taskParts.push(arg);
+    }
+    return {
+        verbose,
+        oneshot,
+        json,
+        ...(outFile ? { outFile } : {}),
+        task: taskParts.join(" ").trim(),
+    };
+}
+export function validateCliArgs(args) {
+    if (args.oneshot && args.task.length === 0) {
+        throw new CliUsageError("--oneshot requires a task prompt. Example: minicode --oneshot \"Fix lint errors\"");
+    }
+    if (!args.oneshot && (args.json || args.outFile)) {
+        throw new CliUsageError("--json and --out are only supported with --oneshot.");
+    }
+}

package/dist/src/index.js

@@ -1,24 +1,22 @@
 #!/usr/bin/env node
 import process from "node:process";
+import { writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline/promises";
-import { CodingAgent } from "./agent/agent.js";
+import { CodingAgent, createModelClient } from "@minicode/agent-sdk";
 import { formatConfigForDisplay, loadAgentConfig } from "./agent/config.js";
+import { listSessions, loadSession, loadSessionByLabel, saveSession, } from "./session/session-store.js";
 import { computeFileHashes, getWorkspaceCacheDir, loadIndex, saveIndex, } from "./indexer/cache.js";
 import { buildProjectIndex } from "./indexer/project-index.js";
-import { createModelClient } from "./model/client.js";
-import { ToolRegistry } from "./tools/registry.js";
-function parseArgs(argv) {
-    const args = argv.slice(2);
-    const verbose = args.includes("--verbose") || args.includes("-v");
-    const filtered = args.filter((a) => a !== "--verbose" && a !== "-v");
-    const task = filtered.join(" ").trim();
-    return { verbose, task };
-}
+import { createToolRegistry } from "./tools/registry.js";
+import { CliUsageError, parseCliArgs, validateCliArgs, } from "./cli/args.js";
+const EXIT_CODE_SUCCESS = 0;
+const EXIT_CODE_RUNTIME_ERROR = 1;
+const EXIT_CODE_USAGE_ERROR = 2;
 function printBanner() {
     console.log("minicode");
     console.log('Type your request, or "/exit" to quit.');
 }
-async function runInteractive(verbose, initialTask) {
+async function createAgentRuntime(verbose, onProgress) {
     const config = await loadAgentConfig();
     const modelClient = createModelClient(config);
     let projectIndex;
@@ -37,15 +35,26 @@ async function runInteractive(verbose, initialTask) {
     catch {
         projectIndex = undefined;
     }
-    const toolRegistry = ToolRegistry.createDefault(config, projectIndex);
-    const agent = new CodingAgent({
-        config,
-        modelClient,
-        toolRegistry,
-        verbose,
-        ...(projectIndex !== undefined ? { projectIndex } : {}),
-        onProgress: (msg) => console.error(`  ${msg}`),
-    });
+    const toolRegistry = createToolRegistry(config, projectIndex);
+    function buildAgent(session) {
+        return new CodingAgent({
+            config,
+            modelClient,
+            toolRegistry,
+            verbose,
+            ...(session ? { session } : {}),
+            ...(projectIndex !== undefined
+                ? { getCodeMap: () => projectIndex.getCodeMap() }
+                : {}),
+            ...(onProgress ? { onProgress } : {}),
+        });
+    }
+    return { agent: buildAgent(), config, toolRegistry, projectIndex, buildAgent };
+}
+async function runInteractive(verbose, initialTask) {
+    const runtime = await createAgentRuntime(verbose, (msg) => console.error(`  ${msg}`));
+    let { agent } = runtime;
+    const { config, buildAgent } = runtime;
     printBanner();
     console.log(`Workspace: ${config.workspaceRoot}`);
     console.log(`Provider: ${config.modelProvider}`);
@@ -64,7 +73,7 @@ async function runInteractive(verbose, initialTask) {
             turnAbortController.abort();
         }
         else if (shuttingDown) {
-            process.exit(1);
+            process.exit(EXIT_CODE_RUNTIME_ERROR);
         }
         else {
             shuttingDown = true;
@@ -89,7 +98,7 @@ async function runInteractive(verbose, initialTask) {
             break;
         }
         if (trimmed === "/help") {
-            console.log('Commands: "/help", "/config", "/exit"');
+            console.log('Commands: "/help", "/config", "/save [label]", "/load [label]", "/sessions", "/exit"');
             console.log("Start with --verbose or -v to log prompts, responses, and tool calls.");
             continue;
         }
@@ -97,6 +106,57 @@ async function runInteractive(verbose, initialTask) {
             console.log("\n" + formatConfigForDisplay(config) + "\n");
             continue;
         }
+        if (trimmed === "/save" || trimmed.startsWith("/save ")) {
+            const label = trimmed.slice("/save".length).trim() || undefined;
+            try {
+                const meta = await saveSession(agent.getSession(), label);
+                console.log(`Session saved as "${meta.label}" (${meta.messageCount} messages)`);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : "Unknown error";
+                console.error(`Failed to save session: ${msg}`);
+            }
+            continue;
+        }
+        if (trimmed === "/sessions") {
+            const sessions = await listSessions();
+            if (sessions.length === 0) {
+                console.log("No saved sessions found.");
+            }
+            else {
+                console.log("Saved sessions:");
+                for (const s of sessions) {
+                    console.log(`  ${s.label} (${s.messageCount} msgs, saved ${s.savedAt})`);
+                }
+            }
+            continue;
+        }
+        if (trimmed === "/load" || trimmed.startsWith("/load ")) {
+            const arg = trimmed.slice("/load".length).trim();
+            if (arg.length === 0) {
+                const sessions = await listSessions();
+                if (sessions.length === 0) {
+                    console.log("No saved sessions found.");
+                }
+                else {
+                    console.log("Saved sessions:");
+                    for (const s of sessions) {
+                        console.log(`  ${s.label} (${s.messageCount} msgs, saved ${s.savedAt})`);
+                    }
+                    console.log('\nUse "/load <label>" to restore a session.');
+                }
+                continue;
+            }
+            const result = (await loadSessionByLabel(arg)) ??
+                (await loadSession(arg));
+            if (!result) {
+                console.log(`No session found matching "${arg}".`);
+                continue;
+            }
+            agent = buildAgent(result.session);
+            console.log(`Session "${result.label}" restored (${result.session.getMessages().length} messages).`);
+            continue;
+        }
         turnAbortController = new AbortController();
         try {
             const { text, usage } = await agent.runTurn(trimmed, {
@@ -121,18 +181,41 @@ async function runInteractive(verbose, initialTask) {
     }
     rl.close();
 }
+async function runOneshot(params) {
+    const { agent } = await createAgentRuntime(params.verbose);
+    const { text, usage } = await agent.runTurn(params.task);
+    const payload = params.json
+        ? JSON.stringify({ text, usage: usage ?? null }, null, 2)
+        : text;
+    if (params.outFile) {
+        await writeFile(params.outFile, payload + "\n", "utf8");
+        return;
+    }
+    console.log(payload);
+}
 async function main() {
-    const { verbose, task } = parseArgs(process.argv);
+    const cliArgs = parseCliArgs(process.argv);
+    validateCliArgs(cliArgs);
+    if (cliArgs.oneshot) {
+        await runOneshot(cliArgs);
+        process.exitCode = EXIT_CODE_SUCCESS;
+        return;
+    }
     const uiMode = process.env.CLI_UI_MODE ?? "ink";
     if (uiMode !== "legacy" && process.stdin.isTTY) {
         const { runInkCli } = await import("./ui/cli-ink.js");
-        await runInkCli(verbose, task.length > 0 ? task : undefined);
+        await runInkCli(cliArgs.verbose, cliArgs.task.length > 0 ? cliArgs.task : undefined);
+        process.exitCode = EXIT_CODE_SUCCESS;
         return;
     }
-    await runInteractive(verbose, task.length > 0 ? task : undefined);
+    await runInteractive(cliArgs.verbose, cliArgs.task.length > 0 ? cliArgs.task : undefined);
+    process.exitCode = EXIT_CODE_SUCCESS;
 }
 main().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
     console.error(`Fatal error: ${message}`);
-    process.exit(1);
+    if (error instanceof CliUsageError) {
+        process.exit(EXIT_CODE_USAGE_ERROR);
+    }
+    process.exit(EXIT_CODE_RUNTIME_ERROR);
 });

package/dist/src/session/session-store.js

@@ -0,0 +1,82 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Session } from "@minicode/agent-sdk";
+let sessionsDir = path.join(os.homedir(), ".minicode", "sessions");
+/** Override sessions directory (for testing). */
+export function setSessionsDir(dir) {
+    sessionsDir = dir;
+}
+export async function saveSession(session, label) {
+    await mkdir(sessionsDir, { recursive: true });
+    const savedAt = new Date().toISOString();
+    const snapshot = session.toJSON();
+    const resolvedLabel = label && label.trim().length > 0
+        ? label.trim()
+        : new Date().toLocaleString();
+    const data = {
+        label: resolvedLabel,
+        savedAt,
+        session: snapshot,
+    };
+    const filePath = path.join(sessionsDir, `${snapshot.id}.json`);
+    await writeFile(filePath, JSON.stringify(data, null, 2), "utf8");
+    return {
+        id: snapshot.id,
+        label: resolvedLabel,
+        createdAt: snapshot.createdAt,
+        savedAt,
+        messageCount: snapshot.messages.length,
+    };
+}
+export async function listSessions() {
+    let files;
+    try {
+        files = await readdir(sessionsDir);
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const file of files) {
+        if (!file.endsWith(".json"))
+            continue;
+        try {
+            const raw = await readFile(path.join(sessionsDir, file), "utf8");
+            const data = JSON.parse(raw);
+            results.push({
+                id: data.session.id,
+                label: data.label,
+                createdAt: data.session.createdAt,
+                savedAt: data.savedAt,
+                messageCount: data.session.messages.length,
+            });
+        }
+        catch {
+            // skip corrupt files
+        }
+    }
+    results.sort((a, b) => b.savedAt.localeCompare(a.savedAt));
+    return results;
+}
+export async function loadSession(sessionId) {
+    const filePath = path.join(sessionsDir, `${sessionId}.json`);
+    try {
+        const raw = await readFile(filePath, "utf8");
+        const data = JSON.parse(raw);
+        return {
+            session: Session.fromJSON(data.session),
+            label: data.label,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function loadSessionByLabel(label) {
+    const sessions = await listSessions();
+    const match = sessions.find((s) => s.label.toLowerCase() === label.toLowerCase());
+    if (!match)
+        return undefined;
+    return loadSession(match.id);
+}

package/dist/src/tools/find-references.js

@@ -1,4 +1,4 @@
-import { expectNonEmptyString, expectOptionalNumber, } from "./helpers.js";
+import { expectNonEmptyString, expectOptionalNumber } from "@minicode/agent-sdk";
 const DEFAULT_LIMIT = 50;
 export function createFindReferencesTool(projectIndex) {
     return {

package/dist/src/tools/get-dependencies.js

@@ -1,4 +1,4 @@
-import { expectNonEmptyString, expectOptionalNumber } from "./helpers.js";
+import { expectNonEmptyString, expectOptionalNumber } from "@minicode/agent-sdk";
 export function createGetDependenciesTool(projectIndex) {
     return {
         name: "get_dependencies",

package/dist/src/tools/read-symbol.js

@@ -1,6 +1,5 @@
 import { readFile, stat } from "node:fs/promises";
-import { resolveWorkspacePath, validateFileReadSize, } from "../safety/guardrails.js";
-import { expectNonEmptyString, expectOptionalBoolean } from "./helpers.js";
+import { resolveWorkspacePath, validateFileReadSize, expectNonEmptyString, expectOptionalBoolean, } from "@minicode/agent-sdk";
 const LEADING_CONTEXT_LINES = 3;
 export function createReadSymbolTool(config, projectIndex) {
     return {

package/dist/src/tools/registry.js

@@ -1,68 +1,33 @@
-import { createEditFileTool } from "./edit-file.js";
+import { ToolRegistry, createReadFileTool, createWriteFileTool, createEditFileTool, createSearchTool, createListFilesTool, createRunCommandTool, } from "@minicode/agent-sdk";
 import { createFindReferencesTool } from "./find-references.js";
 import { createGetDependenciesTool } from "./get-dependencies.js";
-import { createListFilesTool } from "./list-files.js";
-import { createReadFileTool } from "./read-file.js";
 import { createReadSymbolTool } from "./read-symbol.js";
-import { createRunCommandTool } from "./run-command.js";
 import { createSearchCodeMapTool } from "./search-code-map.js";
-import { createSearchTool } from "./search.js";
-import { createWriteFileTool } from "./write-file.js";
-function ensureInputObject(input) {
-    if (typeof input !== "object" || input === null || Array.isArray(input)) {
-        throw new Error("Tool input must be a JSON object.");
-    }
-    return input;
-}
-function toToolSchema(tool) {
-    return {
-        name: tool.name,
-        description: tool.description,
-        input_schema: tool.inputSchema,
-    };
-}
-export class ToolRegistry {
-    toolsByName = new Map();
-    constructor(tools) {
-        for (const tool of tools) {
-            if (this.toolsByName.has(tool.name)) {
-                throw new Error(`Duplicate tool registration for "${tool.name}".`);
-            }
-            this.toolsByName.set(tool.name, tool);
-        }
-    }
-    static createDefault(config, projectIndex) {
-        const tools = [
-            createReadFileTool(config),
-            createWriteFileTool(config, projectIndex),
-            createEditFileTool(config, projectIndex),
-            createSearchTool(config),
-            createListFilesTool(config),
-            createRunCommandTool(config),
-        ];
-        if (projectIndex) {
-            tools.splice(1, 0, createReadSymbolTool(config, projectIndex));
-            tools.splice(2, 0, createFindReferencesTool(projectIndex));
-            tools.splice(3, 0, createGetDependenciesTool(projectIndex));
-            tools.splice(4, 0, createSearchCodeMapTool(projectIndex));
-        }
-        return new ToolRegistry(tools);
-    }
-    getToolSchemas() {
-        return [...this.toolsByName.values()].map(toToolSchema);
-    }
-    async execute(name, input) {
-        const tool = this.toolsByName.get(name);
-        if (!tool) {
-            return `Tool error: Unknown tool "${name}".`;
-        }
-        try {
-            const inputObject = ensureInputObject(input);
-            return await tool.execute(inputObject);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : "Unknown tool failure";
-            return `Tool error (${name}): ${message}`;
+export { ToolRegistry };
+/**
+ * Create a ToolRegistry with the SDK's core tools plus indexer-specific tools
+ * when a ProjectIndex is available.
+ */
+export function createToolRegistry(config, projectIndex) {
+    const hooks = projectIndex
+        ? {
+            afterWrite: (relPath, content) => projectIndex.reindexFile(relPath, content),
+            afterEdit: (relPath, content) => projectIndex.reindexFile(relPath, content),
         }
+        : undefined;
+    const tools = [
+        createReadFileTool(config),
+        createWriteFileTool(config, hooks ? { afterWrite: hooks.afterWrite } : undefined),
+        createEditFileTool(config, hooks ? { afterEdit: hooks.afterEdit } : undefined),
+        createSearchTool(config),
+        createListFilesTool(config),
+        createRunCommandTool(config),
+    ];
+    if (projectIndex) {
+        tools.splice(1, 0, createReadSymbolTool(config, projectIndex));
+        tools.splice(2, 0, createFindReferencesTool(projectIndex));
+        tools.splice(3, 0, createGetDependenciesTool(projectIndex));
+        tools.splice(4, 0, createSearchCodeMapTool(projectIndex));
     }
+    return new ToolRegistry(tools);
 }

package/dist/src/tools/search-code-map.js

@@ -1,4 +1,4 @@
-import { expectNonEmptyString, expectOptionalNumber, } from "./helpers.js";
+import { expectNonEmptyString, expectOptionalNumber } from "@minicode/agent-sdk";
 const DEFAULT_LIMIT = 30;
 function matchesPattern(text, pattern) {
     const lowerText = text.toLowerCase();