dude-claude-plugin 2026.2.1

package/.claude/settings.local.json

@@ -0,0 +1,38 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git ls-tree:*)",
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:modelcontextprotocol.info)",
+      "WebFetch(domain:alexgarcia.xyz)",
+      "Bash(ls:*)",
+      "Bash(git -C /Users/fingerskier/dev/fingerskier/dude-claude-plugin log --oneline --all)",
+      "Bash(chmod:*)",
+      "Bash(npm install:*)",
+      "Bash(echo:*)",
+      "Bash(source ~/.zshrc)",
+      "Bash(node:*)",
+      "Bash(export NVM_DIR=\"$HOME/.nvm\")",
+      "Bash([ -s \"$NVM_DIR/nvm.sh\" ])",
+      "Bash(. \"$NVM_DIR/nvm.sh\")",
+      "Bash([ -s \"/opt/homebrew/opt/nvm/nvm.sh\" ])",
+      "Bash(. \"/opt/homebrew/opt/nvm/nvm.sh\")",
+      "Bash(nvm list:*)",
+      "Bash(volta which:*)",
+      "Bash(git -C /Users/fingerskier/dev/fingerskier/dude-claude-plugin ls-files:*)",
+      "Bash(git -C /Users/fingerskier/dev/fingerskier/dude-claude-plugin status --short)",
+      "Bash(git -C /Users/fingerskier/dev/fingerskier/dude-claude-plugin log --oneline -10)",
+      "Bash(xargs:*)",
+      "Bash(git -C /Users/fingerskier/dev/fingerskier/dude-claude-plugin check-ignore node_modules)",
+      "Bash(git rm:*)",
+      "Bash(git add:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\nAdd .gitignore and remove node_modules from git tracking\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "dude"
+  ],
+  "outputStyle": "default"
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "dude": {
+      "command": "node",
+      "args": ["bin/dude-claude.js", "mcp"]
+    }
+  }
+}

package/README.md

@@ -0,0 +1,57 @@
+# Dude Claude Plugin
+A context multiplier plug-in for Claude CLI
+
+## Install
+
+### npx (recommended)
+
+Add MCP server config to Claude CLI settings (`~/.claude.json` or project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "dude": {
+      "command": "npx",
+      "args": ["dude-claude-plugin", "mcp"]
+    }
+  }
+}
+```
+
+### From source
+
+1. Clone the repo
+2. `npm install`
+3. Add MCP server config:
+   ```json
+   {
+     "mcpServers": {
+       "dude": {
+         "command": "node",
+         "args": ["/path/to/dude-claude-plugin/bin/dude-claude.js", "mcp"]
+       }
+     }
+   }
+   ```
+4. (Optional) Start the web UI: `npm run serve`
+
+## Features
+
+* Local sqlite database~ auto-create
+* Save records for each project
+  * by repo name (for Git)
+  * by path (for non-Git)
+* Each record gets a vector embedding
+* Prior to a think
+  * retrieve relevant records from db via semantic search
+* After each think
+  * If it's a fix upsert associated `issue`record(s)
+  * if it's an improvement upsert associated `specification` record(s)
+* Tools for Claude
+  * search ~ semantic vector search
+  * CRUD project
+  * CRUD issue ~ per project
+  * CRID specification ~ per project
+  * 
+* Local webserver to do manual CRUD
+

package/bin/dude-claude.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+const command = process.argv[2] || 'mcp';
+
+switch (command) {
+  case 'mcp': {
+    const { startServer } = await import('../src/server.js');
+    await startServer();
+    break;
+  }
+  case 'serve': {
+    const { startWebServer } = await import('../src/web.js');
+    await startWebServer();
+    break;
+  }
+  default:
+    console.error(`Usage: dude-claude [mcp|serve]
+
+Commands:
+  mcp    Start the MCP stdio server (default)
+  serve  Start the web UI server on http://127.0.0.1:${process.env.DUDE_PORT || 3456}`);
+    process.exit(1);
+}

