@sean.holung/minicode 0.2.1 → 0.2.3

package/README.md

@@ -2,8 +2,6 @@
 
 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)
@@ -23,7 +21,7 @@ OPENAI_BASE_URL=http://localhost:1234/v1
 OPENAI_API_KEY=
 MAX_STEPS=50
 MAX_TOKENS=4096
-MAX_CONTEXT_TOKENS=60000
+MAX_CONTEXT_TOKENS=24000
 WORKSPACE_ROOT=.
 COMMAND_TIMEOUT_MS=30000
 MAX_FILE_SIZE_BYTES=1000000
@@ -194,6 +192,8 @@ Nothing is written inside your workspace; config and cache live under `~/.minico
 | `CONFIRM_DESTRUCTIVE`   | No              | `true`                     | If `true`, blocks destructive shell commands unless confirmed                                                                         |
 | `KEEP_RECENT_MESSAGES`  | No              | `12`                       | Minimum number of latest messages kept during trimming                                                                                |
 | `LOOP_DETECTION_WINDOW` | No              | `6`                        | Window for repeated tool-call loop detection                                                                                          |
+| `COMPACTION_THRESHOLD`  | No              | `0.8`                      | Context fullness ratio (0–1) at which auto-compaction triggers                                                                        |
+| `COMPACTION_MODEL`      | No              | none                       | Model for LLM-based compaction summaries. When set, `/compact` and auto-compaction use this model instead of mechanical truncation. Use a small, fast model (e.g. your local model). |
 
 
 ### `agent.config.json`
@@ -215,7 +215,8 @@ Create `agent.config.json` in `~/.minicode/` for user-level defaults, or in the
   "keepRecentMessages": 12,
   "loopDetectionWindow": 6,
   "openAiBaseUrl": "http://localhost:1234/v1",
-  "openAiApiKey": ""
+  "openAiApiKey": "",
+  "compactionModel": ""
 }
 ```
 
@@ -235,6 +236,8 @@ Field mapping:
 - `loopDetectionWindow` ↔ `LOOP_DETECTION_WINDOW`
 - `openAiBaseUrl` ↔ `OPENAI_BASE_URL`
 - `openAiApiKey` ↔ `OPENAI_API_KEY`
+- `compactionThreshold` ↔ `COMPACTION_THRESHOLD`
+- `compactionModel` ↔ `COMPACTION_MODEL`
 
 ## Usage
 

package/dist/src/agent/config.js

@@ -27,6 +27,11 @@ export function formatConfigForDisplay(config) {
         "commandDenylist: " + config.commandDenylist.length + " patterns",
         "openAiBaseUrl: " + config.openAiBaseUrl,
         "openAiApiKey: " + (config.openAiApiKey ? "***" : "(unset)"),
+        "enableFileReadDedup: " + (config.enableFileReadDedup ?? false),
+        "enableAdaptiveKeepRecent: " + (config.enableAdaptiveKeepRecent ?? false),
+        "enableToolOutputTruncation: " + (config.enableToolOutputTruncation ?? false),
+        "compactionThreshold: " + (config.compactionThreshold ?? "(disabled)"),
+        "compactionModel: " + (config.compactionModel ?? "(disabled — using mechanical compaction)"),
     ];
     return lines.join("\n");
 }
