@misterhuydo/cairn-mcp 1.2.1 → 1.2.4

package/README.md

@@ -1,270 +1,309 @@
-# Cairn MCP
-
-> Persistent polyglot knowledge graph for Claude Code. Index once, query forever.
-
-Claude is stateless — every session starts at zero. On a multi-repo codebase with Java backends, TypeScript frontends, and Vue components, that means 50% of every session is archaeology: finding where things live before any real work can begin.
-
-**Cairn fixes this.** It indexes your project into a local SQLite knowledge graph (stored in `.cairn/`) and exposes 8 MCP tools that give Claude instant, persistent memory across sessions.
-
----
-
-## Install
-
-```bash
-npm install -g @misterhuydo/cairn-mcp
-```
-
-**Requirements:** Node.js >= 22.15.0
-
----
-
-## Setup
-
-Add to `~/.claude.json`:
-
-```json
-{
-  "mcpServers": {
-    "cairn": {
-      "command": "cairn-mcp"
-    }
-  }
-}
-```
-
-Restart Claude Code. Done.
-
----
-
-## How it works
-
-Cairn works like git — it looks for `.cairn/` in your current working directory. Run Claude Code from your project root and Cairn automatically stores the index at `.cairn/index.db` and bundles at `.cairn/bundles/`.
-
-No root paths needed. No global config. Just `cd` to your project and go.
-
----
-
-## Tools
-
-### `cairn_maintain` — Index your project
-Run once at the start of each session. The index persists in `.cairn/index.db`.
-
-```
-cairn_maintain()
-cairn_maintain({ languages: ["typescript", "vue"] })  // limit to specific languages
-```
-
-```json
-{
-  "repos_indexed": 1,
-  "files_by_language": { "java": 412, "typescript": 287, "vue": 94 },
-  "symbols_total": 6841,
-  "security_findings": 47,
-  "duration_ms": 4200
-}
-```
-
----
-
-### `cairn_search` — Find anything across all languages
-```
-cairn_search({ query: "user authentication", language: "typescript" })
-```
-
-```json
-[
-  { "lang": "typescript", "kind": "function",  "fqn": "src/composables/useAuth.ts::useAuth" },
-  { "lang": "vue",        "kind": "component", "fqn": "src/components/LoginForm.vue::LoginForm" },
-  { "lang": "java",       "kind": "class",     "fqn": "com.example.auth.UserAuthenticator" }
-]
-```
-
----
-
-### `cairn_bundle` — Minified source snapshot for Claude to read
-Strips comments and empty lines, writes a compressed `### File:` bundle. Use after `cairn_search` to give Claude readable source without blowing the context window.
-
-```
-cairn_bundle({ filter_paths: ["src/components/checkout"], bundle_name: "checkout" })
-```
-
-```json
-{
-  "bundle_path": "/your/project/.cairn/bundles/checkout.txt",
-  "original_kb": 284,
-  "compressed_kb": 91,
-  "reduction_pct": 68
-}
-```
-
----
-
-### `cairn_describe` — Summarize a module
-```
-cairn_describe({ path: "src/components/checkout" })
-```
-
-```json
-{
-  "languages": ["vue", "typescript"],
-  "symbols": {
-    "component": ["CheckoutForm", "OrderSummary", "PaymentStep"],
-    "function":  ["useCheckout", "usePayment"]
-  },
-  "imports_from":  ["src/store/cart.ts", "src/api/orders.ts"],
-  "imported_by":   ["src/views/CartView.vue"],
-  "external_deps": ["stripe", "@stripe/stripe-js"]
-}
-```
-
----
-
-### `cairn_code_graph` — Dependency health
-```
-cairn_code_graph({ mode: "instability" })
-```
-
-```json
-{
-  "modules": [
-    { "name": "src/views",       "instability": 1.0, "status": "safe_to_refactor" },
-    { "name": "src/composables", "instability": 0.4, "status": "review_before_change" },
-    { "name": "src/utils",       "instability": 0.1, "status": "load_bearing" }
-  ]
-}
-```
-
-Modes: `instability` · `health` · `cycles`
-
----
-
-### `cairn_security` — Vulnerability scan
-```
-cairn_security({ severity: "HIGH" })
-```
-
-```json
-{
-  "total_findings": 12,
-  "by_language": { "typescript": 7, "java": 5 },
-  "findings": [
-    { "severity": "HIGH", "cwe": "CWE-79",  "file": "src/components/UserProfile.vue", "line": 84, "rule": "XSS via innerHTML" },
-    { "severity": "HIGH", "cwe": "CWE-611", "file": "backend/src/.../XmlParser.java",  "line": 47, "rule": "XXE" }
-  ]
-}
-```
-
-Covers: XSS · XXE · SQL injection · command injection · weak crypto · hardcoded secrets · open redirect · unsafe deserialization
-
----
-
-### `cairn_checkpoint` — Save session state
-Tell Cairn what you were working on so the next session can pick up where you left off.
-
-```
-cairn_checkpoint({
-  message: "Added multi-currency to CheckoutForm, still need PaymentStep",
-  active_files: ["src/components/checkout/CheckoutForm.vue"],
-  notes: ["CurrencyService expects ISO 4217 codes, not symbols"]
-})
-```
-
-```json
-{
-  "saved": true,
-  "checkpoint_at": "2026-02-25T14:30:00Z",
-  "active_files_tracked": 1,
-  "notes_saved": 1
-}
-```
-
----
-
-### `cairn_resume` — Restore session + smart re-index
-Call instead of `cairn_maintain` when resuming work. Detects which files changed and only re-indexes those.
-
-```
-cairn_resume()
-```
-
-```json
-{
-  "last_checkpoint": "2026-02-25T14:30:00Z",
-  "message": "Added multi-currency to CheckoutForm, still need PaymentStep",
-  "index_status": "incremental",
-  "files_reindexed": 2,
-  "files_unchanged": 845,
-  "changed_since_checkpoint": [
-    { "file": "src/components/checkout/PaymentStep.vue", "change": "modified" }
-  ],
-  "active_files": ["src/components/checkout/CheckoutForm.vue"],
-  "notes": ["CurrencyService expects ISO 4217 codes, not symbols"],
-  "resume_summary": "Last session you were adding multi-currency support..."
-}
-```
-
----
-
-## Supported Languages
-
-| Language | What Cairn extracts |
-|---|---|
-| Java | packages, classes, interfaces, enums, records, methods |
-| TypeScript / JavaScript | classes, interfaces, functions, types, enums |
-| Vue | components, composables, script block symbols |
-| Python | classes, functions, decorators |
-| SQL | tables, views, stored procedures |
-| XML / HTML | bean ids, component names |
-| Config (YAML, properties, .env) | top-level keys |
-| Markdown | headings |
-| Build files (pom.xml, package.json, build.gradle) | dependencies |
-
----
-
-## Typical session
-
-**Fresh start:**
-```
-1. cairn_maintain     → index project (persists between sessions)
-2. cairn_search       → find the symbols you need
-3. cairn_bundle       → get a readable snapshot of relevant files
-4. cairn_describe     → understand a module before modifying it
-5. cairn_security     → check for issues before a PR
-6. cairn_checkpoint   → save what you were working on
-```
-
-**Resuming work:**
-```
-1. cairn_resume       → restore session + incremental re-index
-2. cairn_search       → continue where you left off
-```
-
-## Complete session lifecycle
-
-```
-─── START OF SESSION ──────────────────────────────────────────
-You:    "Hey Claude, please resume and continue"
-Claude: cairn_resume
-        → "Last session: adding multi-currency to checkout.
-           PaymentStep.vue was modified since checkpoint (2 files changed, re-indexed).
-           Notes: CurrencyService expects ISO 4217 codes. PaymentStep EUR bug not fixed yet.
-           Ready to continue."
-
-─── DURING SESSION ────────────────────────────────────────────
-Claude uses: cairn_search, cairn_bundle, cairn_code_graph, cairn_security
-             as needed — all reading from .cairn/index.db in cwd
-
-─── END OF SESSION ────────────────────────────────────────────
-You:    "Ok let's stop here for today"
-Claude: cairn_checkpoint
-          message="Fixed EUR formatting in PaymentStep, multi-currency complete"
-          active_files=["src/components/checkout/PaymentStep.vue"]
-          notes=["Still need to add JPY — no decimal places", "QA needs to test AED"]
-        → "Session saved. Resume anytime with cairn_resume."
-```
-
----
-
-## License
-
-MIT
+# Cairn MCP
+
+> Persistent polyglot knowledge graph for Claude Code. Index once, query forever.
+
+Claude is stateless — every session starts at zero. On a multi-repo codebase with Java backends, TypeScript frontends, and Vue components, that means 50% of every session is archaeology: finding where things live before any real work can begin.
+
+**Cairn fixes this.** It indexes your project into a local SQLite knowledge graph (stored in `.cairn/`) and exposes 8 MCP tools that give Claude instant, persistent memory across sessions.
+
+---
+
+# Setup
+- See how-to-use.md 
+
+```bash
+npm install -g @misterhuydo/cairn-mcp
+```
+
+**Requirements:** Node.js >= 22.15.0
+
+---
+
+## Setup
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "cairn": {
+      "command": "cairn-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Code. Done.
+
+---
+
+## Passive hooks (recommended)
+
+Install once and Cairn works automatically — no need to call `cairn_bundle` or `cairn_checkpoint` manually.
+
+**Global (all projects):**
+
+```bash
+cairn install-hooks --global
+```
+
+**Project-only:**
+
+```bash
+cairn install-hooks
+```
+
+| Hook | Trigger | Effect |
+|---|---|---|
+| `PreToolUse[Read]` | Every file read | Source files compressed ~68% before Claude sees them |
+| `Stop` | Every response | Session auto-saved to `.cairn/session.json` |
+| `UserPromptSubmit` | First message of session | Claude reminded of prior session, prompted to call `cairn_resume` |
+
+## How it works
+
+Cairn works like git — it looks for `.cairn/` in your current working directory. Run Claude Code from your project root and Cairn automatically stores the index at `.cairn/index.db` and bundles at `.cairn/bundles/`.
+
+No root paths needed. No global config. Just `cd` to your project and go.
+
+---
+
+## Tools
+
+### `cairn_maintain` — Index your project
+Run once at the start of each session. The index persists in `.cairn/index.db`.
+
+```
+cairn_maintain()
+cairn_maintain({ languages: ["typescript", "vue"] })  // limit to specific languages
+```
+
+```json
+{
+  "repos_indexed": 1,
+  "files_by_language": { "java": 412, "typescript": 287, "vue": 94 },
+  "symbols_total": 6841,
+  "security_findings": 47,
+  "duration_ms": 4200
+}
+```
+
+---
+
+### `cairn_search` — Find anything across all languages
+```
+cairn_search({ query: "user authentication", language: "typescript" })
+```
+
+```json
+[
+  { "lang": "typescript", "kind": "function",  "fqn": "src/composables/useAuth.ts::useAuth" },
+  { "lang": "vue",        "kind": "component", "fqn": "src/components/LoginForm.vue::LoginForm" },
+  { "lang": "java",       "kind": "class",     "fqn": "com.example.auth.UserAuthenticator" }
+]
+```
+
+---
+
+### `cairn_bundle` — Minified source snapshot for Claude to read
+Strips comments and empty lines, writes a compressed `### File:` bundle. Use after `cairn_search` to give Claude readable source without blowing the context window.
+
+```
+cairn_bundle({ filter_paths: ["src/components/checkout"], bundle_name: "checkout" })
+```
+
+```json
+{
+  "bundle_path": "/your/project/.cairn/bundles/checkout.txt",
+  "original_kb": 284,
+  "compressed_kb": 91,
+  "reduction_pct": 68
+}
+```
+
+---
+
+### `cairn_describe` — Summarize a module
+```
+cairn_describe({ path: "src/components/checkout" })
+```
+
+```json
+{
+  "languages": ["vue", "typescript"],
+  "symbols": {
+    "component": ["CheckoutForm", "OrderSummary", "PaymentStep"],
+    "function":  ["useCheckout", "usePayment"]
+  },
+  "imports_from":  ["src/store/cart.ts", "src/api/orders.ts"],
+  "imported_by":   ["src/views/CartView.vue"],
+  "external_deps": ["stripe", "@stripe/stripe-js"]
+}
+```
+
+---
+
+### `cairn_code_graph` — Dependency health
+```
+cairn_code_graph({ mode: "instability" })
+```
+
+```json
+{
+  "modules": [
+    { "name": "src/views",       "instability": 1.0, "status": "safe_to_refactor" },
+    { "name": "src/composables", "instability": 0.4, "status": "review_before_change" },
+    { "name": "src/utils",       "instability": 0.1, "status": "load_bearing" }
+  ]
+}
+```
+
+Modes: `instability` · `health` · `cycles`
+
+---
+
+### `cairn_security` — Vulnerability scan
+```
+cairn_security({ severity: "HIGH" })
+```
+
+```json
+{
+  "total_findings": 12,
+  "by_language": { "typescript": 7, "java": 5 },
+  "findings": [
+    { "severity": "HIGH", "cwe": "CWE-79",  "file": "src/components/UserProfile.vue", "line": 84, "rule": "XSS via innerHTML" },
+    { "severity": "HIGH", "cwe": "CWE-611", "file": "backend/src/.../XmlParser.java",  "line": 47, "rule": "XXE" }
+  ]
+}
+```
+
+Covers: XSS · XXE · SQL injection · command injection · weak crypto · hardcoded secrets · open redirect · unsafe deserialization
+
+---
+
+### `cairn_minify` — Minify a single file
+Minify one source file on demand. Returns compressed content with a `[cairn: N → M lines]` header. Useful when passive hooks are not installed.
+
+```
+cairn_minify({ file_path: "/abs/path/to/Service.java" })
+```
+
+---
+
+### `cairn_checkpoint` — Save session state
+Tell Cairn what you were working on so the next session can pick up where you left off.
+
+```
+cairn_checkpoint({
+  message: "Added multi-currency to CheckoutForm, still need PaymentStep",
+  active_files: ["src/components/checkout/CheckoutForm.vue"],
+  notes: ["CurrencyService expects ISO 4217 codes, not symbols"]
+})
+```
+
+```json
+{
+  "saved": true,
+  "checkpoint_at": "2026-02-25T14:30:00Z",
+  "active_files_tracked": 1,
+  "notes_saved": 1
+}
+```
+
+---
+
+### `cairn_resume` — Restore session + smart re-index
+Call instead of `cairn_maintain` when resuming work. Detects which files changed and only re-indexes those.
+
+```
+cairn_resume()
+```
+
+```json
+{
+  "last_checkpoint": "2026-02-25T14:30:00Z",
+  "message": "Added multi-currency to CheckoutForm, still need PaymentStep",
+  "index_status": "incremental",
+  "files_reindexed": 2,
+  "files_unchanged": 845,
+  "changed_since_checkpoint": [
+    { "file": "src/components/checkout/PaymentStep.vue", "change": "modified" }
+  ],
+  "active_files": ["src/components/checkout/CheckoutForm.vue"],
+  "notes": ["CurrencyService expects ISO 4217 codes, not symbols"],
+  "resume_summary": "Last session you were adding multi-currency support..."
+}
+```
+
+---
+
+## Supported Languages
+
+| Language | What Cairn extracts |
+|---|---|
+| Java | packages, classes, interfaces, enums, records, methods |
+| TypeScript / JavaScript | classes, interfaces, functions, types, enums |
+| Vue | components, composables, script block symbols |
+| Python | classes, functions, decorators |
+| SQL | tables, views, stored procedures |
+| XML / HTML | bean ids, component names |
+| Config (YAML, properties, .env) | top-level keys |
+| Markdown | headings |
+| Build files (pom.xml, package.json, build.gradle) | dependencies |
+
+---
+
+## Typical session
+
+**With passive hooks (recommended):**
+```
+1. cairn_maintain     → index project
+2. cairn_search       → find the symbols you need
+3. cairn_describe     → understand a module before modifying it
+4. cairn_security     → check for issues before a PR
+   (reads auto-compressed, session auto-saved — nothing else needed)
+```
+
+**Without hooks:**
+```
+1. cairn_maintain     → index project (persists between sessions)
+2. cairn_search       → find the symbols you need
+3. cairn_bundle       → get a readable snapshot of relevant files
+4. cairn_describe     → understand a module before modifying it
+5. cairn_security     → check for issues before a PR
+6. cairn_checkpoint   → save what you were working on
+```
+
+**Resuming work:**
+```
+1. cairn_resume       → restore session + incremental re-index
+2. cairn_search       → continue where you left off
+```
+
+## Complete session lifecycle
+
+```
+─── START OF SESSION ──────────────────────────────────────────
+You:    "Hey Claude, please resume and continue"
+Claude: cairn_resume
+        → "Last session: adding multi-currency to checkout.
+           PaymentStep.vue was modified since checkpoint (2 files changed, re-indexed).
+           Notes: CurrencyService expects ISO 4217 codes. PaymentStep EUR bug not fixed yet.
+           Ready to continue."
+
+─── DURING SESSION ────────────────────────────────────────────
+Claude uses: cairn_search, cairn_code_graph, cairn_security
+             as needed — all reading from .cairn/index.db in cwd
+             (file reads auto-compressed by PreToolUse hook)
+
+─── END OF SESSION ────────────────────────────────────────────
+You:    "Ok let's stop here for today"
+        (Stop hook fires → .cairn/session.json auto-saved)
+        → Next session: cairn_resume picks up automatically
+```
+
+---
+
+## License
+
+MIT

package/bin/cairn-cli.js

@@ -1,111 +1,177 @@
-#!/usr/bin/env node
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-import { LANGUAGE_MAP } from '../src/indexer/fileWalker.js';
-import { minifyContent } from '../src/bundler/minifier.js';
-import { minifyVue } from '../src/bundler/vueMinifier.js';
-import { checkpoint } from '../src/tools/checkpoint.js';
-
-const MINIFY_LANGS = new Set(['java', 'typescript', 'javascript', 'vue', 'python', 'sql']);
-
-const subcommand = process.argv[2];
-
-if (subcommand === 'minify') {
-  let stdinData = '';
-  process.stdin.setEncoding('utf8');
-  process.stdin.on('data', chunk => { stdinData += chunk; });
-  process.stdin.on('end', () => {
-    let filePath;
-    try {
-      const input = JSON.parse(stdinData);
-      filePath = input?.tool_input?.file_path;
-    } catch {
-      process.exit(0);
-    }
-
-    if (!filePath) process.exit(0);
-
-    const ext = path.extname(filePath).toLowerCase();
-    const lang = LANGUAGE_MAP[ext];
-
-    if (!lang || !MINIFY_LANGS.has(lang)) process.exit(0);
-
-    let content;
-    try {
-      content = fs.readFileSync(filePath, 'utf8');
-    } catch {
-      process.exit(0);
-    }
-
-    const originalLines = content.split('\n').length;
-
-    const minified = lang === 'vue'
-      ? minifyVue(content)
-      : minifyContent(content, lang);
-
-    const minifiedLines = minified.split('\n').length;
-    const pct = originalLines > 0 ? Math.round((1 - minifiedLines / originalLines) * 100) : 0;
-
-    process.stdout.write(`[cairn: ${originalLines} → ${minifiedLines} lines (-${pct}%)]\n${minified}\n`);
-    process.exit(2);
-  });
-
-} else if (subcommand === 'checkpoint' && process.argv[3] === '--auto') {
-  const message = `Auto-checkpoint at ${new Date().toISOString()}`;
-  checkpoint(null, { message, active_files: [], notes: [] });
-  process.exit(0);
-
-} else if (subcommand === 'install-hooks') {
-  const isGlobal = process.argv.includes('--global');
-  const settingsDir = isGlobal
-    ? path.join(os.homedir(), '.claude')
-    : path.join(process.cwd(), '.claude');
-  const settingsPath = path.join(settingsDir, 'settings.json');
-
-  let settings = {};
-  if (fs.existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-    } catch {
-      settings = {};
-    }
-  }
-
-  settings.hooks = settings.hooks || {};
-
-  // Add PreToolUse hook for Read
-  const preHooks = settings.hooks.PreToolUse || [];
-  const hasMinify = preHooks.some(h =>
-    h.matcher === 'Read' && h.hooks?.some(hh => hh.command === 'cairn minify')
-  );
-  if (!hasMinify) {
-    preHooks.push({ matcher: 'Read', hooks: [{ type: 'command', command: 'cairn minify' }] });
-    settings.hooks.PreToolUse = preHooks;
-  }
-
-  // Add Stop hook for auto-checkpoint
-  const stopHooks = settings.hooks.Stop || [];
-  const hasCheckpoint = stopHooks.some(h =>
-    h.hooks?.some(hh => hh.command === 'cairn checkpoint --auto')
-  );
-  if (!hasCheckpoint) {
-    stopHooks.push({ hooks: [{ type: 'command', command: 'cairn checkpoint --auto' }] });
-    settings.hooks.Stop = stopHooks;
-  }
-
-  fs.mkdirSync(settingsDir, { recursive: true });
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
-
-  const scope = isGlobal ? 'global (~/.claude/settings.json)' : 'project (.claude/settings.json)';
-  console.log(`Cairn hooks installed in ${scope}`);
-  console.log('');
-  console.log('Active hooks:');
-  console.log('  PreToolUse[Read] → cairn minify            (compress source files)');
-  console.log('  Stop             → cairn checkpoint --auto  (auto-save session)');
-  process.exit(0);
-
-} else {
-  console.error('Usage: cairn <minify|checkpoint --auto|install-hooks>');
-  process.exit(1);
-}
+#!/usr/bin/env node
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { LANGUAGE_MAP } from '../src/indexer/fileWalker.js';
+import { minifyContent } from '../src/bundler/minifier.js';
+import { minifyVue } from '../src/bundler/vueMinifier.js';
+import { checkpoint } from '../src/tools/checkpoint.js';
+
+const MINIFY_LANGS = new Set(['java', 'typescript', 'javascript', 'vue', 'python', 'sql']);
+
+const CAIRN_DIR = path.join(os.homedir(), '.cairn');
+const MODE_FILE = path.join(CAIRN_DIR, 'mode');
+
+function getCurrentMode() {
+  try {
+    return fs.readFileSync(MODE_FILE, 'utf8').trim();
+  } catch {
+    return 'read';
+  }
+}
+
+function resetMode() {
+  try {
+    fs.writeFileSync(MODE_FILE, 'read', 'utf8');
+  } catch { }
+}
+
+process.on('uncaughtException', (e) => {
+  process.stderr.write(`cairn: ${e.message}\n`);
+  process.exit(0);
+});
+
+const subcommand = process.argv[2];
+
+if (subcommand === 'minify') {
+  let stdinData = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { stdinData += chunk; });
+  process.stdin.on('end', () => {
+    let filePath;
+    try {
+      const input = JSON.parse(stdinData);
+      filePath = input?.tool_input?.file_path;
+    } catch {
+      process.exit(0);
+    }
+    if (!filePath) process.exit(0);
+
+    // Check mode: if 'edit', let Read proceed with full content (exit 0), then reset to 'read'
+    const mode = getCurrentMode();
+    if (mode === 'edit') {
+      resetMode();
+      process.exit(0);
+    }
+
+    const ext = path.extname(filePath).toLowerCase();
+    const lang = LANGUAGE_MAP[ext];
+    if (!lang || !MINIFY_LANGS.has(lang)) process.exit(0);
+    let content;
+    try {
+      content = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      process.exit(0);
+    }
+    const originalLines = content.split('\n').length;
+    const minified = lang === 'vue'
+      ? minifyVue(content)
+      : minifyContent(content, lang);
+    const minifiedLines = minified.split('\n').length;
+    const pct = originalLines > 0 ? Math.round((1 - minifiedLines / originalLines) * 100) : 0;
+    process.stderr.write(`[cairn: ${originalLines} → ${minifiedLines} lines (-${pct}%)]\n${minified}\n`);
+    process.exit(2);
+  });
+} else if (subcommand === 'set-mode') {
+  const mode = process.argv[3];
+  if (mode !== 'edit' && mode !== 'read') {
+    console.error('Usage: cairn set-mode <edit|read>');
+    process.exit(1);
+  }
+  try {
+    fs.mkdirSync(CAIRN_DIR, { recursive: true });
+    fs.writeFileSync(MODE_FILE, mode, 'utf8');
+    console.log(`cairn: mode set to '${mode}'`);
+    if (mode === 'edit') {
+      console.log('Next Read call will return full content (auto-resets to read after).');
+    }
+  } catch (e) {
+    console.error(`cairn: failed to write mode file: ${e.message}`);
+    process.exit(1);
+  }
+  process.exit(0);
+} else if (subcommand === 'checkpoint' && process.argv[3] === '--auto') {
+  const message = `Auto-checkpoint at ${new Date().toISOString()}`;
+  let existingNotes = [];
+  try {
+    const cairnDir = path.join(process.cwd(), '.cairn');
+    const sessionPath = path.join(cairnDir, 'session.json');
+    if (fs.existsSync(sessionPath)) {
+      const existing = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+      existingNotes = existing.notes || [];
+    }
+  } catch {  }
+  checkpoint(null, { message, active_files: [], notes: existingNotes });
+  process.exit(0);
+} else if (subcommand === 'resume-hint') {
+  const cairnDir = path.join(process.cwd(), '.cairn');
+  const sessionPath = path.join(cairnDir, 'session.json');
+  if (!fs.existsSync(sessionPath)) process.exit(0);
+  const lockPath = path.join(cairnDir, '.hint-lock');
+  const LOCK_TTL_MS = 30 * 60 * 1000;
+  if (fs.existsSync(lockPath)) {
+    const age = Date.now() - fs.statSync(lockPath).mtimeMs;
+    if (age < LOCK_TTL_MS) process.exit(0);
+  }
+  const session = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
+  const when = new Date(session.checkpoint_at).toLocaleString();
+  process.stdout.write(`[cairn] Prior session: "${session.message}" (${when}). Call cairn_resume to restore prior context.\n`);
+  fs.writeFileSync(lockPath, new Date().toISOString(), 'utf8');
+  process.exit(0);
+} else if (subcommand === 'install-hooks') {
+  const isGlobal = process.argv.includes('--global');
+  const settingsDir = isGlobal
+    ? path.join(os.homedir(), '.claude')
+    : path.join(process.cwd(), '.claude');
+  const settingsPath = path.join(settingsDir, 'settings.json');
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch {
+      settings = {};
+    }
+  }
+  settings.hooks = settings.hooks || {};
+  const preHooks = settings.hooks.PreToolUse || [];
+  const hasMinify = preHooks.some(h =>
+    h.matcher === 'Read' && h.hooks?.some(hh => hh.command === 'cairn minify')
+  );
+  if (!hasMinify) {
+    preHooks.push({ matcher: 'Read', hooks: [{ type: 'command', command: 'cairn minify' }] });
+    settings.hooks.PreToolUse = preHooks;
+  }
+  const stopHooks = settings.hooks.Stop || [];
+  const hasCheckpoint = stopHooks.some(h =>
+    h.hooks?.some(hh => hh.command === 'cairn checkpoint --auto')
+  );
+  if (!hasCheckpoint) {
+    stopHooks.push({ hooks: [{ type: 'command', command: 'cairn checkpoint --auto' }] });
+    settings.hooks.Stop = stopHooks;
+  }
+  const submitHooks = settings.hooks.UserPromptSubmit || [];
+  const hasResumeHint = submitHooks.some(h =>
+    h.hooks?.some(hh => hh.command === 'cairn resume-hint')
+  );
+  if (!hasResumeHint) {
+    submitHooks.push({ hooks: [{ type: 'command', command: 'cairn resume-hint' }] });
+    settings.hooks.UserPromptSubmit = submitHooks;
+  }
+  fs.mkdirSync(settingsDir, { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
+  const scope = isGlobal ? 'global (~/.claude/settings.json)' : 'project (.claude/settings.json)';
+  console.log(`Cairn hooks installed in ${scope}`);
+  console.log('');
+  console.log('Active hooks:');
+  console.log('  PreToolUse[Read]    → cairn minify            (compress source files)');
+  console.log('  Stop                → cairn checkpoint --auto  (auto-save session)');
+  console.log('  UserPromptSubmit    → cairn resume-hint        (remind Claude of prior session)');
+  console.log('');
+  console.log('Mode commands:');
+  console.log('  cairn set-mode edit   (next Read returns full content, for Edit tool use)');
+  console.log('  cairn set-mode read   (default: minified content)');
+  process.exit(0);
+} else {
+  console.error('Usage: cairn <minify|set-mode <edit|read>|checkpoint --auto|resume-hint|install-hooks [--global]>');
+  process.exit(1);
+}

package/bin/cairn.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';

package/how-to-use.md

@@ -1,5 +1,50 @@
+# Claude Global Instructions
+
+## MCP Tools — Cairn Session Lifecycle
+
+Always use cairn MCP tools to manage project context across sessions.
+
+### Start of Session
+When starting work on a project, always run:
+1. `cairn_resume` — restores last session context and incrementally re-indexes changed files
+
+If it's a **fresh project** with no prior session:
+1. `cairn_maintain` — index the project (persists between sessions)
+
+### During Session
+Use these tools as needed throughout the session:
+- `cairn_search` — find symbols, functions, or files before reading or modifying code
+- `cairn_bundle` — get a readable snapshot of relevant files before making changes
+- `cairn_describe` — understand a module before modifying it
+- `cairn_security` — check for security issues (always run before a PR)
+
+**Prefer cairn tools over manual file browsing or grep when available.**
+
+### End of Session
+When the user signals they are done (e.g. "let's stop", "that's enough for today", "wrap up"), always run:
+- `cairn_checkpoint` — save session state with:
+  - `message`: summary of what was accomplished
+  - `active_files`: files that were modified or are in progress
+  - `notes`: important context, known bugs, or next steps
+
+---
+
+## Example Session
+
+**Resuming:**
+> User: "Hey Claude, please resume and continue"
+> Claude runs `cairn_resume` → reads context → continues work
+
+**Ending:**
+> User: "Ok let's stop here for today"
+> Claude runs `cairn_checkpoint` with a meaningful summary and notes → confirms session saved
+
+---
+
 # Cairn — Quick Start
 
+> **Requirements:** Node.js >= 22.15.0
+
 ## 1. Install globally
 
 ```bash
@@ -32,12 +77,21 @@ What this sets up:
 |---|---|
 | `PreToolUse[Read]` | Every source file read is silently compressed before Claude sees it (~68% fewer tokens for `.java/.ts/.js/.vue/.py/.sql`) |
 | `Stop` | Session auto-saved to `.cairn/session.json` every time Claude finishes responding |
+| `UserPromptSubmit` | On the first message of a new session, Claude is reminded of the prior session and prompted to call `cairn_resume` |
 
 After this you never need to call `cairn_bundle` or `cairn_checkpoint` — Claude reads files normally and compression + checkpointing happen transparently in the background.
 
 ## 3. Register the MCP server with Claude Code
 
-Add to `~/.claude.json` (create it if it doesn't exist):
+Add to your `~/.claude.json` and restart Claude Code. You should see 8 cairn tools available.
+
+**File location by platform:**
+
+| Platform | Path |
+|---|---|
+| Windows | `C:\\Users\\<you>\\.claude.json` |
+| macOS | `~/.claude.json` |
+| Linux | `~/.claude.json` |
 
 ```json
 {
@@ -51,12 +105,54 @@ Add to `~/.claude.json` (create it if it doesn't exist):
 
 > If you already have other MCP servers, just add `"cairn": { ... }` inside the existing `"mcpServers"` block.
 
-Restart Claude Code. You should see 8 cairn tools available.
+## 4. (Optional) Configure Claude via CLAUDE.md
+
+If you prefer Claude to manage session lifecycle explicitly rather than via hooks, create a global `CLAUDE.md` file. This is an alternative to passive hooks — you don't need both.
+
+**File location by platform:**
+
+| Platform | Path |
+|---|---|
+| Windows | `C:\\Users\\<you>\\CLAUDE.md` |
+| macOS | `~/CLAUDE.md` |
+| Linux | `~/CLAUDE.md` |
+
+Copy and save the following content into that file:
+
+````markdown
+## MCP Tools — Cairn Session Lifecycle
+
+Always use cairn MCP tools to manage project context across sessions.
+
+### Start of Session
+When starting work on a project, always run:
+1. `cairn_resume` — restores last session context and incrementally re-indexes changed files
 
-## 4. Index your project
+If it's a fresh project with no prior session:
+1. `cairn_maintain` — index the project (persists between sessions)
+
+### During Session
+Use these tools as needed throughout the session:
+- `cairn_search` — find symbols, functions, or files before reading or modifying code
+- `cairn_bundle` — get a readable snapshot of relevant files before making changes
+- `cairn_describe` — understand a module before modifying it
+- `cairn_security` — check for security issues (always run before a PR)
+
+Prefer cairn tools over manual file browsing or grep when available.
+
+### End of Session
+When the user signals they are done (e.g. "let's stop", "that's enough for today", "wrap up"), always run:
+- `cairn_checkpoint` — save session state with:
+  - `message`: summary of what was accomplished
+  - `active_files`: files that were modified or are in progress
+  - `notes`: important context, known bugs, or next steps
+````
+
+## 5. Index your project
 
 Run Claude Code from your project root, then:
 
+
 ```
 cairn_maintain
 ```
@@ -65,7 +161,7 @@ No paths needed — Cairn works like git and finds your project from the current
 
 Run this once at the start of each session (or use `cairn_resume` to pick up where you left off).
 
-## 5. Tools at a glance
+## 6. Tools at a glance
 
 | Tool | What to use it for |
 |---|---|
@@ -80,7 +176,7 @@ Run this once at the start of each session (or use `cairn_resume` to pick up whe
 
 > `cairn_bundle` and `cairn_checkpoint` are called automatically when passive hooks are installed. They remain available for explicit use when needed.
 
-## 6. Typical session
+## 7. Typical session
 
 **With passive hooks (recommended):**
 ```
@@ -107,7 +203,7 @@ Run this once at the start of each session (or use `cairn_resume` to pick up whe
 2. cairn_search       → continue where you left off
 ```
 
-## 7. Complete session lifecycle
+## 8. Complete session lifecycle
 
 ```
 ─── START OF SESSION ──────────────────────────────────────────
@@ -128,7 +224,3 @@ You:    "Ok let's stop here for today"
         (Stop hook fires → .cairn/session.json auto-saved)
         → Next session: cairn_resume picks up automatically
 ```
-
----
-
-**Requirements:** Node.js >= 22.15.0

package/index.js

@@ -11,6 +11,7 @@ import { security }     from './src/tools/security.js';
 import { bundle }       from './src/tools/bundle.js';
 import { checkpoint }   from './src/tools/checkpoint.js';
 import { resume }       from './src/tools/resume.js';
+import { minify }       from './src/tools/minify.js';
 
 const db = openDB();
 
@@ -143,6 +144,17 @@ Typical workflow: cairn_search → find files → cairn_bundle those paths → C
         properties: {},
       },
     },
+    {
+      name: 'cairn_minify',
+      description: 'Minify a single source file and return compressed content. Strips comments and empty lines. Useful when passive hooks are not installed. Supports java, typescript, javascript, vue, python, sql.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file_path: { type: 'string', description: 'Absolute path to the file to minify' },
+        },
+        required: ['file_path'],
+      },
+    },
   ],
 }));
 
