@sean.holung/minicode 0.3.4 → 0.3.5

package/README.md

@@ -1,14 +1,16 @@
 # minicode
 
-A graph-native coding agent and code exploration environment built around structural context optimization. It started as a way to make local models viable under tighter context budgets, and it now also works well with hosted frontier models through the same runtime, web UI, and OpenAI-compatible serve mode.
+A graph-native coding agent and code exploration environment built around structural context optimization that leverages symbol-aware retrieval, dependency graphs, and targeted context. It started as a way to make local models viable under tighter context budgets, and it now also works well with hosted frontier models through the same runtime, web UI, and OpenAI-compatible serve mode. 
+
+minicode is built on a simple bet: models perform better when you give them less, but better context. Bloated context directly degrades output quality: attention dilutes, positional biases cause mid-context information loss, and inference latency grows as token count increases.
+
+Read operations dominate token usage in typical agent sessions; minicode addresses this by optimizing for **specific languages**. It indexes your project at startup with language plugins, injects a compact **code map** (signatures only) into the system prompt, and exposes symbol-level tools (`read_symbol`, `find_references`, `get_dependencies`) so the model reads only what it needs instead of entire files. This also enables the agent to walk the code structurally to gain a better understanding of the codebase at a structural level. TypeScript and JavaScript support come built-in, with custom language plugins leaving room for broader language support over time.
 
 _Run `minicode serve` to get the web UI on localhost: chat, tool activity, session controls, model switching, symbol focus, annotations, and a live dependency graph._
 
 <img width="1723" height="920" alt="Screenshot 2026-03-26 at 6 30 23 PM" src="https://github.com/user-attachments/assets/499c8dc7-cc2b-4125-abd5-32b2fc9795ea" />
 
 