@@ -136,7 +141,7 @@ export async function loadAgentConfig(cwd = process.cwd()) {
             "zai-org/glm-4.7-flash",
         maxSteps: parseNumber(process.env.MAX_STEPS, fileConfig.maxSteps ?? 50),
         maxTokens: parseNumber(process.env.MAX_TOKENS, fileConfig.maxTokens ?? 4096),
-        maxContextTokens: parseNumber(process.env.MAX_CONTEXT_TOKENS, fileConfig.maxContextTokens ?? 120_000),
+        maxContextTokens: parseNumber(process.env.MAX_CONTEXT_TOKENS, fileConfig.maxContextTokens ?? 40_000),
         workspaceRoot,
         commandTimeoutMs: parseNumber(process.env.COMMAND_TIMEOUT_MS, fileConfig.commandTimeout ?? 30_000),
         maxFileSizeBytes: parseNumber(process.env.MAX_FILE_SIZE_BYTES, fileConfig.maxFileSizeBytes ?? 1_000_000),
@@ -144,8 +149,15 @@ export async function loadAgentConfig(cwd = process.cwd()) {
         confirmDestructive: parseBoolean(process.env.CONFIRM_DESTRUCTIVE, fileConfig.confirmDestructive ?? true),
         keepRecentMessages: parseNumber(process.env.KEEP_RECENT_MESSAGES, fileConfig.keepRecentMessages ?? 12),
         loopDetectionWindow: parseNumber(process.env.LOOP_DETECTION_WINDOW, fileConfig.loopDetectionWindow ?? 6),
-        maxToolOutputChars: parseNumber(process.env.MAX_TOOL_OUTPUT_CHARS, fileConfig.maxToolOutputChars ?? 15_000),
+        maxToolOutputChars: parseNumber(process.env.MAX_TOOL_OUTPUT_CHARS, fileConfig.maxToolOutputChars ?? 8_000),
         openAiBaseUrl: rawBaseUrl,
         ...(openAiApiKey !== undefined ? { openAiApiKey } : {}),
+        enableFileReadDedup: parseBoolean(process.env.ENABLE_FILE_READ_DEDUP, fileConfig.enableFileReadDedup ?? true),
+        enableAdaptiveKeepRecent: parseBoolean(process.env.ENABLE_ADAPTIVE_KEEP_RECENT, fileConfig.enableAdaptiveKeepRecent ?? true),
+        enableToolOutputTruncation: parseBoolean(process.env.ENABLE_TOOL_OUTPUT_TRUNCATION, fileConfig.enableToolOutputTruncation ?? true),
+        compactionThreshold: parseNumber(process.env.COMPACTION_THRESHOLD, fileConfig.compactionThreshold ?? 0.8),
+        ...(process.env.COMPACTION_MODEL ?? fileConfig.compactionModel
+            ? { compactionModel: process.env.COMPACTION_MODEL ?? fileConfig.compactionModel }
+            : {}),
     };
 }

package/dist/src/index.js

@@ -44,7 +44,7 @@ async function createAgentRuntime(verbose, onProgress) {
             verbose,
             ...(session ? { session } : {}),
             ...(projectIndex !== undefined
-                ? { getCodeMap: () => projectIndex.getCodeMap() }
+                ? { getCodeMap: (focusSymbols) => projectIndex.getCodeMap(undefined, focusSymbols) }
                 : {}),
             ...(onProgress ? { onProgress } : {}),
         });
@@ -98,7 +98,7 @@ async function runInteractive(verbose, initialTask) {
             break;
         }
         if (trimmed === "/help") {
-            console.log('Commands: "/help", "/config", "/save [label]", "/load [label]", "/sessions", "/exit"');
+            console.log('Commands: "/help", "/config", "/compact", "/save [label]", "/load [label]", "/sessions", "/exit"');
             console.log("Start with --verbose or -v to log prompts, responses, and tool calls.");
             continue;
         }
@@ -106,6 +106,20 @@ async function runInteractive(verbose, initialTask) {
             console.log("\n" + formatConfigForDisplay(config) + "\n");
             continue;
         }