@@ -157,6 +169,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case 'cairn_bundle':      return await bundle(db, args);
     case 'cairn_checkpoint':  return checkpoint(db, args);
     case 'cairn_resume':      return await resume(db);
+    case 'cairn_minify':      return minify(db, args);
     default: throw new Error(`Unknown tool: ${name}`);
   }
 });

package/package.json

@@ -1,44 +1,44 @@
-{
-  "name": "@misterhuydo/cairn-mcp",
-  "version": "1.2.1",
-  "description": "MCP server that gives Claude Code persistent memory across sessions. Index your codebase once, search symbols, bundle source, scan for vulnerabilities, and checkpoint/resume work — across Java, TypeScript, Vue, Python, SQL and more.",
-  "type": "module",
-  "main": "index.js",
-  "bin": {
-    "cairn-mcp": "bin/cairn-mcp.js",
-    "cairn": "bin/cairn.js"
-  },
-  "scripts": {
-    "start": "node --experimental-sqlite index.js"
-  },
-  "engines": {
-    "node": ">=22.15.0"
-  },
-  "keywords": [
-    "mcp",
-    "claude",
-    "claude-code",
-    "knowledge-graph",
-    "codebase-search",
-    "polyglot",
-    "java",
-    "typescript",
-    "vue",
-    "python",
-    "sqlite",
-    "developer-tools"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/misterhuydo/Cairn.git"
-  },
-  "homepage": "https://github.com/misterhuydo/Cairn#readme",
-  "bugs": {
-    "url": "https://github.com/misterhuydo/Cairn/issues"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "fast-glob": "^3.3.0"
-  }
-}
+{
+  "name": "@misterhuydo/cairn-mcp",
+  "version": "1.2.4",
+  "description": "MCP server that gives Claude Code persistent memory across sessions. Index your codebase once, search symbols, bundle source, scan for vulnerabilities, and checkpoint/resume work — across Java, TypeScript, Vue, Python, SQL and more.",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "cairn-mcp": "bin/cairn-mcp.js",
+    "cairn": "bin/cairn.js"
+  },
+  "scripts": {
+    "start": "node --experimental-sqlite index.js"
+  },
+  "engines": {
+    "node": ">=22.15.0"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "claude-code",
+    "knowledge-graph",
+    "codebase-search",
+    "polyglot",
+    "java",
+    "typescript",
+    "vue",
+    "python",
+    "sqlite",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/misterhuydo/Cairn.git"
+  },
+  "homepage": "https://github.com/misterhuydo/Cairn#readme",
+  "bugs": {
+    "url": "https://github.com/misterhuydo/Cairn/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "fast-glob": "^3.3.0"
+  }
+}

