oioxo-mcp 0.1.1 → 0.1.3

package/dist/cli/agents.d.ts

@@ -1,3 +1,5 @@
+/** The instruction files for the agents that read them at session start. */
+export declare function writeAgentInstructions(root: string): Promise<string[]>;
 export interface InitOptions {
     /** Force-write the per-PROJECT files even when not detected. */
     all?: boolean;

package/dist/cli/agents.js

@@ -123,6 +123,46 @@ async function appendToml(file, entry) {
     await fs.writeFile(file, existing + block, 'utf8');
     return true;
 }
+// ---- agent INSTRUCTION files — why OIOXO fires BEFORE the session starts ----
+// MCP registration alone leaves it to the model's judgement whether to call the
+// tool. Instructions files are read by the agent at session start, so the very
+// first prompt already routes through OIOXO. Marked block, idempotent.
+const OIOXO_START = '<!-- oioxo:start -->';
+const OIOXO_END = '<!-- oioxo:end -->';
+const OIOXO_INSTRUCTIONS = `${OIOXO_START}
+## OIOXO context engine (use it FIRST)
+This project is wired to the OIOXO MCP server. BEFORE reading, searching or listing files yourself, ALWAYS call the \`get_context\` tool from the \`oioxo\` MCP server with the task as the query — it returns the minimal relevant code slice (10-20x fewer tokens than reading files). Use \`get_impact\` before refactors, \`get_skeleton\` to learn an API cheaply, and \`remember\` to persist durable project facts.
+${OIOXO_END}`;
+/** Append/refresh the marked OIOXO block in an instructions file. */
+async function writeInstructionBlock(file) {
+    let existing = '';
+    try {
+        existing = await fs.readFile(file, 'utf8');
+    }
+    catch { /* fresh file */ }
+    const start = existing.indexOf(OIOXO_START);
+    const end = existing.indexOf(OIOXO_END);
+    let next;
+    if (start >= 0 && end > start) {
+        next = existing.slice(0, start) + OIOXO_INSTRUCTIONS + existing.slice(end + OIOXO_END.length);
+    }
+    else {
+        next = existing ? existing.trimEnd() + '\n\n' + OIOXO_INSTRUCTIONS + '\n' : OIOXO_INSTRUCTIONS + '\n';
+    }
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, next, 'utf8');
+}
+/** The instruction files for the agents that read them at session start. */
+export async function writeAgentInstructions(root) {
+    const targets = [
+        path.join(root, '.github', 'copilot-instructions.md'), // Copilot reads automatically
+        path.join(root, 'CLAUDE.md'), // Claude Code reads at start
+        path.join(root, '.cursor', 'rules', 'oioxo.mdc'), // Cursor project rules
+    ];
+    for (const t of targets)
+        await writeInstructionBlock(t);
+    return targets;
+}
 export async function initAgents(root, opts = {}) {
     const home = opts.home ?? os.homedir();
     const entry = serverEntry(opts.command);
@@ -150,6 +190,9 @@ export async function initAgents(root, opts = {}) {
         console.log('  No agents detected. Run with --all to write the project configs anyway.');
         return;
     }
+    // Instruction files make agents call OIOXO from the FIRST prompt of a session.
+    await writeAgentInstructions(root);
+    console.log('  ✓ Agent instructions: .github/copilot-instructions.md, CLAUDE.md, .cursor/rules/oioxo.mdc');
     console.log('\nRestart your agent (or reload the window) and it will call OIOXO before reading files.');
     console.log('Not connected yet? Run `oioxo-mcp login`.');
 }

package/dist/core/capsule.js