package/doc/SPEC.md

@@ -0,0 +1,322 @@
+# Dude Claude Plugin — Implementation Specification
+
+Ultra-minimal RAG and cross-project memory for Claude CLI.
+
+## 1. Architecture Overview
+
+The plugin is an **MCP (Model Context Protocol) stdio server** written in Node.js.
+Claude CLI launches it as a subprocess and communicates via JSON-RPC 2.0 over stdin/stdout.
+
+Companion **hooks** (configured in `.claude/settings.json`) fire at session boundaries to automatically inject retrieved context and persist learnings without explicit tool calls.
+
+```
+Claude CLI
+  ├── MCP stdio server  (tools: search, CRUD)
+  │     └── SQLite + vec0 extension
+  └── Hooks
+        ├── PreToolUse   → auto-retrieve relevant records
+        └── Stop         → auto-upsert issue/spec records
+```
+
+## 2. Technology Stack
+
+| Component       | Choice                | Rationale                              |
+|-----------------|-----------------------|----------------------------------------|
+| Runtime         | Node.js >=18          | Claude CLI ecosystem is JS/TS-centric  |
+| Language        | Plain JavaScript (ESM)| Zero build step; ultra-minimal goal    |
+| Database        | better-sqlite3        | Synchronous, zero-config, single-file  |
+| Vector search   | sqlite-vec (vec0)     | SQLite extension; no external service  |
+| Embeddings      | Local: all-MiniLM-L6-v2 via `onnxruntime-node` | Offline, fast, 384-dim |
+| MCP SDK         | `@modelcontextprotocol/sdk` | Official MCP server library   |
+| Web UI          | Bare `http` module + static HTML | No framework; minimal       |
+
+### Dependency Summary
+
+```
+dependencies:
+  @modelcontextprotocol/sdk
+  better-sqlite3
+  sqlite-vec
+  onnxruntime-node
+  @xenova/transformers   # wraps ONNX for embedding generation
+```
+
+## 3. Data Model
+
+Single SQLite file per user: `~/.dude-claude/dude.db`
+
+### 3.1 `project`
+
+| Column      | Type    | Notes                                      |
+|-------------|---------|--------------------------------------------|
+| id          | INTEGER | PK, autoincrement                          |
+| name        | TEXT    | UNIQUE — repo name (git) or absolute path  |
+| created_at  | TEXT    | ISO-8601                                   |
+| updated_at  | TEXT    | ISO-8601                                   |
+
+### 3.2 `record`
+
+A record is either an **issue** or a **specification**. 
+Both share one table to keep queries and embeddings uniform.
+
+| Column      | Type    | Notes                                         |
+|-------------|---------|-----------------------------------------------|
+| id          | INTEGER | PK, autoincrement                             |
+| project_id  | INTEGER | FK → project.id                               |
+| kind        | TEXT    | `'issue'` or `'spec'`                         |
+| title       | TEXT    | Short summary                                 |
+| body        | TEXT    | Full description / details                    |
+| status      | TEXT    | `'open'` / `'resolved'` / `'archived'`        |
+| created_at  | TEXT    | ISO-8601                                      |
+| updated_at  | TEXT    | ISO-8601                                      |
+
+### 3.3 `record_embedding` (virtual — vec0)
+
+| Column      | Type         | Notes                          |
+|-------------|--------------|--------------------------------|
+| record_id   | INTEGER      | FK → record.id                 |
+| embedding   | FLOAT[384]   | all-MiniLM-L6-v2 output        |
+
+Created via:
+```sql
+CREATE VIRTUAL TABLE record_embedding USING vec0(
+  record_id INTEGER PRIMARY KEY,
+  embedding FLOAT[384]
+);
+```
+
+### 3.4 Project Identification
+
+On startup the server determines the current project:
+1. Run `git rev-parse --show-toplevel` — if it succeeds, use the **basename** as the project name.
+2. Otherwise, use the **working directory path** as the project name.
+3. Upsert into `project` table.
+
+## 4. MCP Tools
+
+All tools are exposed under the MCP server name `dude`. Claude sees them as `mcp__dude__<tool>`.
+
+### 4.1 `search`
+
+Semantic search across records.
+By default, search includes cross-project results so that learnings from one project can inform another.
+Results from the current project are ranked higher; cross-project results appear at lower weight.
+Each result includes the originating `project` name/ID for disambiguation.
+
+| Parameter    | Type    | Required | Default | Description                       |
+|--------------|---------|----------|---------|-----------------------------------|
+| query        | string  | yes      | —       | Natural language search query     |
+| kind         | string  | no       | both    | Filter: `'issue'`, `'spec'`, or `'all'` |
+| project      | string  | no       | current | Project name to boost; `'*'` for equal weight across all projects |
+| limit        | integer | no       | 5       | Max results returned              |
+
+Returns: array of `{ id, project, kind, title, body, status, similarity }` sorted by descending similarity.
+Results with similarity < 0.3 are excluded.
+The `project` field defaults to the current project but is always present in the response so callers can distinguish cross-project results.
+
+### 4.2 `upsert_record`
+
+Create or update a record.
+If `id` is provided, update; otherwise insert with deduplication (see below).
+
+| Parameter  | Type    | Required | Description              |
+|------------|---------|----------|--------------------------|
+| id         | integer | no       | Record ID to update      |
+| kind       | string  | yes      | `'issue'` or `'spec'`   |
+| title      | string  | yes      | Short summary            |
+| body       | string  | no       | Full description         |
+| status     | string  | no       | Defaults to `'open'`     |
+
+On upsert the server:
+1. Generates an embedding from `title + ' ' + body`.
+2. **Deduplication**: If no `id` is provided, query `record_embedding` for existing records in the same project and `kind` whose embedding distance is below a configurable threshold (default cosine distance ≤ 0.15).  If a close match exists, treat the operation as an update of that record instead of creating a duplicate.
+3. Writes (insert or update) the record row.
+4. Upserts into `record_embedding`.
+
+### 4.3 `get_record`
+
+| Parameter | Type    | Required |
+|-----------|---------|----------|
+| id        | integer | yes      |
+
+Returns full record fields.
+
+### 4.4 `list_records`
+
+| Parameter | Type    | Required | Default |
+|-----------|---------|----------|---------|
+| kind      | string  | no       | both    |
+| status    | string  | no       | all     |
+| project   | string  | no       | current |
+
+Returns array of `{ id, kind, title, status, updated_at }`.
+
+### 4.5 `delete_record`
+
+| Parameter | Type    | Required |
+|-----------|---------|----------|
+| id        | integer | yes      |
+
+Deletes record and its embedding.
+
+### 4.6 `list_projects`
+
+No parameters. Returns all known projects.
+
+## 5. Hooks
+
+Hooks are configured in the project or user settings and call into the MCP tools automatically.
+
+### 5.1 Auto-Retrieve (UserPromptSubmit)
+
+When the user submits a prompt, a hook runs `mcp__dude__search` with the user's message as the query.
+Results are injected as additional context so Claude has relevant history before it begins reasoning.
+
+**Settings entry:**
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.dude-claude/hooks/auto-retrieve.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The hook script:
+1. Reads the user prompt from stdin JSON (`tool_input` or equivalent).
+2. Queries the SQLite database directly for speed (MCP is not required for hook scripts).
+3. If results exist, writes the top **5** results (configurable via `DUDE_CONTEXT_LIMIT` env var or the `contextLimit` key in config) to stdout as context for Claude.
+
+### 5.2 Auto-Persist (Stop)
+
+When Claude finishes responding, a `Stop` hook evaluates whether the conversation involved a fix or improvement and upserts records accordingly.
+
+**Settings entry:**
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Review the conversation. If a bug was fixed, output JSON: {\"action\":\"upsert\",\"kind\":\"issue\",\"title\":\"...\",\"body\":\"...\",\"status\":\"resolved\"}. If a feature or improvement was made, output JSON: {\"action\":\"upsert\",\"kind\":\"spec\",\"title\":\"...\",\"body\":\"...\"}. If neither, output {\"action\":\"none\"}.",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+A follow-up command hook parses this output and calls `mcp__dude__upsert_record`.
+
+**Fallback behavior**: If the model returns malformed JSON or declines to classify, the hook silently skips the upsert (no data loss, no user-facing error) **and** emits a tool-result message to Claude's worklog noting that the auto-persist step was skipped and why (e.g., "Auto-persist skipped: malformed JSON from classification prompt").
+
+### 5.3 Classification Logic
+
+"Fix" vs "improvement" is determined by the Stop hook's LLM prompt evaluation — not by heuristics.
+The prompt asks Claude to classify the work that was done.
+This keeps the logic simple and leverages the model's understanding of the conversation.
+
+The same fallback applies here: if classification fails, the hook skips silently and logs a worklog message.
+
+## 6. Web UI
+
+A minimal local HTTP server for manual CRUD when Claude CLI isn't running.
+
+| Detail     | Value                                    |
+|------------|------------------------------------------|
+| Port       | 3456 (configurable via `DUDE_PORT` env)  |
+| Start      | `npx dude-claude serve`                  |
+| Auth       | None (localhost only, binds 127.0.0.1)   |
+
+### Endpoints
+
+| Method | Path                     | Description               |
+|--------|--------------------------|---------------------------|
+| GET    | `/`                      | Static HTML SPA           |
+| GET    | `/api/projects`          | List projects             |
+| GET    | `/api/records?project=&kind=&status=` | List records |
+| GET    | `/api/records/:id`       | Get record                |
+| POST   | `/api/records`           | Create record             |
+| PUT    | `/api/records/:id`       | Update record             |
+| DELETE | `/api/records/:id`       | Delete record             |
+| POST   | `/api/search`            | Semantic search           |
+
+The SPA is a single `index.html` file served from `web/index.html` using the built-in `http` module. No bundler.
+
+## 7. File Layout
+
+```
+dude-claude-plugin/
+  package.json
+  bin/
+    dude-claude.js          # CLI entry point (MCP server + serve command)
+  src/
+    server.js               # MCP server setup + tool handlers
+    db.js                   # SQLite schema init, migration runner, query helpers
+    embed.js                # Embedding generation
+    web.js                  # HTTP server for manual CRUD
+    migrations/
+      001-initial.js        # Creates project, record, record_embedding tables
+  web/
+    index.html              # Single-page CRUD UI
+  hooks/
+    auto-retrieve.js        # UserPromptSubmit hook script
+    auto-persist.js         # Stop hook follow-up script
+  doc/
+    SPEC.md                 # This file
+  .mcp.json                 # MCP server registration for Claude CLI
+```
+
+## 8. Schema Migration
+
+Schema changes are handled via **versioned migration scripts** stored in `src/migrations/` (e.g., `001-initial.js`, `002-add-index.js`).
+
+On startup, `db.js`:
+1. Ensures a `schema_version` table exists (`CREATE TABLE IF NOT EXISTS schema_version (version INTEGER PRIMARY KEY)`).
+2. Reads the current version (or 0 if the table is empty).
+3. Runs any migration scripts with a version number greater than the current version, in order.
+4. Updates `schema_version` to the latest version after all pending migrations succeed.
+
+Migrations run inside a transaction so a failed migration leaves the database unchanged.
+
+### File Layout Addition
+
+```
+src/
+  migrations/
+    001-initial.js        # Creates project, record, record_embedding tables
+    002-...               # Future schema changes
+```
+
+## 9. Configuration
+
+### `.mcp.json` (project-scoped, committed)
+
+```json
+{
+  "mcpServers": {
+    "dude": {
+      "command": "node",
+      "args": ["bin/dude-claude.js", "mcp"]
+    }
+  }
+}
+```
+
+### User-global install
+
+```bash
+claude mcp add --transport stdio dude -- node /path/to/dude-claude-plugin/bin/dude-claude.js mcp
+```

package/hooks/auto-persist.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+/**
+ * Stop hook — auto-persist records from conversation classification.
+ * Reads classification JSON from stdin, upserts records as needed.
+ * On malformed JSON or action=none, exits silently.
+ */
+
+import { embed } from '../src/embed.js';
+import { initDb, upsertRecord, getCurrentProject } from '../src/db.js';
+
+try {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString().trim();
+
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.stdout.write('Auto-persist skipped: malformed JSON from classification prompt\n');
+    process.exit(0);
+  }
+
+  if (!input.action || input.action === 'none') {
+    process.exit(0);
+  }
+
+  if (input.action === 'upsert') {
+    const kind = input.kind || 'issue';
+    const title = input.title || 'Untitled';
+    const body = input.body || '';
+    const status = input.status || 'open';
+
+    await initDb();
+    const text = `${title} ${body}`.trim();
+    const embedding = await embed(text);
+
+    const record = upsertRecord(
+      {
+        projectId: getCurrentProject().id,
+        kind,
+        title,
+        body,
+        status,
+      },
+      embedding,
+    );
+
+    process.stdout.write(`Auto-persisted ${kind}: "${record.title}" (id=${record.id})\n`);
+  }
+} catch (err) {
+  // Non-blocking: exit cleanly on any error
+  console.error(`[dude] auto-persist error: ${err.message}`);
+  process.stdout.write(`Auto-persist skipped: ${err.message}\n`);
+  process.exit(0);
+}