+        if (trimmed === "/compact") {
+            const session = agent.getSession();
+            const tokensBefore = session.getTokenEstimate();
+            const result = session.compact(config.keepRecentMessages);
+            if (result) {
+                console.log(`Compacted: ${result.removedMessages} messages summarized, ` +
+                    `${result.previousTokens} → ${result.newTokens} tokens ` +
+                    `(saved ${result.previousTokens - result.newTokens} tokens)`);
+            }
+            else {
+                console.log(`Nothing to compact (${tokensBefore} tokens, ${session.getMessages().length} messages).`);
+            }
+            continue;
+        }
         if (trimmed === "/save" || trimmed.startsWith("/save ")) {
             const label = trimmed.slice("/save".length).trim() || undefined;
             try {

package/dist/src/indexer/code-map.js

@@ -12,12 +12,42 @@ function formatSymbol(symbol, indent, isMethod) {
 function isEntryPointFile(filePath) {
     return filePath === "src/index.ts" || filePath.endsWith("/index.ts");
 }
-function createSymbolRanker(edges) {
+/**
+ * Build the set of symbols related to focus symbols via dependency edges.
+ * Expands 1 hop outbound (what focus symbols depend on) and 1 hop inbound
+ * (what depends on focus symbols).
+ */
+function expandFocusSet(focusSymbols, edges) {
+    const expanded = new Set(focusSymbols);
+    for (const edge of edges) {
+        // Outbound: focus symbol depends on something
+        if (focusSymbols.has(edge.from)) {
+            expanded.add(edge.to);
+        }
+        // Inbound: something depends on focus symbol
+        if (focusSymbols.has(edge.to)) {
+            expanded.add(edge.from);
+        }
+    }
+    return expanded;
+}
+function createSymbolRanker(edges, focusSymbols) {
     const refCount = new Map();
     for (const e of edges) {
         refCount.set(e.to, (refCount.get(e.to) ?? 0) + 1);
     }
+    // Expand focus set to include 1-hop neighbors in the dependency graph
+    const boosted = focusSymbols?.size
+        ? expandFocusSet(focusSymbols, edges)
+        : undefined;
     return (a, b) => {
+        // Focus-boosted symbols always sort first
+        if (boosted) {
+            const aFocused = boosted.has(a.qualifiedName);
+            const bFocused = boosted.has(b.qualifiedName);
+            if (aFocused !== bFocused)
+                return aFocused ? -1 : 1;
+        }
         if (a.exported !== b.exported)
             return a.exported ? -1 : 1;
         const refA = refCount.get(a.qualifiedName) ?? 0;
@@ -31,20 +61,37 @@ function createSymbolRanker(edges) {
 }
 /**
  * Generate a compact code map from symbols grouped by file.
- * Ranks symbols by: exported > high reference count > entry points.
+ * Ranks symbols by: focus-boosted > exported > high reference count > entry points.
  * When over budget, truncates with a footer.
+ *
+ * @param focusSymbols Optional set of symbol qualified names to boost to the top.
+ *   These symbols (and their 1-hop dependency neighbors) will be ranked above all
+ *   others, ensuring they survive truncation within the token budget.
  */
-export function generateCodeMap(symbolsByFile, tokenBudget = DEFAULT_TOKEN_BUDGET, dependencyEdges) {
+export function generateCodeMap(symbolsByFile, tokenBudget = DEFAULT_TOKEN_BUDGET, dependencyEdges, focusSymbols) {
     const totalCount = [...symbolsByFile.values()].reduce((sum, syms) => sum + syms.length, 0);
     const lines = ["# Project Code Map", ""];
     const rank = dependencyEdges
-        ? createSymbolRanker(dependencyEdges)
+        ? createSymbolRanker(dependencyEdges, focusSymbols)
         : (a, b) => (a.exported === b.exported ? 0 : a.exported ? -1 : 1);
     let totalTokens = estimateTokens(lines.join("\n"));
     let truncatedSymbols = 0;
     let shownCount = 0;
     const filesWithTruncation = new Set();
-    const sortedFiles = [...symbolsByFile.keys()].sort();
+    // When we have focus symbols, sort files so that files containing
+    // focused symbols come first in the code map.
+    const boosted = focusSymbols?.size && dependencyEdges
+        ? expandFocusSet(focusSymbols, dependencyEdges)
+        : undefined;
+    const sortedFiles = [...symbolsByFile.keys()].sort((a, b) => {
+        if (boosted) {
+            const aHasFocus = symbolsByFile.get(a)?.some((s) => boosted.has(s.qualifiedName)) ?? false;
+            const bHasFocus = symbolsByFile.get(b)?.some((s) => boosted.has(s.qualifiedName)) ?? false;
+            if (aHasFocus !== bHasFocus)
+                return aHasFocus ? -1 : 1;
+        }
+        return a.localeCompare(b);
+    });
     for (const filePath of sortedFiles) {
         const symbols = symbolsByFile.get(filePath);
         if (!symbols?.length)

package/dist/src/indexer/focus-tracker.js

@@ -0,0 +1,63 @@
+/**
+ * Tracks which symbols the user/agent is actively working with.
+ * Used to dynamically re-rank the code map so that relevant symbols
+ * survive truncation within the fixed token budget.
+ *
+ * Focus is derived from:
+ * - Symbol names in tool calls (read_symbol, find_references, get_dependencies)
+ * - Symbol names mentioned in user messages (fuzzy match against index)
+ */
+const MAX_FOCUS_SYMBOLS = 30;
+export class FocusTracker {
+    focused = new Map();
+    generation = 0;
+    /**
+     * Record a symbol as being actively focused on.
+     * More recent additions have higher priority.
+     */
+    addSymbol(qualifiedName) {
+        this.generation += 1;
+        this.focused.set(qualifiedName, this.generation);
+        // Evict oldest entries if we exceed the limit
+        if (this.focused.size > MAX_FOCUS_SYMBOLS) {
+            let oldestKey = null;
+            let oldestGen = Infinity;
+            for (const [key, gen] of this.focused) {
+                if (gen < oldestGen) {
+                    oldestGen = gen;
+                    oldestKey = key;
+                }
+            }
+            if (oldestKey) {
+                this.focused.delete(oldestKey);
+            }
+        }
+    }
+    /**
+     * Record multiple symbols at once (e.g. from dependency expansion).
+     */
+    addSymbols(qualifiedNames) {
+        for (const name of qualifiedNames) {
+            this.addSymbol(name);
+        }
+    }
+    /**
+     * Get the current set of focused symbol qualified names.
+     */
+    getFocusedSymbols() {
+        return new Set(this.focused.keys());
+    }
+    /**
+     * Check if a symbol is currently focused.
+     */
+    hasFocus(qualifiedName) {
+        return this.focused.has(qualifiedName);
+    }
+    /**
+     * Clear all focus tracking.
+     */
+    clear() {
+        this.focused.clear();
+        this.generation = 0;
+    }
+}

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

@@ -66,8 +66,8 @@ export function createProjectIndex(symbols, files, dependencyEdges, plugins, pro
             }
             return [...result.values()];
         },
-        getCodeMap(tokenBudget) {
-            return generateCodeMap(files, tokenBudget, dependencyEdges);
+        getCodeMap(tokenBudget, focusSymbols) {
+            return generateCodeMap(files, tokenBudget, dependencyEdges, focusSymbols);
         },
         reindexFile(filePath, content) {
             const relPath = path.isAbsolute(filePath)

package/dist/src/ui/cli-ink.js

@@ -85,7 +85,7 @@ export async function runInkCli(verbose, initialTask) {
             verbose,
             ...(session ? { session } : {}),
             ...(projectIndex !== undefined
-                ? { getCodeMap: () => projectIndex.getCodeMap() }
+                ? { getCodeMap: (focusSymbols) => projectIndex.getCodeMap(undefined, focusSymbols) }
                 : {}),
             ...(verbose
                 ? {
@@ -121,7 +121,7 @@ export async function runInkCli(verbose, initialTask) {
         if (trimmed === "/help") {
             store.addItem({
                 type: "system",
-                content: 'Commands: "/help", "/config", "/save [label]", "/load [label]", "/sessions", "/exit".',
+                content: 'Commands: "/help", "/config", "/compact", "/save [label]", "/load [label]", "/sessions", "/exit".',
             });
             return;
         }
@@ -132,6 +132,26 @@ export async function runInkCli(verbose, initialTask) {
             });
             return;
         }
+        if (trimmed === "/compact") {
+            const session = agent.getSession();
+            const result = await agent.compactContext();
+            if (result) {
+                const method = config.compactionModel ? "LLM" : "mechanical";
+                store.addItem({
+                    type: "system",
+                    content: `Compacted (${method}): ${result.removedMessages} messages summarized, ` +
+                        `${result.previousTokens} → ${result.newTokens} tokens ` +
+                        `(saved ${result.previousTokens - result.newTokens} tokens)`,
+                });
+            }
+            else {
+                store.addItem({
+                    type: "system",
+                    content: `Nothing to compact (${session.getTokenEstimate()} tokens, ${session.getMessages().length} messages).`,
+                });
+            }
+            return;
+        }
         if (trimmed === "/save" || trimmed.startsWith("/save ")) {
             const label = trimmed.slice("/save".length).trim() || undefined;
             try {

package/dist/tests/agent.test.js

@@ -102,6 +102,68 @@ test("agent omits code map when projectIndex is not provided", async () => {
     await agent.runTurn("Hello");
     assert.ok(!capturedSystem.includes("[Project Code Map]"));
 });
+test("agent caps thinking text in session but preserves final response", async () => {
+    const longThinking = "I need to analyze this carefully. ".repeat(20); // ~660 chars, well over 200
+    const finalResponse = "Here is the complete and detailed answer that should not be truncated at all. ".repeat(10); // ~780 chars
+    const responses = [
+        {
+            text: longThinking,
+            toolCalls: [{ id: "tool-1", name: "echo_tool", input: { value: "ok" } }],
+            stopReason: "tool_use",
+            usage: { inputTokens: 10, outputTokens: 8 },
+        },
+        {
+            text: finalResponse,
+            toolCalls: [],
+            stopReason: "end_turn",
+            usage: { inputTokens: 12, outputTokens: 6 },
+        },
+    ];
+    const agent = new CodingAgent({
+        config: createTestAgentConfig("/tmp"),
+        modelClient: new SequenceModelClient(responses),
+        toolRegistry: new ToolRegistry([createEchoTool()]),
+    });
+    const { text } = await agent.runTurn("Do something complex");
+    const messages = agent.getSession().getMessages();
+    // Thinking message (assistant with toolCalls) should be capped at ~200 chars + "..."
+    const thinkingMsg = messages[1];
+    assert.equal(thinkingMsg?.role, "assistant");
+    assert.ok(thinkingMsg?.role === "assistant" && thinkingMsg.content.length <= 204, `Thinking should be capped but was ${thinkingMsg?.role === "assistant" ? thinkingMsg.content.length : "?"} chars`);
+    assert.ok(thinkingMsg?.role === "assistant" && thinkingMsg.content.endsWith("..."), "Capped thinking should end with ellipsis");
+    // Final response (assistant without toolCalls) should be preserved in full
+    const finalMsg = messages[3];
+    assert.equal(finalMsg?.role, "assistant");
+    assert.equal(text, finalResponse);
+    assert.ok(finalMsg?.role === "assistant" && finalMsg.content === finalResponse, "Final response should not be truncated");
+});
+test("agent preserves short thinking text without capping", async () => {
+    const shortThinking = "Let me check.";
+    const responses = [
+        {
+            text: shortThinking,
+            toolCalls: [{ id: "tool-1", name: "echo_tool", input: { value: "ok" } }],
+            stopReason: "tool_use",
+            usage: { inputTokens: 10, outputTokens: 8 },
+        },
+        {
+            text: "Done.",
+            toolCalls: [],
+            stopReason: "end_turn",
+            usage: { inputTokens: 12, outputTokens: 6 },
+        },
+    ];
+    const agent = new CodingAgent({
+        config: createTestAgentConfig("/tmp"),
+        modelClient: new SequenceModelClient(responses),
+        toolRegistry: new ToolRegistry([createEchoTool()]),
+    });
+    await agent.runTurn("Quick task");
+    const messages = agent.getSession().getMessages();
+    const thinkingMsg = messages[1];
+    assert.equal(thinkingMsg?.role, "assistant");
+    assert.ok(thinkingMsg?.role === "assistant" && thinkingMsg.content === shortThinking, "Short thinking should be preserved verbatim");
+});
 test("agent includes code map in system prompt when projectIndex is provided", async () => {
     const root = path.resolve(import.meta.dirname, "..");
     const projectIndex = await buildProjectIndex(root);

package/node_modules/@anthropic-ai/sdk/.github/logo.svg

@@ -0,0 +1,3 @@
+<svg width="248" height="248" viewBox="0 0 248 248" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M52.4285 162.873L98.7844 136.879L99.5485 134.602L98.7844 133.334H96.4921L88.7237 132.862L62.2346 132.153L39.3113 131.207L17.0249 130.026L11.4214 128.844L6.2 121.873L6.7094 118.447L11.4214 115.257L18.171 115.847L33.0711 116.911L55.485 118.447L71.6586 119.392L95.728 121.873H99.5485L100.058 120.337L98.7844 119.392L97.7656 118.447L74.5877 102.732L49.4995 86.1905L36.3823 76.62L29.3779 71.7757L25.8121 67.2858L24.2839 57.3608L30.6515 50.2716L39.3113 50.8623L41.4763 51.4531L50.2636 58.1879L68.9842 72.7209L93.4357 90.6804L97.0015 93.6343L98.4374 92.6652L98.6571 91.9801L97.0015 89.2625L83.757 65.2772L69.621 40.8192L63.2534 30.6579L61.5978 24.632C60.9565 22.1032 60.579 20.0111 60.579 17.4246L67.8381 7.49965L71.9133 6.19995L81.7193 7.49965L85.7946 11.0443L91.9074 24.9865L101.714 46.8451L116.996 76.62L121.453 85.4816L123.873 93.6343L124.764 96.1155H126.292V94.6976L127.566 77.9197L129.858 57.3608L132.15 30.8942L132.915 23.4505L136.608 14.4708L143.994 9.62643L149.725 12.344L154.437 19.0788L153.8 23.4505L150.998 41.6463L145.522 70.1215L141.957 89.2625H143.994L146.414 86.7813L156.093 74.0206L172.266 53.698L179.398 45.6635L187.803 36.802L193.152 32.5484H203.34L210.726 43.6549L207.415 55.1159L196.972 68.3492L188.312 79.5739L175.896 96.2095L168.191 109.585L168.882 110.689L170.738 110.53L198.755 104.504L213.91 101.787L231.994 98.7149L240.144 102.496L241.036 106.395L237.852 114.311L218.495 119.037L195.826 123.645L162.07 131.592L161.696 131.893L162.137 132.547L177.36 133.925L183.855 134.279H199.774L229.447 136.524L237.215 141.605L241.8 147.867L241.036 152.711L229.065 158.737L213.019 154.956L175.45 145.977L162.587 142.787H160.805V143.85L171.502 154.366L191.242 172.089L215.82 195.011L217.094 200.682L213.91 205.172L210.599 204.699L188.949 188.394L180.544 181.069L161.696 165.118H160.422V166.772L164.752 173.152L187.803 207.771L188.949 218.405L187.294 221.832L181.308 223.959L174.813 222.777L161.187 203.754L147.305 182.486L136.098 163.345L134.745 164.2L128.075 235.42L125.019 239.082L117.887 241.8L111.902 237.31L108.718 229.984L111.902 215.452L115.722 196.547L118.779 181.541L121.58 162.873L123.291 156.636L123.14 156.219L121.773 156.449L107.699 175.752L86.304 204.699L69.3663 222.777L65.291 224.431L58.2867 220.768L58.9235 214.27L62.8713 208.48L86.304 178.705L100.44 160.155L109.551 149.507L109.462 147.967L108.959 147.924L46.6977 188.512L35.6182 189.93L30.7788 185.44L31.4156 178.115L33.7079 175.752L52.4285 162.873Z" fill="#D97757"/>
+</svg>