gigarag-claude-code 0.1.0

package/cli/state.js

@@ -0,0 +1,210 @@
+import { createRequire } from 'node:module';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { stateDir } from './paths.js';
+/**
+ * node:sqlite prints an ExperimentalWarning the first time it loads. A hook's
+ * stderr lands in the middle of somebody's terminal session, so the warning is
+ * swallowed for the one require and the original handler put back.
+ */
+function loadSqlite() {
+    const original = process.emitWarning;
+    process.emitWarning = ((warning, ...rest) => {
+        const type = typeof rest[0] === 'string' ? rest[0] : rest[0]?.type;
+        if (type === 'ExperimentalWarning' || (warning instanceof Error && warning.name === 'ExperimentalWarning'))
+            return;
+        return original.call(process, warning, ...rest);
+    });
+    try {
+        return createRequire(import.meta.url)('node:sqlite');
+    }
+    finally {
+        process.emitWarning = original;
+    }
+}
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS repos (
+  slug TEXT PRIMARY KEY, root TEXT NOT NULL, indexed_at INTEGER
+);
+CREATE TABLE IF NOT EXISTS files (
+  repo TEXT NOT NULL, path TEXT NOT NULL, hash TEXT NOT NULL,
+  dirty INTEGER NOT NULL DEFAULT 0, indexed_at INTEGER,
+  PRIMARY KEY (repo, path)
+);
+CREATE TABLE IF NOT EXISTS links (
+  repo TEXT NOT NULL, path TEXT NOT NULL, node_id TEXT NOT NULL,
+  PRIMARY KEY (repo, path, node_id)
+);
+CREATE TABLE IF NOT EXISTS nodes (
+  node_id TEXT PRIMARY KEY, ref TEXT, title TEXT NOT NULL, type TEXT,
+  tokens INTEGER, touched_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS nodes_touched ON nodes (touched_at DESC);
+CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+`;
+export class State {
+    db;
+    cache = new Map();
+    constructor(path = join(stateDir(), 'state.db')) {
+        // Private, like the key file beside it: memo titles and repository paths are not for other users of the machine.
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const { DatabaseSync } = loadSqlite();
+        this.db = new DatabaseSync(path);
+        // Several Claude Code sessions write to this file at once, each from its own hook process.
+        this.db.exec('PRAGMA busy_timeout = 2000; PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL;');
+        this.db.exec(SCHEMA);
+        try {
+            chmodSync(path, 0o600);
+        }
+        catch {
+            /* Windows has no chmod that means anything */
+        }
+    }
+    stmt(sql) {
+        let s = this.cache.get(sql);
+        if (!s) {
+            s = this.db.prepare(sql);
+            this.cache.set(sql, s);
+        }
+        return s;
+    }
+    close() {
+        this.db.close();
+    }
+    transaction(fn) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const out = fn();
+            this.db.exec('COMMIT');
+            return out;
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+    }
+    // --- meta ---------------------------------------------------------------
+    getMeta(key) {
+        return this.stmt('SELECT value FROM meta WHERE key = ?').get(key)?.value;
+    }
+    setMeta(key, value) {
+        this.stmt('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(key, value);
+    }
+    /**
+     * Takes a lock that lapses after `ttlMs`, in one transaction, so two workers starting together
+     * cannot both see it free. Returns whether this caller now holds it.
+     */
+    tryAcquire(key, ttlMs, now = Date.now()) {
+        return this.transaction(() => {
+            if (now - Number(this.getMeta(key) ?? 0) < ttlMs)
+                return false;
+            this.setMeta(key, String(now));
+            return true;
+        });
+    }
+    // --- repos and files ------------------------------------------------------
+    upsertRepo(slug, root, indexedAt) {
+        this.stmt(`INSERT INTO repos (slug, root, indexed_at) VALUES (?, ?, ?)
+       ON CONFLICT(slug) DO UPDATE SET root = excluded.root, indexed_at = COALESCE(excluded.indexed_at, indexed_at)`).run(slug, root, indexedAt ?? null);
+    }
+    listRepos() {
+        return this.stmt('SELECT slug, root, indexed_at FROM repos ORDER BY slug').all();
+    }
+    hasRepo(slug) {
+        return this.stmt('SELECT 1 AS x FROM repos WHERE slug = ?').get(slug) !== undefined;
+    }
+    repoBySlug(slug) {
+        return this.stmt('SELECT slug, root, indexed_at FROM repos WHERE slug = ?').get(slug);
+    }
+    files(repo) {
+        const rows = this.stmt('SELECT path, hash, dirty FROM files WHERE repo = ?').all(repo);
+        return new Map(rows.map(r => [r.path, r]));
+    }
+    nodesOf(repo, path) {
+        return this.stmt('SELECT node_id FROM links WHERE repo = ? AND path = ?').all(repo, path).map(r => r.node_id);
+    }
+    /** Nodes that only these paths point at, so deleting the files means deleting them. */
+    orphansIfRemoved(repo, paths) {
+        const removing = new Set(paths);
+        const out = new Map();
+        for (const path of paths) {
+            const orphaned = [];
+            for (const id of this.nodesOf(repo, path)) {
+                const holders = this.stmt('SELECT repo, path FROM links WHERE node_id = ?').all(id);
+                const remaining = holders.filter(h => !(h.repo === repo && removing.has(h.path)));
+                if (remaining.length === 0)
+                    orphaned.push(id);
+            }
+            out.set(path, orphaned);
+        }
+        return out;
+    }
+    /** Records that `path` was indexed at `hash` and now lives in `nodeIds`. */
+    recordFile(repo, path, hash, nodeIds, now = Date.now()) {
+        this.transaction(() => {
+            this.stmt(`INSERT INTO files (repo, path, hash, dirty, indexed_at) VALUES (?, ?, ?, 0, ?)
+         ON CONFLICT(repo, path) DO UPDATE SET hash = excluded.hash, dirty = 0, indexed_at = excluded.indexed_at`).run(repo, path, hash, now);
+            for (const id of nodeIds) {
+                this.stmt('INSERT OR IGNORE INTO links (repo, path, node_id) VALUES (?, ?, ?)').run(repo, path, id);
+            }
+        });
+    }
+    forgetFile(repo, path) {
+        this.transaction(() => {
+            this.stmt('DELETE FROM files WHERE repo = ? AND path = ?').run(repo, path);
+            this.stmt('DELETE FROM links WHERE repo = ? AND path = ?').run(repo, path);
+        });
+    }
+    markDirty(repo, path) {
+        const res = this.stmt('UPDATE files SET dirty = 1 WHERE repo = ? AND path = ?').run(repo, path);
+        return Number(res.changes) > 0;
+    }
+    /** A file saved without changing has nothing to re-index, so its flag goes. */
+    clearDirty(repo, path) {
+        this.stmt('UPDATE files SET dirty = 0 WHERE repo = ? AND path = ? AND dirty = 1').run(repo, path);
+    }
+    dirtyCount(repo) {
+        return this.stmt('SELECT COUNT(*) AS n FROM files WHERE repo = ? AND dirty = 1').get(repo).n;
+    }
+    dirtyFiles(repo) {
+        return this.stmt('SELECT path FROM files WHERE repo = ? AND dirty = 1 ORDER BY path').all(repo).map(r => r.path);
+    }
+    // --- the session index ------------------------------------------------------
+    upsertNode(row) {
+        this.stmt(`INSERT INTO nodes (node_id, ref, title, type, tokens, touched_at) VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(node_id) DO UPDATE SET
+         ref = COALESCE(excluded.ref, ref), title = excluded.title, type = COALESCE(excluded.type, type),
+         tokens = COALESCE(excluded.tokens, tokens), touched_at = excluded.touched_at`).run(row.node_id, row.ref ?? null, row.title, row.type ?? null, row.tokens ?? null, row.touched_at ?? Date.now());
+    }
+    deleteNode(nodeId) {
+        this.transaction(() => {
+            this.stmt('DELETE FROM nodes WHERE node_id = ?').run(nodeId);
+            this.stmt('DELETE FROM links WHERE node_id = ?').run(nodeId);
+        });
+    }
+    /** Replaces the synced set: rows not in `keep` are dropped, so deletions elsewhere disappear here. */
+    replaceNodes(rows) {
+        this.transaction(() => {
+            const known = new Map(this.stmt('SELECT node_id, tokens FROM nodes').all().map(r => [r.node_id, r.tokens]));
+            this.db.exec('DELETE FROM nodes');
+            for (const row of rows) {
+                this.stmt('INSERT INTO nodes (node_id, ref, title, type, tokens, touched_at) VALUES (?, ?, ?, ?, ?, ?)').run(row.node_id, row.ref, row.title, row.type, row.tokens ?? known.get(row.node_id) ?? null, row.touched_at);
+            }
+        });
+    }
+    recentNodes(limit) {
+        return this.stmt('SELECT node_id, ref, title, type, tokens, touched_at FROM nodes ORDER BY touched_at DESC LIMIT ?').all(limit);
+    }
+    nodeCount() {
+        return this.stmt('SELECT COUNT(*) AS n FROM nodes').get().n;
+    }
+}
+/** Opens the state, or returns undefined when it cannot be opened, so a hook never fails a session. */
+export function tryOpenState(path) {
+    try {
+        return new State(path);
+    }
+    catch {
+        return undefined;
+    }
+}

package/cli/ui.js

@@ -0,0 +1,66 @@
+import { stdin, stdout } from 'node:process';
+export const out = (line = '') => stdout.write(`${line}\n`);
+export const err = (line = '') => process.stderr.write(`${line}\n`);
+/** Pads columns so a list reads as a table without box drawing. */
+export function table(rows, gap = 2) {
+    const widths = [];
+    for (const row of rows)
+        row.forEach((cell, i) => (widths[i] = Math.max(widths[i] ?? 0, cell.length)));
+    return rows.map(row => row
+        .map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i] + gap)))
+        .join('')
+        .trimEnd());
+}
+/** Reads a line from the terminal without echoing it, for a key that should not land in scrollback. */
+export function promptHidden(question) {
+    return new Promise((resolve, reject) => {
+        if (!stdin.isTTY) {
+            reject(new Error('No terminal to prompt on.'));
+            return;
+        }
+        stdout.write(question);
+        let value = '';
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf8');
+        const done = (fn) => {
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdin.off('data', onData);
+            stdout.write('\n');
+            fn();
+        };
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === '\r' || ch === '\n')
+                    return done(() => resolve(value));
+                if (ch === '\u0003')
+                    return done(() => reject(new Error('Cancelled.')));
+                if (ch === '\u007f' || ch === '\b')
+                    value = value.slice(0, -1);
+                else if (ch >= ' ')
+                    value += ch;
+            }
+        };
+        stdin.on('data', onData);
+    });
+}
+/** First line of piped input, for `echo $KEY | gigarag login`. */
+export async function readStdinLine() {
+    const chunks = [];
+    for await (const chunk of stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8').split(/\r?\n/)[0]?.trim() ?? '';
+}
+export async function readStdinAll() {
+    const chunks = [];
+    for await (const chunk of stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UsageError';
+    }
+}

package/commands/gigadocs.md

@@ -0,0 +1,19 @@
+---
+description: Ingest external documentation into GigaRAG so it can be searched later
+argument-hint: <url>
+---
+
+Ingest the documentation at $ARGUMENTS into GigaRAG.
+
+If that is empty or is not a URL, ask me for one and stop.
+
+The bucket is named for the site: the hostname with dots turned into hyphens and any leading `www` dropped, so docs.stripe.com becomes `docs-stripe-com`. Find it with `list_buckets`, and create it if it is missing, with the site name as the title.
+
+Then:
+1. Fetch the page. Follow links that stay on the same host and sit under the same path prefix as the starting URL, up to two levels deep and at most 30 pages. Skip anchors, downloads, login pages and anything that repeats a page you already have. Say so if you hit the 30 page limit.
+2. For each page, first call `search_nodes` for its URL. If a memo already carries that URL, update it in place with `update_node` instead of creating a duplicate, so running this twice does not double the bucket.
+3. Otherwise `create_node`. The title is the page's own title. The summary is one or two sentences on what the page covers. The body opens with the line `Source: <url>, retrieved <today's date>`, then the page's content as clean markdown: keep headings, code blocks and tables, drop navigation, footers, cookie banners and repeated menus.
+4. A memo body holds at most 10,000 characters. For a longer page, split at a heading into several memos titled "Page title, part 2" and so on, and link each part to the next in its text as `[Page title, part 2](N:12)`.
+5. Set `node_type` to `doc` and `actor` to `agent:claude-code`.
+
+When you finish, tell me the bucket, how many pages you created and updated, how many you skipped and why, and one example query I could try with `/gigarecall`.

package/commands/gigaindex.md

@@ -0,0 +1,10 @@
+---
+description: Index a codebase into GigaRAG, one bucket per repository
+argument-hint: [path]
+---
+
+Index the codebase at "$ARGUMENTS" into GigaRAG. If that is empty, use the current directory.
+
+Hand the work to the `gigarag:gigarag-indexer` subagent, so the repository walk happens in its own context and not in this conversation. Run it in the foreground and wait for it to finish, because a background run ends with nothing indexed if this session closes first. Give it the path exactly as I gave it, or the current directory, and tell it to run a full index.
+
+When it finishes, tell me in five lines or fewer: the bucket it used, how many memos it created, updated and deleted, anything it could not index and why, and whether the index is now up to date. Do not paste the file list.

package/commands/gigarecall.md

@@ -0,0 +1,15 @@
+---
+description: Search GigaRAG and load what it knows into this conversation
+argument-hint: <what to recall>
+---
+
+Recall what GigaRAG knows about: $ARGUMENTS
+
+If that is empty, ask me what to recall and stop.
+
+1. Call `search_nodes` with my question in plain words, limit 8. It combines exact-term and meaning-based search, so a paraphrase works as well as an identifier.
+2. Read the two to four most relevant hits in full with `fetch_node`. Search returns only a snippet, so do not answer from snippets alone.
+3. If a memo links to another that looks necessary to answer, read that one too with `fetch_node`, or use `neighbors`. Stop after about six memos in total.
+4. Give me what you found: the facts that answer the question, each with the ref of the memo it came from, like N:12. Say which memos disagree, if any do, and which is newer. If a memo is marked superseded, say so and prefer what replaced it.
+
+If nothing relevant came back, say that plainly and suggest one different phrasing to try. Do not fill the gap from general knowledge, and do not save anything.

package/commands/gigasave.md

@@ -0,0 +1,24 @@
+---
+description: Save this session's decisions and discoveries to GigaRAG as memos
+argument-hint: [what to focus on]
+---
+
+Save what this session decided or learned into GigaRAG, so the next session, on any machine or in any client, can find it. If I gave a focus ("$ARGUMENTS"), save only that. Otherwise go through the whole conversation.
+
+Find the bucket first: run `gigarag repo --slug` and use that slug. If no bucket has it yet, create one with that slug.
+
+What is worth a memo:
+- A decision, with why it was made and what was rejected. "We chose X over Y because Z" is the best kind.
+- A discovery that took effort: why something behaves as it does, a constraint nobody wrote down, a bug's real cause.
+- A convention agreed for this codebase.
+- An open question somebody still has to answer.
+
+What is not: chatter, status updates, anything already obvious from the code or the git log, and anything secret. Never save keys, tokens, passwords or personal data, even if they appeared in the conversation.
+
+For each one:
+1. Call `search_nodes` with the topic first. If a memo already covers it, update that memo with `update_node`, keeping the links already in its text, instead of creating a second one.
+2. Otherwise `create_node` in a thread called `decisions` in that bucket (create the thread if it is missing). Use the type `decision` for decisions and `note` for everything else. Set `actor` to `agent:claude-code`.
+3. The title states the point ("Use cursor pagination for /events"), not the topic ("Pagination"). The summary is one or two sentences. The body has the context, the decision, why, and what was rejected.
+4. Where a memo relates to another, link it in the text as `[Title](N:12)`, using the ref from `find_nodes`. Never write a UUID as a link target.
+
+At the end, list what you saved as one line each: the ref, the title, and whether it was created or updated. If there was nothing worth saving, say so and save nothing.

package/commands/gigasync.md

@@ -0,0 +1,9 @@
+---
+description: Bring GigaRAG up to date with the files that changed since the last index
+---
+
+Run `gigarag scan --summary` in the current directory and read the counts.
+
+If nothing is new, changed or gone, say "GigaRAG is up to date with this repository." and stop. Do not start the indexer for nothing.
+
+Otherwise hand the work to the `gigarag:gigarag-indexer` subagent, in the foreground and waiting for it to finish, for the current directory, and tell it this is an incremental sync: only the files the scan reports. When it finishes, tell me in three lines or fewer what changed: memos created, updated and deleted.

package/hooks/hooks.json

@@ -0,0 +1,38 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/run.mjs\" hook SessionStart",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/run.mjs\" hook PostToolUse",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/run.mjs\" hook Stop",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "gigarag-claude-code",
+  "version": "0.1.0",
+  "description": "The GigaRAG plugin for Claude Code. Commands, an indexing agent, hooks and an MCP server that carry the gigarag CLI inside them.",
+  "license": "UNLICENSED",
+  "files": [
+    ".claude-plugin",
+    "commands",
+    "agents",
+    "hooks",
+    "scripts",
+    "bin",
+    "cli",
+    ".mcp.json",
+    "README.md"
+  ],
+  "bin": {
+    "gigarag": "bin/gigarag"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gigarag/gigarag-cli.git",
+    "directory": "plugins/claude-code"
+  },
+  "homepage": "https://gigarag.com"
+}