package/src/tools/minify.js

@@ -0,0 +1,40 @@
+import fs from 'fs';
+import path from 'path';
+import { LANGUAGE_MAP } from '../indexer/fileWalker.js';
+import { minifyContent } from '../bundler/minifier.js';
+import { minifyVue } from '../bundler/vueMinifier.js';
+
+const MINIFY_LANGS = new Set(['java', 'typescript', 'javascript', 'vue', 'python', 'sql']);
+
+export function minify(_db, { file_path }) {
+  if (!file_path) throw new Error('file_path is required');
+
+  const ext = path.extname(file_path).toLowerCase();
+  const lang = LANGUAGE_MAP[ext];
+
+  if (!lang || !MINIFY_LANGS.has(lang)) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({ skipped: true, reason: `language '${lang ?? ext}' is not minified` }),
+      }],
+    };
+  }
+
+  const content = fs.readFileSync(file_path, 'utf8');
+  const originalLines = content.split('\n').length;
+
+  const minified = lang === 'vue'
+    ? minifyVue(content)
+    : minifyContent(content, lang);
+
+  const minifiedLines = minified.split('\n').length;
+  const pct = originalLines > 0 ? Math.round((1 - minifiedLines / originalLines) * 100) : 0;
+
+  return {
+    content: [{
+      type: 'text',
+      text: `[cairn: ${originalLines} → ${minifiedLines} lines (-${pct}%)]\n${minified}`,
+    }],
+  };
+}