Skip to content
Back to search

karp-inspector

SkillWorks with Claude CodeGitHub

The Complete Development Intelligence Server for Claude Desktop

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/souldriver007--karp-inspector/badge.svg)](/listings/souldriver007--karp-inspector)

HTML

<a href="/listings/souldriver007--karp-inspector"><img src="/api/listings/souldriver007--karp-inspector/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Extension Install (Recommended)

1. Download `karp-inspector.mcpb` from the [latest release](https://github.com/souldriver007/karp-inspector/releases/latest). 2. In Claude Desktop, open **Settings** (on Windows: **File → Settings**), click **Desktop app** in the left panel, scroll to the bottom and choose **Extensions → Manage → Advanced settings → Install extension**, then select the downloaded file. 3. Choose a **Data Folder** (where the database lives) and one or more **Project Folders** (the code Claude can read and edit). 4. Click **Enable**, then **Configure**, and choose **Allow all** on the permissions screen.

Then ask Claude to run `server_status`: it should report version 0.5.0 and 52 tools.

The server runs directly via stdio (no proxy, no background process) — same pattern as every other KARP MCP server.

Upgrading from Inspector Premium

The new extension installs under a different name, so it sits alongside the old one. Disable or remove **KARP Inspector Premium** first so the two never write to the same database at once, then install **KARP Inspector** and choose the **same Data Folder** you used before. Your knowledge graph, code index and snapshots carry straight over: the database file names (`premium.db`, `premium-*.db`) are unchanged for exactly this reason. There are no licence fields any more, so there's nothing to enter.

Manual Config (Development)

1. `git clone https://github.com/souldriver007/karp-inspector.git` 2. Inside the folder, run `npm install`, then `npm run download-model` (the embedding model isn't committed to git; about 33MB) 3. Add to your `claude_desktop_config.json`:

{
  "mcpServers": {
    "karp-inspector": {
      "command": "node",
      "args": ["C:\\path\\to\\karp-inspector\\server\\index.js"],
      "env": {
        "ALLOWED_DIRS": "C:\\Users\\You\\Projects;D:\\Code",
        "DATA_PATH": "C:\\path\\to\\your\\chosen\\data\\folder",
        "ALLOWED_COMMANDS": "node --check"
      }
    }
  }
}

> `ALLOWED_COMMANDS` above is the safe default. Adding `npm test`, `npm run build` or `pytest` lets the project you point at execute its own code — only do that for repositories you trust.

4. Restart Claude Desktop 5. Say: *"Set project to C:\path\to\my\project and index it"*

Build the extension yourself

npm install
npm run download-model
npm run build

The extension is written to `dist/karp-inspector.mcpb`.

> **Linux (x64):** run installs as `ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install` (or `npm ci`). Otherwise onnxruntime-node's install script tries to download optional GPU binaries, and that download currently fails. Inspector only needs the CPU binaries, which are already in the package.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 507 lines
  1. # KARP Inspector
  2. ### The Complete Development Intelligence Server for Claude Desktop
  3. [![Smoke Test](https://github.com/souldriver007/karp-inspector/actions/workflows/smoke-test.yml/badge.svg)](https://github.com/souldriver007/karp-inspector/actions/workflows/smoke-test.yml)
  4. **Version:** 0.5.0
  5. **Author:** [SoulDriver](https://souldriver.com.au) (Adelaide, Australia)
  6. **Licence:** MIT — free and open source, every tool included
  7. > Formerly **KARP Inspector Premium**. Up to v0.4.0 it was a paid extension with a licence key. From v0.5.0 all 52 tools are free for everyone.
  8. ---
  9. ## What Is This?
  10. KARP Inspector is a single MCP server that gives Claude everything it needs to understand, navigate, modify, and reason about your codebase — plus a persistent knowledge graph that remembers decisions, tracks changes, and connects code to context.
  11. **52 tools. One server. One database. Zero external services.**
  12. > Everything runs locally. Your code never leaves your machine.
  13. ---
  14. ## Inspector vs Inspector Lite
  15. Inspector Lite is the lightweight, search-only sibling. Inspector is the full toolkit.
  16. | Capability | Inspector Lite | Inspector |
  17. |---|---|---|
  18. | Semantic code search | ✅ | ✅ |
  19. | Grep / file outline / diff | ✅ | ✅ |
  20. | Read files | ❌ | ✅ |
  21. | Write / patch files | ❌ | ✅ (atomic, corruption-safe) |
  22. | Move / copy / delete | ❌ | ✅ (soft delete with trash) |
  23. | Find files (glob + filters) | ❌ | ✅ |
  24. | Search & replace (cross-file) | ❌ | ✅ (with dry-run preview) |
  25. | Knowledge graph | ❌ | ✅ (remember, recall, connect) |
  26. | Custom node types | ❌ | ✅ (propose any schema) |
  27. | Semantic graph search | ❌ | ✅ (ONNX embeddings) |
  28. | Repo map (compressed overview) | ❌ | ✅ |
  29. | Dependency graph | ❌ | ✅ (with circular dep detection) |
  30. | Impact analysis | ❌ | ✅ (blast radius + symbol tracking) |
  31. | Dead code detection | ❌ | ✅ |
  32. | TODO / FIXME scanner | ❌ | ✅ |
  33. | Security audit | ❌ | ✅ (secrets, keys, high-entropy) |
  34. | Git checkpoint | ❌ | ✅ (or SQLite fallback) |
  35. | Undo / rollback | ❌ | ✅ (snapshot-based revert) |
  36. | Run terminal commands | ❌ | ✅ (pre-approved patterns only) |
  37. | Disk usage analysis | ❌ | ✅ |
  38. | File checksums | ❌ | ✅ (SHA256) |
  39. | Unified database | ❌ | ✅ (single SQLite file) |
  40. | Version history | File snapshots | SQLite snapshots (searchable) |
  41. | Index observability | ❌ | ✅ (list, status, forget, export/import) |
  42. | Server diagnostics | ❌ | ✅ (`server_status`) |
  43. | **Total tools** | **9** | **52** |
  44. ---
  45. ## Installation
  46. ### Extension Install (Recommended)
  47. 1. Download `karp-inspector.mcpb` from the [latest release](https://github.com/souldriver007/karp-inspector/releases/latest).
  48. 2. In Claude Desktop, open **Settings** (on Windows: **File → Settings**), click **Desktop app** in the left panel, scroll to the bottom and choose **Extensions → Manage → Advanced settings → Install extension**, then select the downloaded file.
  49. 3. Choose a **Data Folder** (where the database lives) and one or more **Project Folders** (the code Claude can read and edit).
  50. 4. Click **Enable**, then **Configure**, and choose **Allow all** on the permissions screen.
  51. Then ask Claude to run `server_status`: it should report version 0.5.0 and 52 tools.
  52. The server runs directly via stdio (no proxy, no background process) — same pattern as every other KARP MCP server.
  53. ### Upgrading from Inspector Premium
  54. The new extension installs under a different name, so it sits alongside the old one. Disable or remove **KARP Inspector Premium** first so the two never write to the same database at once, then install **KARP Inspector** and choose the **same Data Folder** you used before. Your knowledge graph, code index and snapshots carry straight over: the database file names (`premium.db`, `premium-*.db`) are unchanged for exactly this reason. There are no licence fields any more, so there's nothing to enter.
  55. ### Manual Config (Development)
  56. 1. `git clone https://github.com/souldriver007/karp-inspector.git`
  57. 2. Inside the folder, run `npm install`, then `npm run download-model` (the embedding model isn't committed to git; about 33MB)
  58. 3. Add to your `claude_desktop_config.json`:
  59. ```json
  60. {
  61. "mcpServers": {
  62. "karp-inspector": {
  63. "command": "node",
  64. "args": ["C:\\path\\to\\karp-inspector\\server\\index.js"],
  65. "env": {
  66. "ALLOWED_DIRS": "C:\\Users\\You\\Projects;D:\\Code",
  67. "DATA_PATH": "C:\\path\\to\\your\\chosen\\data\\folder",
  68. "ALLOWED_COMMANDS": "node --check"
  69. }
  70. }
  71. }
  72. }
  73. ```
  74. > `ALLOWED_COMMANDS` above is the safe default. Adding `npm test`, `npm run build` or `pytest` lets the project you point at execute its own code — only do that for repositories you trust.
  75. 4. Restart Claude Desktop
  76. 5. Say: *"Set project to C:\path\to\my\project and index it"*
  77. ### Build the extension yourself
  78. ```bash
  79. npm install
  80. npm run download-model
  81. npm run build
  82. ```
  83. The extension is written to `dist/karp-inspector.mcpb`.
  84. > **Linux (x64):** run installs as `ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install` (or `npm ci`). Otherwise onnxruntime-node's install script tries to download optional GPU binaries, and that download currently fails. Inspector only needs the CPU binaries, which are already in the package.
  85. ---
  86. ## Testing
  87. ```bash
  88. npm run smoke
  89. ```
  90. Spawns the server and drives it over stdio with a real JSON-RPC client — no
  91. Claude Desktop, no GUI, no SDK dependency. 32 assertions, a few
  92. seconds.
  93. Every assertion corresponds to something that actually broke during
  94. development, so this is a regression net rather than a formality:
  95. | Assertion | The bug it guards against |
  96. |---|---|
  97. | `set_project` outside the boundary is denied | The directory sandbox once covered only one module in four, making `grep_code` an arbitrary-file reader |
  98. | Two roots sharing a `README.md` both index | Chunk ids were `filepath:line`, so any two projects sharing a relative path collided on the primary key |
  99. | A one-line `const a = () => {}, b = () => {}` indexes | Two chunks with the same start line produced duplicate ids |
  100. | `index_project` returns chunks > 0 | File hashes committed before chunks; an interrupted run left the index claiming N files with zero chunks, unrecoverable |
  101. | `search_code` ranks the right file first | Proves the vectors are meaningful, not merely present |
  102. | Hybrid finds a file semantic search misses | `count-lines.js` contains `totalLines`; semantic search returned `countFiles` and `countRows` instead |
  103. | Export records `embedding_dtype` | An index recording only the model name imports cleanly into a server on the other precision and returns plausible nonsense |
  104. | Deleting a file yields `pruned: 1` | Deleted files' chunks previously survived forever |
  105. | Ambiguous relative path errors | `resolveInRoots` used to return the first match and call it an answer |
  106. | `security_audit`, `git_checkpoint`, `run_check` and export → import all run | Before v0.5.0 these were licence-gated, so CI only reached them when licence secrets were set, and `import_index` shipped broken because nothing exercised it |
  107. The fixture is created under the OS temp directory, which on macOS is a
  108. symlink into `/private/var/...` — so the run also exercises the `realpath`
  109. handling in `assertAllowed`.
  110. CI runs the same suite on **macOS, Windows and Linux** on every push, covering
  111. every tool, including `run_check`'s non-Windows `which` branch. See
  112. `.github/workflows/smoke-test.yml`.
  113. ---
  114. ## How search works
  115. `search_code` runs two rankers over the same chunks and fuses the results.
  116. **Semantic** compares the query's embedding against each chunk's. Good at
  117. concepts — "validate a token before the request runs" finds the middleware even
  118. though it never uses those words.
  119. **Literal** scores term frequency over each chunk's text and name, with
  120. identifiers split on camelCase and snake_case so `totalLines` matches "total
  121. lines". Good at the thing semantic search is worst at: you half-remember an
  122. identifier, a config key, or an error string.
  123. **Fusion** uses Reciprocal Rank Fusion — `Σ 1/(60 + rank)` across both lists.
  124. RRF works on ranks rather than raw scores, which matters because cosine
  125. similarity and term frequency aren't on comparable scales. Every result reports
  126. `semantic_score`, `lexical_score` and the fused `rrf` value, so a ranking can be
  127. explained rather than taken on trust.
  128. Why both: on a real codebase, a query for "count the number of lines of code"
  129. returned `countFiles`, `countRows` and `getRecordCounts` from semantic search
  130. alone — and missed a file named `count-lines.js` containing `totalLines`. Literal
  131. matching finds it instantly. Neither ranker is sufficient by itself.
  132. Pass `mode: "semantic"` or `mode: "literal"` to force one.
  133. **A note on queries.** Search quality depends more on vocabulary than on any
  134. setting. Search the way the code is *written*, not the way you'd describe it to a
  135. colleague — `"service worker cache"` rather than `"works offline"`. The embedding
  136. model matches vocabulary in context; it does not reliably infer that
  137. `caches.match()` means offline support.
  138. ---
  139. ## Indexed file types
  140. Text and source files up to 1MB:
  141. ```
  142. .py .js .jsx .ts .tsx .html .css .md .txt
  143. .sql .sh .ps1 .bat
  144. .go .rs .java .cs .rb .php .vue .svelte .kt .swift
  145. .c .h .cpp .hpp .scala .ex .exs
  146. ```
  147. Config and data formats (`.json`, `.yaml`, `.toml`, `.ini`) are deliberately
  148. not indexed: generated files like `package-lock.json` crowd out real code in
  149. search results. `grep_code` reads straight from disk, so literal lookups in
  150. those files still work.
  151. Three of these get structural parsing rather than fixed-size windows:
  152. - **Python** — functions and classes become individual chunks
  153. - **JavaScript / TypeScript** — parsed with `acorn`
  154. - **HTML** — inline `<script>` is parsed as JavaScript with correct absolute
  155. line numbers, inline `<style>` is skipped, and remaining markup is chunked as
  156. prose only when it reads like prose rather than a navigation menu
  157. Everything else is chunked into overlapping windows, which works acceptably for
  158. uniform content.
  159. `.gitignore` is respected, along with a default skip list (`node_modules`,
  160. `.git`, `dist`, `build`, `__pycache__` and similar). If a root contains nothing
  161. indexable, `index_project` says so and lists what it looks for, rather than
  162. reporting a successful index of nothing.
  163. ---
  164. ## Configuration Reference
  165. | Environment Variable | Required | Description | Example |
  166. |---|---|---|---|
  167. | `ALLOWED_DIRS` | **Required** (manual config) | Semicolon-separated list of directories the server may access. **There is no unrestricted mode** — if this is empty and no `project_dirs` are passed, every filesystem, search and analysis tool refuses to run. The `.mcpb` extension config uses `project_dirs` (a folder picker, see below) instead of this env var — both feed the same boundary. | `C:\Users\Me\Desktop;D:\Projects` |
  168. | `DATA_PATH` | Required via `.mcpb` config screen (Data Folder); optional in manual config | Where the unified SQLite database is stored, including automatic snapshots (`DATA_PATH/snapshots/`). Manual-config default is `~/.karp-premium` (the name dates from the Premium release and is kept so existing data still loads). | `C:\path\to\data` |
  169. | `ALLOWED_COMMANDS` | Optional | Semicolon-separated command prefixes for `run_check`. Defaults to `node --check` only. Leave empty to disable terminal execution entirely. **Adding test or build runners lets a project execute its own code** — `npm test`/`npm run build` run scripts from that project's `package.json`, and `pytest` runs its `conftest.py`. Only add them for repositories you trust. | `node --check;npm test;pytest` |
  170. | `TRASH_DIR` | Optional | Where soft-deleted files go. Defaults to `DATA_PATH/trash`. | `C:\path\to\trash` |
  171. ### MCPB Extension Config (as actually shipped)
  172. Users configure these two fields via Claude Desktop's built-in settings UI when installing the `.mcpb`. `data_path` is a single folder picker; `project_dirs` is a multi-select folder picker (`"multiple": true`) — click it again to add more folders, and it expands to as many directories as you pick:
  173. ```json
  174. {
  175. "user_config": {
  176. "data_path": {
  177. "type": "directory",
  178. "title": "Data Folder",
  179. "description": "Choose where to store your knowledge graph and code index. Pick any folder — your data stays on your machine and survives extension updates.",
  180. "required": true
  181. },
  182. "project_dirs": {
  183. "type": "directory",
  184. "title": "Project Folders",
  185. "description": "Choose one or more top-level folders Claude can read, write, and search within (subfolders included). This is the file boundary for all filesystem tools — Claude can't touch anything outside these. Click again to add more.",
  186. "multiple": true,
  187. "required": true
  188. }
  189. }
  190. }
  191. ```
  192. Under the hood, multi-select directory fields expand into separate command-line arguments (per the MCPB spec — arrays aren't passed through `env` as a single string), so `project_dirs` is wired into `args` rather than `env`. `server/index.js` reads both `process.argv` (for the `.mcpb` path) and the `ALLOWED_DIRS` env var (for manual config), merges and dedupes them.
  193. ---
  194. ## All 52 Tools
  195. ### Filesystem (20 tools)
  196. | Tool | Description |
  197. |---|---|
  198. | `list_allowed_directories` | Show which directories the server can access |
  199. | `read_file` | Read a text file with optional head/tail line limits |
  200. | `read_files` | Read multiple files in a single call |
  201. | `write_file` | Atomic write (temp file + rename) with parent dir creation |
  202. | `patch_file` | Edit a file by replacing one exact text match |
  203. | `list_directory` | List files and dirs with type, size, modification date |
  204. | `directory_tree` | Recursive tree view respecting .gitignore |
  205. | `file_info` | Detailed metadata: size, dates, permissions, MIME type |
  206. | `move_file` | Move or rename files and directories |
  207. | `copy_file` | Copy files or directories (recursive) |
  208. | `create_directory` | Create directories (and parents) |
  209. | `delete_file` | Soft delete to trash (or permanent) |
  210. | `find_files` | Glob pattern search with date/size filters |
  211. | `search_replace` | Cross-file find and replace with dry-run preview |
  212. | `disk_usage` | Biggest files, directory sizes, breakdown by extension |
  213. | `checksum` | SHA256 hash of one or more files |
  214. | `run_check` | Execute pre-approved terminal commands (syntax check, tests, linter) |
  215. | `list_allowed_commands` | Show which commands are approved for run_check |
  216. | `git_checkpoint` | Safety checkpoint: git commit or SQLite snapshot fallback |
  217. | `karp_undo` | Revert file changes using saved snapshots |
  218. ### Knowledge Graph (11 tools)
  219. | Tool | Description |
  220. |---|---|
  221. | `remember` | Store a memory, decision, todo, insight, changelog, or custom type |
  222. | `recall` | Semantic search across the knowledge graph by meaning |
  223. | `forget` | Delete a node permanently |
  224. | `connect` | Create a named relationship between two nodes |
  225. | `update` | Edit a node in place — preserves its id, created_at and edges, re-embeds only if the text changed |
  226. | `graph_search` | Keyword search across node summaries and details |
  227. | `graph_list` | Browse nodes by type, tags, or date |
  228. | `propose_node_type` | Create a custom node type with icon and description |
  229. | `kg_status` | Health check: node counts, DB size, embedding coverage |
  230. | `graph_snapshot` | Backup the entire database |
  231. | `re_embed` | Rebuild all vector embeddings |
  232. ### Code Intelligence (14 tools)
  233. | Tool | Description |
  234. |---|---|
  235. | `search_code` | Hybrid code search — fuses semantic similarity with literal term matching. `mode` accepts `hybrid` (default), `semantic`, or `literal` |
  236. | `grep_code` | Exact string or regex search with context lines |
  237. | `file_outline` | Structural overview: classes, functions, signatures, line numbers. Takes an absolute path or one relative to a root |
  238. | `index_project` | Build or rebuild the semantic search index across every configured root |
  239. | `reindex_file` | Re-index a single file after editing. Takes an absolute path or one relative to a root |
  240. | `file_history` | List saved snapshots of a file |
  241. | `file_diff` | Diff between snapshots or against the live file. Refuses rather than guess when the same path exists under several roots |
  242. | `project_stats` | Index statistics: files, chunks, extensions |
  243. | `set_project` | Set one root, or several at once for a monorepo — all search, grep and index tools then span every root |
  244. | `list_projects` | Every indexed root with chunk/file counts, last indexed date, and whether it still exists on disk |
  245. | `index_status` | What's new, changed or deleted since the last index — tells you whether indexing is needed at all |
  246. | `forget_project` | Delete one root's index and reclaim the space. Dry run by default |
  247. | `export_index` | Export a root's chunks and embeddings to a portable file |
  248. | `import_index` | Import an exported index, optionally remapping the root path |
  249. ### Server (1 tool)
  250. | Tool | Description |
  251. |---|---|
  252. | `server_status` | Version, uptime, directory boundary, allowed commands, database size, index totals, snapshot health |
  253. ### Developer Intelligence (6 tools)
  254. | Tool | Description |
  255. |---|---|
  256. | `repo_map` | Compressed structural map — function signatures and class names across a directory, without implementation code. 10,000 lines → 500 tokens. |
  257. | `dependency_graph` | Import/require mapping across the project. Finds circular dependencies. |
  258. | `impact_analysis` | "If I change this file, what breaks?" Blast radius + symbol reference tracking. |
  259. | `dead_code` | Find exported symbols that nothing imports |
  260. | `todo_scan` | Extract TODO, FIXME, HACK, XXX, NOTE comments across the codebase |
  261. | `security_audit` | Scan for API keys, tokens, private keys, high-entropy strings, hardcoded credentials |
  262. ---
  263. ## Architecture
  264. ```
  265. ┌─────────────────────────────────────────────┐
  266. │ KARP Inspector v0.5.0 │
  267. │ 52 tools • 1 server • 1 database │
  268. ├─────────────────────────────────────────────┤
  269. │ │
  270. │ server/index.js ─ MCP Protocol (hand-rolled) │
  271. │ │ runs directly via stdio │
  272. │ │ (Desktop's entry_point) │
  273. │ ├── filesystem.js (20 tools) │
  274. │ ├── graph.js (11 tools) │
  275. │ ├── inspector.js (14 tools) │
  276. │ └── intelligence.js ( 6 tools) │
  277. │ │
  278. │ database.js ── Unified SQLite (WAL mode) │
  279. │ ├── nodes (knowledge graph) │
  280. │ ├── edges (relationships) │
  281. │ ├── type_definitions │
  282. │ ├── chunks (code index) │
  283. │ ├── file_hashes (change detection) │
  284. │ └── snapshots (version history — │
  285. │ auto + manual) │
  286. │ │
  287. │ utils.js ── Shared helpers + dir boundary │
  288. │ │
  289. ├─────────────────────────────────────────────┤
  290. │ Stack: Node.js • SQLite • ONNX • Acorn │
  291. │ Protocol: Hand-rolled MCP (no SDK dep) │
  292. │ Embeddings: bge-small-en-v1.5 (local) │
  293. │ External services: None │
  294. └─────────────────────────────────────────────┘
  295. ```
  296. ### What makes this different
  297. - **Unified database** — Code index, knowledge graph, and version history in one SQLite file. A file write, an index update, and a changelog entry happen in the same transaction.
  298. - **Multi-root projects** — `set_project` takes one directory or several. A monorepo's `frontend/` and `api/`, or a project plus its shared library, are searched and indexed together instead of switching back and forth. Chunk ids are namespaced by root, so two roots holding the same `README.md` or `src/index.js` coexist cleanly.
  299. - **The index is visible and reversible** — `index_status` says whether indexing is even needed, `list_projects` shows what's stored, and `forget_project` removes a root you indexed by mistake. Most tools in this space let you build an index and never look inside it again.
  300. - **No SDK dependency** — Hand-rolled MCP protocol over stdio. Fewer dependencies, fewer failure modes.
  301. - **No external services** — No Docker, no Qdrant, no PostgreSQL, no API keys. Everything runs in-process.
  302. - **Knowledge + code in one tool** — Ask "why did we change the auth flow?" and get both the reasoning (graph) AND the code diff (inspector).
  303. ---
  304. ## Performance
  305. | Scenario | Time |
  306. |---|---|
  307. | First index — 12 files, 117 chunks, model load included | ~17s |
  308. | Re-index — 12 files, 117 chunks, model cached | ~13s |
  309. | Incremental index — 1 changed file | **0.1s** (11 skipped via SHA256) |
  310. | No-op index — nothing changed | 0.02s |
  311. | Semantic search | <1s |
  312. | Grep search | Instant |
  313. | Repo map | Instant |
  314. | Dependency graph (first call / cached) | Instant / cached 60s |
  315. | Project switching (cached) | Instant |
  316. | Git checkpoint (SQLite fallback, 19 files) | <1s |
  317. Embedding runs at roughly **9 chunks/sec** on CPU with the full-precision
  318. bge-small model. That is the dominant cost of a first index and it scales
  319. linearly — 1,800 chunks is about 200 seconds. The fastest index is the one
  320. you don't run, which is what `index_status` and the pre-flight guard on
  321. `index_project` are for. Measured on Windows, Node 24, no GPU acceleration
  322. (`onnxruntime-node` ships CPU-only binaries by default).
  323. ---
  324. ## Supported Languages
  325. **Full AST parsing:** JavaScript, TypeScript, JSX, TSX (via Acorn)
  326. **Regex parsing:** Python (classes, functions, decorators, multi-line signatures)
  327. **Section-based chunking:** HTML, CSS, Markdown, plain text
  328. **Dependency analysis:** JavaScript/TypeScript (import/require), Python (import/from)
  329. ---
  330. ## Requirements
  331. - **Claude Desktop** (Windows or macOS)
  332. - **Node.js 18+** (ships with Claude Desktop)
  333. - **Windows** — developed and tested here
  334. - **macOS / Linux** — core functionality verified by CI on every commit; the `.mcpb` install flow in Claude Desktop has not yet been walked through by hand on a Mac
  335. - ~33MB disk for the bundled embedding model (quantized bge-small, ships inside the extension — no download, works offline)
  336. - No Python, Docker, API keys, or external services
  337. ---
  338. ## How Is This Different?
  339. | Tool | Filesystem | Knowledge Graph | Code Intelligence | Terminal |
  340. |---|---|---|---|---|
  341. | Anthropic Filesystem Extension | ✅ | ❌ | ❌ | ❌ |
  342. | KARP Inspector Lite | ❌ | ❌ | ✅ (9 tools) | ❌ |
  343. | KARP Graph Lite | ❌ | ✅ (11 tools) | ❌ | ❌ |
  344. | Cline | ✅ | ❌ | Partial | ✅ |
  345. | Aider | ✅ | ❌ | Partial | ✅ |
  346. | **KARP Inspector** | **✅ (20 tools)** | **✅ (11 tools)** | **✅ (20 tools)** | **✅ (pre-approved commands)** |
  347. **Key differentiators:**
  348. - Filesystem, knowledge graph and code intelligence in one server
  349. - Unified SQLite database — code changes and decisions in the same store
  350. - Terminal execution limited to the command prefixes you pre-approve
  351. - Impact analysis with blast radius — knows what breaks before you break it
  352. - Repo map — 10,000 lines compressed to 500 tokens
  353. - Security audit built in — catches secrets before they ship
  354. - Free and MIT licensed — read the code, fork it, change it
  355. ---
  356. ## Privacy Policy
  357. KARP Inspector is fully local. **No data is collected, transmitted, or shared.**
  358. - No telemetry, analytics, or tracking
  359. - No network requests after initial model download
  360. - No API keys or external services
  361. - Your code never leaves your machine
  362. - Database stored locally in your configured DATA_PATH
  363. ---
  364. ## Restoring from a Snapshot
  365. If the database gets corrupted, wiped, or bloated, here's how to actually restore from a snapshot:
  366. 1. **Fully quit Claude Desktop first.** Toggling the extension off/on in Desktop's UI is **not sufficient** — the underlying `node.exe` process can stay running with the old (bad) database already loaded in memory, and any write from that stale process will silently overwrite whatever file you restore. On Windows, if Desktop doesn't close cleanly, end it via Task Manager. Confirmed this the hard way: a toggle left `kg_status` still reporting the pre-restore state; only a full close did.
  367. 2. With Desktop closed, copy the snapshot you want over the live database: `<DATA_PATH>\snapshots\auto-<timestamp>.db` (or `premium-<timestamp>.db` for a manual `graph_snapshot`) → `<DATA_PATH>\premium.db`, overwriting it.
  368. 3. Start Claude Desktop back up. `server/index.js` reads `premium.db` fresh on process start — this is the point where your restored snapshot actually takes effect.
  369. 4. Verify with `kg_status` — check `total_nodes`/`total_chunks` and `db_size` match what you expect from the snapshot you restored, not the state you were trying to get away from.
  370. ---
  371. ## Licence
  372. MIT. See [LICENSE](LICENSE). Use it, fork it, ship it.
  373. Up to v0.4.0 this project was sold as KARP Inspector Premium, with 25 of its 52 tools behind an offline licence key. From v0.5.0 the licence check is gone and every tool is free.
  374. ### Third-party components
  375. | Component | Licence |
  376. |---|---|
  377. | [bge-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5) embedding model (BAAI), bundled in the `.mcpb` | MIT |
  378. | [@huggingface/transformers](https://github.com/huggingface/transformers.js) | Apache-2.0 |
  379. | [acorn](https://github.com/acornjs/acorn) and acorn-walk | MIT |
  380. | [sql.js](https://github.com/sql-js/sql.js) | MIT |
  381. ---
  382. ## Contributing
  383. Issues and pull requests are welcome. Please run `npm run smoke` before opening a pull request; CI runs the same suite on Windows, macOS and Linux.
  384. ---
  385. ## Support
  386. - **Bugs and questions:** [GitHub Issues](https://github.com/souldriver007/karp-inspector/issues)
  387. - **Website:** [souldriver.com.au/karp-tools.html](https://souldriver.com.au/karp-tools.html)
  388. ---
  389. **Built in Adelaide, Australia by [SoulDriver](https://souldriver.com.au)**
  390. *Part of the KARP ecosystem — Knowledge Acquisition Research Protocol*
  391. *Democratising access to intelligent tools.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.