-Read operations dominate token usage in typical agent sessions; minicode addresses this by optimizing for **specific languages**. It indexes your project at startup with language plugins, injects a compact **code map** (signatures only) into the system prompt, and exposes symbol-level tools (`read_symbol`, `find_references`, `get_dependencies`) so the model reads only what it needs instead of entire files. TypeScript and JavaScript support come built-in, with custom language plugins leaving room for broader language support over time.
-
 ## Quick Start (LM Studio)
 
 ```bash

package/dist/scripts/run-benchmarks.js

@@ -12,15 +12,20 @@
  *   --out <path>        Write the JSON report to a file
  *
  * Environment:
- *   MODEL_PROVIDER, MODEL, OPENAI_BASE_URL, OPENAI_API_KEY, ANTHROPIC_API_KEY
- *   — same as minicode runtime config.
+ *   MODEL_PROVIDER, MODEL, OPENAI_BASE_URL, OPENAI_API_KEY, OPENROUTER_API_KEY, ANTHROPIC_API_KEY
+ *   — benchmark-layer overrides for benchmarks/benchmark.config.json.
  */
+import { readFileSync, existsSync } from "node:fs";
 import path from "node:path";
+import { homedir } from "node:os";
 import { writeFile } from "node:fs/promises";
-import { createModelClient, createReadFileTool, createWriteFileTool, createEditFileTool, createSearchTool, createListFilesTool, createRunCommandTool, } from "@minicode/agent-sdk";
+import { createModelClient, } from "@minicode/agent-sdk";
+import { parse as parseDotenv } from "dotenv";
 import { loadBenchmarkTasks, loadBenchmarkTask } from "../src/benchmark/task-loader.js";
 import { runBenchmarkSuite } from "../src/benchmark/runner.js";
 import { buildReport, formatReport } from "../src/benchmark/reporter.js";
+import { buildProjectIndex } from "../src/indexer/project-index.js";
+import { createToolRegistry } from "../src/tools/registry.js";
 export function parseArgs(argv) {
     const args = { variant: "ci" };
     for (let i = 0; i < argv.length; i++) {
@@ -48,25 +53,63 @@ export function parseArgs(argv) {
 /* ------------------------------------------------------------------ */
 /*  Config builder                                                     */
 /* ------------------------------------------------------------------ */
-export function buildConfig() {
-    const provider = (process.env.MODEL_PROVIDER ?? "openai-compatible");
-    const model = process.env.MODEL ?? "test-model";
+export function getBenchmarkConfigPath(repoRoot = process.cwd()) {
+    return path.resolve(repoRoot, "benchmarks", "benchmark.config.json");
+}
+function loadJsonConfigFile(configPath) {
+    if (!existsSync(configPath)) {
+        return {};
+    }
+    return JSON.parse(readFileSync(configPath, "utf8"));
+}
+function loadHomeEnvVars(homeEnvPath) {
+    if (!existsSync(homeEnvPath)) {
+        return {};
+    }
+    return parseDotenv(readFileSync(homeEnvPath, "utf8"));
+}
+function firstDefined(...values) {
+    return values.find((value) => value != null && value.length > 0);
+}
+function getNumberSetting(envValue, fileValue, fallback) {
+    if (envValue != null && envValue.length > 0) {
+        return Number(envValue);
+    }
+    return fileValue ?? fallback;
+}
+export function buildConfig(options = {}) {
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    const env = options.env ?? process.env;
+    const homeEnvPath = options.homeEnvPath ?? path.join(homedir(), ".minicode", ".env");
+    const configPath = options.configPath ?? getBenchmarkConfigPath(repoRoot);
+    const fileConfig = loadJsonConfigFile(configPath);
+    const homeEnv = loadHomeEnvVars(homeEnvPath);
+    const getShellOverride = (key) => env[key];
+    const getSecret = (key) => firstDefined(env[key], homeEnv[key]);
+    const provider = (firstDefined(getShellOverride("MODEL_PROVIDER"), fileConfig.modelProvider, "openai-compatible") ?? "openai-compatible");
+    const model = firstDefined(getShellOverride("MODEL"), fileConfig.model, "test-model") ?? "test-model";
+    const openAiBaseUrl = firstDefined(getShellOverride("OPENAI_BASE_URL"), fileConfig.openAiBaseUrl, "http://localhost:1234/v1") ?? "http://localhost:1234/v1";
+    const openAiApiKey = provider === "openai-compatible"
+        ? (openAiBaseUrl.includes("openrouter.ai")
+            ? firstDefined(getSecret("OPENROUTER_API_KEY"), getSecret("OPENAI_API_KEY"))
+            : getSecret("OPENAI_API_KEY"))
+        : undefined;
     return {
         modelProvider: provider,
         model,
-        maxSteps: Number(process.env.MAX_STEPS ?? "50"),
-        maxTokens: Number(process.env.MAX_TOKENS ?? "4096"),
-        maxContextTokens: Number(process.env.MAX_CONTEXT_TOKENS ?? "32000"),
-        workspaceRoot: process.cwd(),
-        commandTimeoutMs: Number(process.env.COMMAND_TIMEOUT_MS ?? "30000"),
-        maxFileSizeBytes: Number(process.env.MAX_FILE_SIZE_BYTES ?? "1000000"),
+        maxSteps: getNumberSetting(getShellOverride("MAX_STEPS"), fileConfig.maxSteps, 50),
+        maxTokens: getNumberSetting(getShellOverride("MAX_TOKENS"), fileConfig.maxTokens, 4096),
+        maxContextTokens: getNumberSetting(getShellOverride("MAX_CONTEXT_TOKENS"), fileConfig.maxContextTokens, 32000),
+        workspaceRoot: repoRoot,
+        commandTimeoutMs: getNumberSetting(getShellOverride("COMMAND_TIMEOUT_MS"), fileConfig.commandTimeoutMs, 30000),
+        maxFileSizeBytes: getNumberSetting(getShellOverride("MAX_FILE_SIZE_BYTES"), fileConfig.maxFileSizeBytes, 1000000),
         commandDenylist: [],
         confirmDestructive: false,
-        keepRecentMessages: Number(process.env.KEEP_RECENT_MESSAGES ?? "12"),
-        loopDetectionWindow: Number(process.env.LOOP_DETECTION_WINDOW ?? "6"),
-        maxToolOutputChars: Number(process.env.MAX_TOOL_OUTPUT_CHARS ?? "8000"),
-        openAiBaseUrl: process.env.OPENAI_BASE_URL ?? "http://localhost:1234/v1",
-        ...(process.env.OPENAI_API_KEY ? { openAiApiKey: process.env.OPENAI_API_KEY } : {}),
+        keepRecentMessages: getNumberSetting(getShellOverride("KEEP_RECENT_MESSAGES"), fileConfig.keepRecentMessages, 12),
+        loopDetectionWindow: getNumberSetting(getShellOverride("LOOP_DETECTION_WINDOW"), fileConfig.loopDetectionWindow, 6),
+        maxToolOutputChars: getNumberSetting(getShellOverride("MAX_TOOL_OUTPUT_CHARS"), fileConfig.maxToolOutputChars, 8000),
+        openAiBaseUrl,
+        ...(openAiApiKey ? { openAiApiKey } : {}),
     };
 }
 /* ------------------------------------------------------------------ */
@@ -94,8 +137,9 @@ export async function loadTasks(tasksDir, args) {
 /* ------------------------------------------------------------------ */
 async function main() {
     const args = parseArgs(process.argv.slice(2));
-    const config = buildConfig();
-    const tasksDir = path.resolve(process.cwd(), "benchmarks", "tasks");
+    const repoRoot = process.cwd();
+    const config = buildConfig({ repoRoot });
+    const tasksDir = path.resolve(repoRoot, "benchmarks", "tasks");
     console.log(`Benchmark runner starting...`);
     console.log(`  Provider: ${config.modelProvider}`);
     console.log(`  Model: ${config.model}`);
@@ -104,19 +148,20 @@ async function main() {
     console.log(`  Tasks: ${tasks.length}`);
     console.log("");
     const modelClient = createModelClient(config);
-    const tools = [
-        createReadFileTool(config),
-        createWriteFileTool(config),
-        createEditFileTool(config),
-        createSearchTool(config),
-        createListFilesTool(config),
-        createRunCommandTool(config),
-    ];
     const traces = await runBenchmarkSuite(tasks, {
         modelClient,
         config,
-        tools,
         variant: args.variant,
+        repoRoot,
+        isolateWorkspace: true,
+        createToolset: async (taskConfig) => {
+            const projectIndex = await buildProjectIndex(taskConfig.workspaceRoot);
+            const toolRegistry = createToolRegistry(taskConfig, projectIndex);
+            return {
+                tools: toolRegistry.getDefinitions(),
+                projectIndex,
+            };
+        },
         onTaskComplete: (taskId, trace) => {
             const dur = (trace.durationMs / 1000).toFixed(1);
             console.log(`  [done] ${taskId} (${dur}s, ${trace.toolCalls.length} tool calls)`);

package/dist/src/benchmark/runner.js

@@ -5,7 +5,17 @@
  * over tool-call instrumentation and trace capture.
  */
 import { execSync } from "node:child_process";
+import { cp, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import { CodingAgent, Session, ToolRegistry, } from "@minicode/agent-sdk";
+const COPY_SKIP_NAMES = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+]);
 function getGitCommitSha() {
     try {
         return execSync("git rev-parse HEAD", { encoding: "utf8" }).trim();
@@ -19,73 +29,146 @@ const STRUCTURAL_TOOLS = new Set([
     "find_references",
     "get_dependencies",
     "search_code_map",
+    "find_path",
 ]);
+function sanitizeTaskId(taskId) {
+    return taskId.replace(/[^a-z0-9-_]+/gi, "-");
+}
+function resolveSourceWorkspaceRoot(task, options) {
+    if (!task.workspaceRoot) {
+        return path.resolve(options.config.workspaceRoot);
+    }
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    return path.resolve(repoRoot, task.workspaceRoot);
+}
+function shouldCopyPath(src) {
+    const name = path.basename(src);
+    return !COPY_SKIP_NAMES.has(name);
+}
+async function prepareTaskWorkspace(task, options) {
+    const sourceWorkspaceRoot = resolveSourceWorkspaceRoot(task, options);
+    if (options.isolateWorkspace === false) {
+        return {
+            sourceWorkspaceRoot,
+            workspaceRoot: sourceWorkspaceRoot,
+            cleanup: async () => { },
+        };
+    }
+    const tempRoot = await mkdtemp(path.join(tmpdir(), "minicode-benchmark-"));
+    const isolatedWorkspaceRoot = path.join(tempRoot, sanitizeTaskId(task.id));
+    await cp(sourceWorkspaceRoot, isolatedWorkspaceRoot, {
+        recursive: true,
+        filter: shouldCopyPath,
+    });
+    return {
+        sourceWorkspaceRoot,
+        workspaceRoot: isolatedWorkspaceRoot,
+        cleanup: async () => {
+            await rm(tempRoot, { recursive: true, force: true });
+        },
+    };
+}
+function getTrackedSymbolNames(toolName, input) {
+    if (toolName === "find_path") {
+        const names = [input.from, input.to]
+            .filter((value) => typeof value === "string" && value.length > 0);
+        return [...new Set(names)];
+    }
+    const name = input.symbol ?? input.symbolName ?? input.name ?? input.query;
+    return typeof name === "string" && name.length > 0 ? [name] : [];
+}
+function trackStructuralFileReads(toolName, projectIndex, input, filesRead) {
+    if (!projectIndex || !STRUCTURAL_TOOLS.has(toolName)) {
+        return;
+    }
+    for (const symbolName of getTrackedSymbolNames(toolName, input)) {
+        const symbol = projectIndex.getSymbol(symbolName);
+        if (symbol) {
+            filesRead.add(symbol.filePath);
+        }
+    }
+}
 /**
  * Run a single benchmark task and return the captured trace.
  */
 export async function runBenchmarkTask(task, options) {
+    const workspace = await prepareTaskWorkspace(task, options);
     const captured = [];
     const filesRead = new Set();
     const symbolsQueried = new Set();
-    // Wrap each tool to capture calls
-    const instrumentedTools = options.tools.map((tool) => ({
-        ...tool,
-        execute: async (input) => {
-            const start = performance.now();
-            const output = await tool.execute(input);
-            const durationMs = performance.now() - start;
-            captured.push({
-                name: tool.name,
-                input,
-                output: output.length > 2000 ? output.slice(0, 2000) + "…[truncated]" : output,
-                durationMs,
-            });
-            // Track files read
-            if (tool.name === "read_file" || tool.name === "read_symbol") {
-                const filePath = input.path ?? input.file_path ?? input.filePath;
-                if (typeof filePath === "string")
-                    filesRead.add(filePath);
-            }
-            // Track symbol queries
-            if (STRUCTURAL_TOOLS.has(tool.name)) {
-                const sym = input.symbol ?? input.symbolName ?? input.name ?? input.query;
-                if (typeof sym === "string")
-                    symbolsQueried.add(sym);
-            }
-            return output;
-        },
-    }));
-    const registry = new ToolRegistry(instrumentedTools);
-    const session = new Session();
-    const agent = new CodingAgent({
-        config: options.config,
-        modelClient: options.modelClient,
-        toolRegistry: registry,
-        session,
-    });
-    const startedAt = new Date().toISOString();
-    const start = performance.now();
-    const { text, usage } = await agent.runTurn(task.prompt);
-    const durationMs = performance.now() - start;
-    const trace = {
-        taskId: task.id,
-        model: options.config.model,
-        variant: options.variant,
-        commitSha: getGitCommitSha(),
-        response: text,
-        toolCalls: captured,
-        filesRead: [...filesRead],
-        symbolsQueried: [...symbolsQueried],
-        usage: {
-            inputTokens: usage?.inputTokens ?? 0,
-            outputTokens: usage?.outputTokens ?? 0,
-            totalTokens: (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0),
-        },
-        durationMs,
-        startedAt,
-    };
-    options.onTaskComplete?.(task.id, trace);
-    return trace;
+    try {
+        const taskConfig = {
+            ...options.config,
+            workspaceRoot: workspace.workspaceRoot,
+        };
+        const toolset = options.createToolset
+            ? await options.createToolset(taskConfig, task)
+            : { tools: options.tools ?? [] };
+        // Wrap each tool to capture calls
+        const instrumentedTools = toolset.tools.map((tool) => ({
+            ...tool,
+            execute: async (input) => {
+                const start = performance.now();
+                const output = await tool.execute(input);
+                const durationMs = performance.now() - start;
+                captured.push({
+                    name: tool.name,
+                    input,
+                    output: output.length > 2000 ? output.slice(0, 2000) + "…[truncated]" : output,
+                    durationMs,
+                });
+                if (tool.name === "read_file") {
+                    const filePath = input.path ?? input.file_path ?? input.filePath;
+                    if (typeof filePath === "string") {
+                        filesRead.add(filePath);
+                    }
+                }
+                trackStructuralFileReads(tool.name, toolset.projectIndex, input, filesRead);
+                if (STRUCTURAL_TOOLS.has(tool.name)) {
+                    for (const symbolName of getTrackedSymbolNames(tool.name, input)) {
+                        symbolsQueried.add(symbolName);
+                    }
+                }
+                return output;
+            },
+        }));
+        const registry = new ToolRegistry(instrumentedTools);
+        const session = new Session();
+        const agent = new CodingAgent({
+            config: taskConfig,
+            modelClient: options.modelClient,
+            toolRegistry: registry,
+            session,
+        });
+        const startedAt = new Date().toISOString();
+        const start = performance.now();
+        const { text, usage } = await agent.runTurn(task.prompt);
+        const durationMs = performance.now() - start;
+        const trace = {
+            taskId: task.id,
+            model: taskConfig.model,
+            variant: options.variant,
+            commitSha: getGitCommitSha(),
+            sourceWorkspaceRoot: workspace.sourceWorkspaceRoot,
+            workspaceRoot: workspace.workspaceRoot,
+            response: text,
+            toolCalls: captured,
+            filesRead: [...filesRead],
+            symbolsQueried: [...symbolsQueried],
+            usage: {
+                inputTokens: usage?.inputTokens ?? 0,
+                outputTokens: usage?.outputTokens ?? 0,
+                totalTokens: (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0),
+            },
+            durationMs,
+            startedAt,
+        };
+        options.onTaskComplete?.(task.id, trace);
+        return trace;
+    }
+    finally {
+        await workspace.cleanup();
+    }
 }
 /**
  * Run all provided benchmark tasks sequentially.

package/dist/src/indexer/project-index.js

@@ -48,22 +48,26 @@ function buildAdjacencyTo(edges) {
     }
     return map;
 }
-function resolveSymbol(name, symbols) {
+function resolveSymbols(name, symbols) {
     const direct = symbols.get(name);
     if (direct)
-        return direct;
+        return [direct];
     const matches = [...symbols.values()].filter((sym) => getSymbolLookupNames(sym).includes(name));
     if (matches.length === 0) {
-        return undefined;
+        return [];
     }
     matches.sort((a, b) => Number(b.exported) - Number(a.exported) ||
         a.filePath.localeCompare(b.filePath) ||
         a.startLine - b.startLine ||
         a.qualifiedName.localeCompare(b.qualifiedName));
-    return matches[0];
+    return matches;
+}
+function resolveSymbol(name, symbols) {
+    return resolveSymbols(name, symbols)[0];
 }
 export function createProjectIndex(symbols, files, dependencyEdges, plugins, projectFiles, workspaceRoot) {
     let adjacencyFrom = buildAdjacencyFrom(dependencyEdges);
+    const root = path.resolve(workspaceRoot);
     function rebuildSymbolsMap() {
         const normalizedSymbols = normalizeIndexedSymbols(files);
         symbols.clear();
@@ -71,6 +75,42 @@ export function createProjectIndex(symbols, files, dependencyEdges, plugins, pro
             symbols.set(qualifiedName, symbol);
         }
     }
+    function rebuildDependencyEdges() {
+        for (const p of plugins) {
+            if (p.resolveDependencies) {
+                const allSymbols = [...symbols.values()];
+                const edges = p.resolveDependencies(allSymbols, projectFiles);
+                dependencyEdges.splice(0, dependencyEdges.length, ...edges);
+                adjacencyFrom = buildAdjacencyFrom(dependencyEdges);
+                break;
+            }
+        }
+    }
+    async function refreshFromWorkspace() {
+        const validExtensions = new Set(plugins.flatMap((p) => p.extensions));
+        const sourceFiles = [];
+        await collectSourceFiles(root, root, sourceFiles, validExtensions);
+        files.clear();
+        projectFiles.clear();
+        for (const relPath of sourceFiles) {
+            const plugin = getPluginForFile(relPath, plugins);
+            if (!plugin)
+                continue;
+            const absPath = path.join(root, relPath);
+            let content;
+            try {
+                content = await readFile(absPath, "utf8");
+            }
+            catch {
+                continue;
+            }
+            projectFiles.set(relPath, content);
+            const extracted = plugin.indexFile(relPath, content);
+            files.set(relPath, extracted);
+        }
+        rebuildSymbolsMap();
+        rebuildDependencyEdges();
+    }
     return {
         symbols,
         files,
@@ -81,6 +121,9 @@ export function createProjectIndex(symbols, files, dependencyEdges, plugins, pro
         getSymbol(name) {
             return resolveSymbol(name, symbols);
         },
+        getSymbolMatches(name) {
+            return resolveSymbols(name, symbols);
+        },
         getSymbolsInFile(filePath) {
             return files.get(filePath) ?? [];
         },
@@ -226,16 +269,9 @@ export function createProjectIndex(symbols, files, dependencyEdges, plugins, pro
             const extracted = plugin.indexFile(relPath, content);
             files.set(relPath, extracted);
             rebuildSymbolsMap();
-            for (const p of plugins) {
-                if (p.resolveDependencies) {
-                    const allSymbols = [...symbols.values()];
-                    const edges = p.resolveDependencies(allSymbols, projectFiles);
-                    dependencyEdges.splice(0, dependencyEdges.length, ...edges);
-                    adjacencyFrom = buildAdjacencyFrom(dependencyEdges);
-                    break;
-                }
-            }
+            rebuildDependencyEdges();
         },
+        refreshFromWorkspace,
     };
 }
 /**

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

@@ -276,10 +276,18 @@ export class AgentBridge {
             return undefined;
         return this.projectIndex.getSymbol(name);
     }
+    getSymbolMatches(name) {
+        if (!this.projectIndex)
+            return [];
+        return this.projectIndex.getSymbolMatches(name);
+    }
     getDependencies(symbolName, depth) {
         if (!this.projectIndex)
             return undefined;
-        const cone = this.projectIndex.getDependencyCone(symbolName, depth);
+        const matches = this.projectIndex.getSymbolMatches(symbolName);
+        if (matches.length !== 1)
+            return undefined;
+        const cone = this.projectIndex.getDependencyCone(matches[0].qualifiedName, depth);
         if (cone.length === 0)
             return undefined;
         return cone.map((sym) => ({
@@ -293,9 +301,10 @@ export class AgentBridge {
     getReferences(symbolName) {
         if (!this.projectIndex)
             return undefined;
-        const sym = this.projectIndex.getSymbol(symbolName);
-        if (!sym)
+        const matches = this.projectIndex.getSymbolMatches(symbolName);
+        if (matches.length !== 1)
             return undefined;
+        const sym = matches[0];
         // Find all edges pointing TO this symbol
         const refs = this.projectIndex.dependencyEdges
             .filter((e) => e.to === sym.qualifiedName || e.to === sym.name)