package/hooks/auto-retrieve.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+/**
+ * UserPromptSubmit hook — auto-retrieve relevant records.
+ * Reads the user prompt from stdin JSON, embeds it, searches the DB,
+ * and writes formatted context to stdout for Claude to see.
+ */
+
+import { embed } from '../src/embed.js';
+import { initDb, searchRecords } from '../src/db.js';
+
+try {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const input = JSON.parse(Buffer.concat(chunks).toString());
+  const prompt = input.prompt || input.tool_input?.prompt || '';
+
+  if (!prompt.trim()) {
+    process.exit(0);
+  }
+
+  await initDb();
+  const embedding = await embed(prompt);
+  const limit = Number(process.env.DUDE_CONTEXT_LIMIT) || 5;
+  const results = searchRecords(embedding, { limit });
+
+  if (results.length === 0) {
+    process.exit(0);
+  }
+
+  // Format context for Claude
+  const lines = ['[dude] Relevant context from memory:\n'];
+  for (const r of results) {
+    lines.push(`- [${r.kind}] ${r.title} (project: ${r.project}, status: ${r.status}, similarity: ${r.similarity.toFixed(2)})`);
+    if (r.body) {
+      lines.push(`  ${r.body.slice(0, 200)}${r.body.length > 200 ? '…' : ''}`);
+    }
+  }
+  process.stdout.write(lines.join('\n') + '\n');
+} catch (err) {
+  // Non-blocking: exit cleanly on any error
+  console.error(`[dude] auto-retrieve error: ${err.message}`);
+  process.exit(0);
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "dude-claude-plugin",
+  "version": "2026.2.1",
+  "description": "Ultra-minimal RAG and cross-project memory for Claude CLI",
+  "type": "module",
+  "bin": {
+    "dude-claude": "bin/dude-claude.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/dude-claude.js mcp",
+    "serve": "node bin/dude-claude.js serve"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.2",
+    "better-sqlite3": "^11.8.1",
+    "sqlite-vec": "^0.1.6",
+    "@huggingface/transformers": "^3.4.1"
+  },
+  "license": "MIT"
+}