@@ -6,6 +6,14 @@ export function buildCapsule(query, files, index, opts = {}) {
     const maxFiles = opts.maxFiles ?? 10;
     const maxChars = opts.maxChars ?? 24_000;
     const byPath = new Map(files.map((f) => [f.path, f]));
+    // TINY-PROJECT fast path: when everything fits in one capsule, retrieval
+    // theater only adds headers. Ship the whole project verbatim and claim ZERO
+    // savings — honesty here is what makes the 90% on real repos believable.
+    const totalChars = files.reduce((n, f) => n + f.content.length, 0);
+    if (totalChars > 0 && totalChars <= maxChars * 0.8) {
+        const text = files.map((f) => `// ${f.path}\n${f.content}`).join('\n\n');
+        return { text, files: files.map((f) => f.path), savedTokens: 0, chunks: [] };
+    }
     const chunks = index.retrieve(query, topChunks);
     // Anchors: distinct files behind the top chunks (order of first appearance).
     const anchors = [];
@@ -26,17 +34,50 @@ export function buildCapsule(query, files, index, opts = {}) {
     }
     const parts = [];
     const anchorSet = new Set(anchors);
-    // 1) Anchor chunks: the exact code in play, full text, with line refs.
+    // 1) Anchor excerpts. Chunks overlap by design (12-line windows), so emit
+    //    MERGED line ranges per file — overlap shipped twice is pure waste. And
+    //    when the merged range covers most of a small file, ship the whole file
+    //    once instead (simpler for the agent, fewer tokens than range headers).
+    const rangesByFile = new Map();
     for (const c of chunks) {
-        parts.push(`// ${c.path}:${c.startLine}-${c.endLine}\n${c.text}`);
+        const list = rangesByFile.get(c.path) ?? [];
+        list.push({ start: c.startLine, end: c.endLine });
+        rangesByFile.set(c.path, list);
     }
-    // 2) Neighbor files: skeletons only.
+    for (const [p, ranges] of rangesByFile) {
+        const f = byPath.get(p);
+        if (!f)
+            continue;
+        const lines = f.content.split('\n');
+        ranges.sort((a, b) => a.start - b.start);
+        const merged = [];
+        for (const r of ranges) {
+            const last = merged[merged.length - 1];
+            if (last && r.start <= last.end + 1)
+                last.end = Math.max(last.end, r.end);
+            else
+                merged.push({ ...r });
+        }
+        const covered = merged.reduce((n, r) => n + (r.end - r.start + 1), 0);
+        if (covered >= lines.length * 0.7) {
+            parts.push(`// ${p} (full)\n${f.content}`);
+        }
+        else {
+            for (const r of merged)
+                parts.push(`// ${p}:${r.start}-${r.end}\n${lines.slice(r.start - 1, r.end).join('\n')}`);
+        }
+    }
+    // 2) Neighbor files: skeletons only — unless the file is so small that its
+    //    skeleton wouldn't be cheaper, in which case skip it (the agent can ask).
     for (const p of slice) {
         if (anchorSet.has(p))
             continue;
         const f = byPath.get(p);
-        if (f)
-            parts.push(fileSkeleton(f.path, f.content));
+        if (!f)
+            continue;
+        const skel = fileSkeleton(f.path, f.content);
+        if (skel.length < f.content.length * 0.8)
+            parts.push(skel);
     }
     let text = parts.join('\n\n');
     if (text.length > maxChars)

package/dist/test/e2e.test.js

@@ -91,6 +91,11 @@ test('init writes + merges agent configs (project + global)', async () => {
     const codex = await fs.readFile(path.join(home, '.codex', 'config.toml'), 'utf8');
     assert.ok(codex.startsWith('model = "o4"'), 'existing TOML preserved');
     assert.ok(codex.includes('[mcp_servers.oioxo]'));
+    // Instruction files (the "fires first" mechanism) — written and idempotent.
+    const copilotIns = await fs.readFile(path.join(root, '.github', 'copilot-instructions.md'), 'utf8');
+    assert.ok(copilotIns.includes('get_context'), 'copilot instructions mention the tool');
+    const claudeMd = await fs.readFile(path.join(root, 'CLAUDE.md'), 'utf8');
+    assert.ok(claudeMd.includes('oioxo:start'));
     // Idempotent: second run must not duplicate the TOML section.
     await initAgents(root, { all: true, command: 'oioxo-mcp', home });
     const codex2 = await fs.readFile(path.join(home, '.codex', 'config.toml'), 'utf8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oioxo-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "OIOXO context engine for AI coding agents — feeds Claude Code, Copilot, Cursor and any MCP-capable agent the minimal relevant slice of your codebase, on-device, so your tokens go further.",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",