package/scripts/run.mjs

@@ -0,0 +1,64 @@
+// Finds the gigarag CLI and runs it, so every hook, command and MCP entry in this
+// plugin calls one thing. Lookup order:
+//   1. GIGARAG_CLI, a path to bin.js, for development
+//   2. ../cli/bin.js, the build vendored into this package at release time
+//   3. a gigarag on PATH, such as npm i -g gigarag or the standalone installer
+//   4. npx, which downloads the version this plugin was released with
+// The CLI is vendored because Claude Code does not run install scripts and npm never
+// publishes a lockfile, so a declared dependency would not be there on first run.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const args = process.argv.slice(2);
+const here = dirname(fileURLToPath(import.meta.url));
+const isHook = args[0] === 'hook';
+const windows = process.platform === 'win32';
+
+const local = [process.env.GIGARAG_CLI, join(here, '..', 'cli', 'bin.js')].find(p => p && existsSync(p));
+
+/** The version this plugin shipped with, so npx runs the CLI it was tested against and not whatever is newest. */
+const pinned = () => {
+  try {
+    const { version } = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+    return /^\d+\.\d+\.\d+(-[\w.]+)?$/.test(version) ? `gigarag@${version}` : 'gigarag';
+  } catch {
+    return 'gigarag';
+  }
+};
+
+/** True when the command exists. A probe, because a shell reports a missing command as an ordinary exit code. */
+const exists = (cmd, probe) => {
+  const r = spawnSync(cmd, probe, { stdio: 'ignore', shell: windows });
+  return !r.error && r.status === 0;
+};
+
+/**
+ * On Windows gigarag and npx are .cmd scripts, which Node will only start through cmd.exe. What a
+ * user typed after a slash command ends up in these arguments, so anything cmd.exe would read as
+ * syntax is refused rather than passed on.
+ */
+const unsafeForCmd = list => windows && list.some(a => /[&|<>^%"\r\n`]/.test(a));
+
+if (local) {
+  // In this process: no second Node start, which matters inside a 100ms hook budget.
+  await import(pathToFileURL(local).href);
+} else {
+  const attempts = [
+    ['gigarag', ['--version'], 'gigarag', args],
+    ['npx', ['--version'], 'npx', ['-y', pinned(), ...args]],
+  ];
+  const found = attempts.find(([probeCmd, probeArgs]) => exists(probeCmd, probeArgs));
+  if (found && unsafeForCmd(found[3])) {
+    if (!isHook) process.stderr.write('gigarag: an argument holds a character that cmd.exe would treat as syntax, so nothing was run.\n');
+    process.exitCode = isHook ? 0 : 1;
+  } else if (found) {
+    const r = spawnSync(found[2], found[3], { stdio: 'inherit', shell: windows });
+    // A hook must never break the session it runs in.
+    process.exitCode = isHook ? 0 : (r.status ?? 1);
+  } else {
+    if (!isHook) process.stderr.write('gigarag is not installed. Run: npm install -g gigarag\n');
+    process.exitCode = isHook ? 0 : 1;
+  }
+}