Skip to content
Back to search

codeindex

Repo dependency analyzer with **blast-radius impact scoring** for AI-assisted development.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/scheidydude--codeindex/badge.svg)](/listings/scheidydude--codeindex)

HTML

<a href="/listings/scheidydude--codeindex"><img src="/api/listings/scheidydude--codeindex/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.

pip install codeindex

Or from source:

git clone https://github.com/scheidydude/codeindex
cd codeindex
pip install -e .

---

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 · 774 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # codeindex
  2. **Temporal code knowledge graph** with blast-radius impact scoring, semantic symbol search, and git-history-aware dependency analysis — for AI-assisted development.
  3. Point it at any project — Python, JavaScript/TypeScript, Go, Ruby, Rust, Java, PHP, and more — and get:
  4. - A persistent **SQLite graph store** at `<repo>/.codeindex/index.db` — incremental, queryable, temporal
  5. - A `codeindex.json` dependency index written directly into your repo (preserved for backward compatibility)
  6. - Per-file blast-radius scores (how many files break if this one changes), including **historical as-of queries**
  7. - A `symbolindex.json` symbol map so AI can find any function/class without scanning every file
  8. - **Hybrid semantic search** over symbols: natural-language queries fused with keyword + graph expansion
  9. - **Git history backfill** — temporal graph from commit history without touching the working tree
  10. - Ten ways to consume the data: CLI, markdown report, MCP server (10 tools), pre-commit hook, CLAUDE.md injection
  11. - An interactive visualization UI (2D/3D graphs, dependency matrix, treemap)
  12. No build step. No npm. Zero required runtime dependencies — SQLite is stdlib.
  13. ---
  14. ## Install
  15. ```bash
  16. pip install codeindex
  17. ```
  18. Or from source:
  19. ```bash
  20. git clone https://github.com/scheidydude/codeindex
  21. cd codeindex
  22. pip install -e .
  23. ```
  24. ---
  25. ## Quickstart
  26. ```bash
  27. # Build the dependency index (also writes to .codeindex/index.db)
  28. codeindex analyze ./myapp
  29. # Build the symbol index (where every function and class lives)
  30. codeindex symbols ./myapp
  31. # See blast radius for a file before touching it
  32. codeindex impact src/auth.py
  33. # Search symbols with natural language (no embedding endpoint needed — FTS fallback)
  34. codeindex search "validate auth token"
  35. # See what changed since a release tag
  36. codeindex changed-since v1.2.0
  37. # Launch the visualization UI
  38. codeindex serve --viz --repo ./myapp
  39. open http://localhost:8080
  40. ```
  41. ---
  42. ## Commands
  43. ### `codeindex analyze`
  44. ```bash
  45. codeindex analyze [REPO_PATH] [--output PATH] [--watch]
  46. ```
  47. Analyzes the repo and writes `codeindex.json` to the repo root. Detects 12+ languages automatically.
  48. | Flag | Default | Description |
  49. |------|---------|-------------|
  50. | `REPO_PATH` | `.` | Path to repo root |
  51. | `--output` | `<repo>/codeindex.json` | Override output path |
  52. | `--watch` | off | Re-index on file changes (requires `watchdog`) |
  53. ---
  54. ### `codeindex symbols`
  55. ```bash
  56. codeindex symbols [REPO_PATH] [--output PATH] [--inline] [--index PATH]
  57. [--claude-md] [--claude-md-path PATH] [--all-symbols]
  58. ```
  59. Builds a symbol index — a map of every function, class, struct, and type to its exact file and line number. Lets AI tools (and humans) find any symbol in one lookup instead of scanning the entire repo.
  60. **Modes:**
  61. | Flag | Description |
  62. |------|-------------|
  63. | _(none)_ | Write a standalone `symbolindex.json` |
  64. | `--inline` | Embed symbols into each node in `codeindex.json` instead |
  65. | `--claude-md` | Append a compressed symbol summary to `CLAUDE.md` |
  66. Both `--inline` and `--claude-md` can be combined in a single run.
  67. **Options:**
  68. | Flag | Default | Description |
  69. |------|---------|-------------|
  70. | `REPO_PATH` | `.` | Path to repo root |
  71. | `--output` | `<repo>/symbolindex.json` | Output path (standalone mode) |
  72. | `--index` | auto-discovered | Path to `codeindex.json` (for `--inline`) |
  73. | `--claude-md-path` | `<repo>/CLAUDE.md` | Override CLAUDE.md path |
  74. | `--all-symbols` | off | Include non-exported symbols in CLAUDE.md (default: exported only) |
  75. **Examples:**
  76. ```bash
  77. # Standalone symbol index
  78. codeindex symbols ./myapp
  79. # Embed into codeindex.json (one file for blast radius + symbols)
  80. codeindex symbols ./myapp --inline
  81. # Write CLAUDE.md summary so Claude Code loads symbols automatically
  82. codeindex symbols ./myapp --claude-md
  83. # All three at once
  84. codeindex symbols ./myapp --inline --claude-md
  85. # Re-generate when code changes
  86. codeindex symbols ./myapp --inline --claude-md
  87. ```
  88. **Why it matters:** Claude Code and other AI tools normally scan every file to find a function definition. With a symbol index, Claude can load one file, do an O(1) lookup, and open only the relevant file — cutting token usage 60–90% on symbol-location tasks.
  89. **CLAUDE.md injection** is opt-in because it increases base context size on every prompt. Use it when symbol lookups are frequent in your workflow; skip it for simple tasks where the overhead outweighs the benefit.
  90. ---
  91. ### `codeindex impact`
  92. ```bash
  93. codeindex impact FILE [--index PATH] [--out FILE] [--json] [--as-of REF]
  94. ```
  95. Shows the blast-radius impact for a specific file: direct dependents, transitive dependents, blast score, and risk level.
  96. ```
  97. Impact: src/auth.py
  98. Blast Score: 8.5 (2 direct · 7 transitive) [HIGH]
  99. Direct dependents (2)
  100. src/api.py
  101. src/middleware.py
  102. Transitive dependents (5 additional)
  103. src/main.py ← src/api.py
  104. src/app.py ← src/middleware.py
  105. ...
  106. Risk: HIGH — affects 7/42 files (16.7% of codebase)
  107. ```
  108. **Blast score formula:** `direct + (0.5 × transitive)`
  109. | Flag | Description |
  110. |------|-------------|
  111. | `--index PATH` | Path to `codeindex.json` (auto-discovered if omitted) |
  112. | `--out FILE` | Write a markdown report to this file |
  113. | `--json` | Output raw JSON |
  114. | `--as-of REF` | Compute blast radius at a historical commit/ref instead of HEAD |
  115. ---
  116. ### `codeindex search`
  117. ```bash
  118. codeindex search QUERY [--k N] [--as-of REF] [--db PATH] [--json]
  119. ```
  120. Hybrid semantic + keyword + graph symbol search. Finds relevant functions and classes without knowing their exact names.
  121. **Retrieval signals fused with Reciprocal Rank Fusion (RRF):**
  122. 1. **Semantic KNN** — embedding similarity (requires `codeindex[semantic]` + a configured endpoint)
  123. 2. **FTS5 keyword** — full-text search over symbol names, signatures, and docstrings
  124. 3. **Graph expansion** — structurally adjacent symbols from dependent/dependency files
  125. Degrades gracefully: if no embedding endpoint is configured, falls back to FTS + graph (no crash, no config needed).
  126. ```bash
  127. # Keyword + graph search (no embedding setup required)
  128. codeindex search "validate auth token"
  129. # Full semantic search (requires CODEINDEX_EMBEDDING_* env vars)
  130. CODEINDEX_EMBEDDING_ENDPOINT=http://localhost:11434 \
  131. CODEINDEX_EMBEDDING_MODEL=nomic-embed-text \
  132. CODEINDEX_EMBEDDING_DIMS=768 \
  133. codeindex search "validate auth token"
  134. # Historical search — symbols visible at a release tag
  135. codeindex search "token validation" --as-of v1.2.0
  136. ```
  137. | Flag | Default | Description |
  138. |------|---------|-------------|
  139. | `QUERY` | — | Natural-language or keyword query |
  140. | `--k N` | `10` | Number of results to return |
  141. | `--as-of REF` | HEAD | Restrict to symbols visible at this commit/ref |
  142. | `--db PATH` | auto-discovered | Path to `.codeindex/index.db` |
  143. | `--json` | off | Output raw JSON |
  144. ---
  145. ### `codeindex history`
  146. ```bash
  147. codeindex history [REPO_PATH] [--since REF] [--max-commits N] [--json]
  148. ```
  149. Backfills temporal graph data from git history — without any working-tree checkouts. Reads blobs via `git cat-file --batch` and stamps `first_seen_commit` / `last_seen_commit` on every file, edge, and symbol.
  150. Run this once after initial setup to enable `--as-of` queries across the full history.
  151. ```bash
  152. # Backfill up to 1000 commits (default)
  153. codeindex history .
  154. # Backfill only recent history
  155. codeindex history . --since v1.0.0 --max-commits 200
  156. ```
  157. | Flag | Default | Description |
  158. |------|---------|-------------|
  159. | `REPO_PATH` | `.` | Path to repo root |
  160. | `--since REF` | — | Only process commits after this date/ref |
  161. | `--max-commits N` | `1000` | Maximum commits to process |
  162. | `--json` | off | Output summary as JSON |
  163. ---
  164. ### `codeindex changed-since`
  165. ```bash
  166. codeindex changed-since REF [--repo PATH] [--db PATH] [--json]
  167. ```
  168. Lists files and dependency edges added or removed since a commit, branch, or tag.
  169. ```
  170. $ codeindex changed-since v1.2.0
  171. Changes since v1.2.0:
  172. Added files (2):
  173. + src/payments/stripe.py
  174. + src/payments/webhook.py
  175. Removed edges (1):
  176. - src/api.py → src/auth_v1.py [imports]
  177. ```
  178. | Flag | Default | Description |
  179. |------|---------|-------------|
  180. | `REF` | — | Commit hash, branch, or tag to compare against |
  181. | `--repo PATH` | `.` | Repo root (for git operations) |
  182. | `--db PATH` | auto-discovered | Path to `.codeindex/index.db` |
  183. | `--json` | off | Output raw JSON |
  184. ---
  185. ### `codeindex db`
  186. ```bash
  187. codeindex db status [--db PATH] [--json]
  188. codeindex db migrate [--db PATH]
  189. ```
  190. Manages the SQLite store at `<repo>/.codeindex/index.db`.
  191. ```
  192. $ codeindex db status
  193. schema_version : 2
  194. repo_root : /Users/alice/myapp
  195. last_indexed_commit : a3f2e1c8
  196. active_files : 142
  197. active_edges : 387
  198. active_symbols : 1204
  199. embedding_model : nomic-embed-text
  200. embedding_dims : 768
  201. vec_symbols : enabled
  202. ```
  203. `db migrate` applies any pending schema migrations automatically (also runs on every `codeindex analyze`).
  204. ---
  205. ### `codeindex serve`
  206. ```bash
  207. codeindex serve --viz [--repo PATH] [--port PORT] [--watch]
  208. codeindex serve --mcp
  209. ```
  210. `--viz` launches an interactive visualization UI in your browser (5 modes: 2D force graph, 3D network, dependency matrix, treemap, infrastructure graph).
  211. `--mcp` starts a stdio MCP server that exposes codeindex tools directly to Claude and other MCP clients.
  212. **MCP tools:**
  213. | Tool | Description |
  214. |------|-------------|
  215. | `analyze_repo` | Build or refresh the dependency index |
  216. | `get_impact` | Blast-radius report for a file |
  217. | `get_dependencies` | imports + imported-by for a file |
  218. | `get_high_blast_files` | All files above a blast score threshold |
  219. | `build_symbol_index` | Build or refresh the symbol index |
  220. | `lookup_symbol` | Find where any function/class/type is defined (file + line) |
  221. | `semantic_search` | Hybrid semantic + keyword + graph symbol search; degrades gracefully without embeddings |
  222. | `temporal_impact` | Blast-radius at a historical commit/ref (`as_of` parameter) |
  223. | `graph_query` | k-hop dependency neighborhood of a file (`dependents`/`dependencies`/`both`) |
  224. | `changed_since` | Files and edges added or removed since a commit/ref |
  225. **Claude Code MCP config** (`.claude/settings.json`):
  226. ```json
  227. {
  228. "mcpServers": {
  229. "codeindex": {
  230. "command": "codeindex",
  231. "args": ["serve", "--mcp"]
  232. }
  233. }
  234. }
  235. ```
  236. ---
  237. ### `codeindex lookup`
  238. ```bash
  239. codeindex lookup SYMBOL [--index PATH] [--json]
  240. ```
  241. Finds where a function, class, struct, or other symbol is defined. Queries the SQLite DB (same source as `search`), falling back to `symbolindex.json` if no DB is present. Prints 5 lines of source context around the definition.
  242. ```
  243. $ codeindex lookup compute_blast_radius
  244. codeindex/impact.py:6 compute_blast_radius (function)
  245. > 6 | def compute_blast_radius(nodes: list[dict], links: list[dict]) -> dict[str, dict]:
  246. 7 | """..."""
  247. 8 | ...
  248. $ codeindex lookup AuthService
  249. src/auth.py:44 AuthService (class) methods: login, logout, refresh
  250. > 44 | class AuthService:
  251. 45 | def login(self, ...):
  252. ```
  253. If a symbol isn't found, it's likely a third-party import — only symbols defined in the repo are indexed.
  254. | Flag | Description |
  255. |------|-------------|
  256. | `--index PATH` | Path to `symbolindex.json` fallback (auto-discovered if omitted) |
  257. | `--json` | Output raw JSON |
  258. ---
  259. ### `codeindex dependencies`
  260. ```bash
  261. codeindex dependencies FILE [--index PATH] [--json]
  262. ```
  263. Shows what a file imports and what imports it, plus its blast score.
  264. ```
  265. $ codeindex dependencies src/auth.py
  266. File: src/auth.py (blast score: 8.5)
  267. Imports (3):
  268. src/db.py
  269. src/config.py
  270. src/utils.py
  271. Imported by (2):
  272. src/api.py
  273. src/middleware.py
  274. ```
  275. | Flag | Description |
  276. |------|-------------|
  277. | `--index PATH` | Path to `codeindex.json` (auto-discovered if omitted) |
  278. | `--json` | Output raw JSON |
  279. ---
  280. ### `codeindex high-blast`
  281. ```bash
  282. codeindex high-blast [--threshold N] [--index PATH] [--json]
  283. ```
  284. Lists all files whose blast score exceeds the threshold, sorted by score descending. Useful for identifying the riskiest files before a refactor.
  285. ```
  286. $ codeindex high-blast --threshold 5
  287. Files with blast score ≥ 5.0 (3 found)
  288. 13.0 src/db.py (12d / 2t)
  289. 8.5 src/auth.py (3d / 7t)
  290. 5.5 src/config.py (5d / 1t)
  291. ```
  292. `d` = direct dependents · `t` = transitive dependents
  293. | Flag | Default | Description |
  294. |------|---------|-------------|
  295. | `--threshold N` | `5` | Minimum blast score to include |
  296. | `--index PATH` | auto-discovered | Path to `codeindex.json` |
  297. | `--json` | off | Output raw JSON |
  298. ---
  299. ### `codeindex symbol-blast`
  300. ```bash
  301. codeindex symbol-blast FILE [--json]
  302. ```
  303. Per-export blast radius for a file. Lists every exported symbol with the count and exact file paths of importers that reference it by name. Useful when a file exports many symbols and you only need to touch one — lets you confirm the others are safe.
  304. ```
  305. $ codeindex symbol-blast lib/db/schema.ts
  306. Symbol-level blast radius: lib/db/schema.ts
  307. 5 exported symbol(s), 12 importer(s)
  308. userSchema (const, line 8) → 8 user(s)
  309. app/api/users/route.ts
  310. app/api/profile/route.ts
  311. ...
  312. legacySchema (const, line 42) → 1 user(s)
  313. scripts/migrate.ts
  314. sessionSchema (const, line 67) → 3 user(s)
  315. ...
  316. ```
  317. `userSchema` touches 8 routes; `legacySchema` touches only 1 — safe to change in isolation.
  318. | Flag | Description |
  319. |------|-------------|
  320. | `FILE` | Repo-relative path to the file (e.g. `lib/db/schema.ts`) |
  321. | `--json` | Output raw JSON with full `used_by` arrays per symbol |
  322. ---
  323. ### `codeindex install-hook`
  324. ```bash
  325. codeindex install-hook [--repo PATH] [--threshold N] [--strict] [--remove]
  326. ```
  327. Installs a git pre-commit hook that warns when staged files exceed the blast score threshold.
  328. | Flag | Default | Description |
  329. |------|---------|-------------|
  330. | `--threshold N` | `10` | Blast score above which to warn |
  331. | `--strict` | off | Block the commit instead of just warning |
  332. | `--remove` | — | Uninstall the hook |
  333. ---
  334. ## Using codeindex in another repo with Claude
  335. Three workflows, ordered by automation level.
  336. ### Workflow 1 — MCP server (recommended for active coding)
  337. Claude gets symbol lookup, dependency, and impact tools it calls automatically. No extra prompting needed.
  338. **One-time setup:**
  339. ```bash
  340. cd /your/other/repo
  341. codeindex analyze .
  342. codeindex symbols .
  343. ```
  344. Register the MCP server with Claude Code using `claude mcp add`. Use `--scope project` to limit it to this repo, or `--scope global` to use it everywhere:
  345. ```bash
  346. # Project-scoped (recommended — stored in .claude/settings.json)
  347. claude mcp add --scope project codeindex -- /path/to/codeindex serve --mcp
  348. # Global (available in all repos)
  349. claude mcp add --scope global codeindex -- /path/to/codeindex serve --mcp
  350. ```
  351. Find the full path to your codeindex binary with `which codeindex`, then substitute it above.
  352. ```bash
  353. # Example with conda install
  354. claude mcp add --scope project codeindex -- /opt/homebrew/Caskroom/miniforge/base/bin/codeindex serve --mcp
  355. ```
  356. Verify it registered:
  357. ```bash
  358. claude mcp list
  359. ```
  360. > **Note:** Do not use `"command": "codeindex"` with a bare name — Claude Code does not inherit your shell PATH, so the binary won't be found unless you use the absolute path.
  361. Claude now has all 10 MCP tools available in every session. When it needs to find `processPayment`, it calls `lookup_symbol("processPayment")` and gets `src/billing.py:142` back in one shot — no file scanning. When it needs to find code that validates auth tokens without knowing the exact name, it calls `semantic_search("validate auth token")`.
  362. **Keep the index fresh:**
  363. ```bash
  364. # Auto-rebuild on file changes (leave running in a terminal)
  365. codeindex symbols . --watch
  366. ```
  367. ---
  368. ### Workflow 2 — CLAUDE.md injection (best for repos you revisit often)
  369. Symbol table is embedded in `CLAUDE.md` so it loads into every session automatically — no tool call needed at all.
  370. ```bash
  371. cd /your/other/repo
  372. codeindex symbols . --claude-md
  373. ```
  374. This upserts a `symbolindex` code fence into `CLAUDE.md`. Every Claude Code session in that repo loads it at startup. Claude can answer "where is `X` defined?" from context alone with zero tool calls.
  375. **Tradeoff:** adds ~500–2000 tokens to every prompt depending on repo size. Worth it for repos where symbol lookups are frequent; skip it for repos where you mostly write new code.
  376. **Keep it fresh:**
  377. ```bash
  378. # Re-run after significant refactors
  379. codeindex analyze . && codeindex symbols . --claude-md
  380. ```
  381. ---
  382. ### Workflow 3 — Hybrid (large repos)
  383. For large repos where the `--claude-md` section would be too large, use the MCP server for lookups and add a short hint to `CLAUDE.md` so Claude reaches for the tool first:
  384. ```bash
  385. codeindex analyze .
  386. codeindex symbols .
  387. ```
  388. Then add to `CLAUDE.md`:
  389. ```markdown
  390. ## Codeindex
  391. Symbol index: `symbolindex.json` — use the `lookup_symbol` MCP tool before grepping for any function or class.
  392. Dependency index: `codeindex.json` — use `get_impact` before modifying high-blast files.
  393. ```
  394. This costs almost no tokens but primes Claude to use the index rather than defaulting to grep.
  395. ---
  396. ### CLI quick reference for human use
  397. The same data available via MCP is also accessible directly from the terminal:
  398. ```bash
  399. # Find where a symbol is defined (shows code snippet)
  400. codeindex lookup MyClassName
  401. codeindex lookup process_payment --json
  402. # Show what a file imports and what depends on it
  403. codeindex dependencies src/auth.py
  404. # List the riskiest files to change
  405. codeindex high-blast --threshold 5
  406. # Blast-radius report before touching a file
  407. codeindex impact src/auth.py
  408. # Per-export blast radius — which importers use each exported symbol
  409. codeindex symbol-blast lib/db/schema.ts
  410. ```
  411. ---
  412. ### Which workflow to pick
  413. | Situation | Workflow |
  414. |-----------|----------|
  415. | Daily driver repo, active feature work | MCP server |
  416. | Medium repo, frequent symbol lookups | CLAUDE.md injection |
  417. | Large repo (1000+ files) | MCP server + short CLAUDE.md hint |
  418. | Quick one-off in an unfamiliar repo | `codeindex symbols . --claude-md`, delete after |
  419. | Terminal / scripting use | CLI commands (`lookup`, `dependencies`, `high-blast`) |
  420. ---
  421. ## Supported Languages
  422. | Language | Dependency analysis | Symbol extraction |
  423. |----------|--------------------|--------------------|
  424. | Python | AST imports, type detection | Functions, classes, methods (AST-precise) |
  425. | JavaScript / TypeScript | ES modules, `require()`, framework detection | Exported functions, classes, types, enums, consts |
  426. | Vue | SFC `<script>` imports | Exported symbols from `<script>` block |
  427. | Go | Package-level nodes, `import` blocks | Functions, structs, interfaces (exported flag) |
  428. | Ruby | `require`, `require_relative`, `autoload` | Classes, modules, methods |
  429. | Rust | `mod`, `use crate::` | `pub fn`, structs, enums, traits |
  430. | Java / Kotlin | FQN imports, wildcard imports | Classes, interfaces, methods |
  431. | PHP | PSR-4 namespace resolution | Classes, interfaces, functions |
  432. | CSS / SCSS / Less | `@import`, `@use`, `@forward` | — |
  433. | Docker | Services, `depends_on` edges | — |
  434. | CI/CD | GitHub Actions + GitLab CI jobs, `needs:` edges | — |
  435. | SQL / Prisma | Tables/models, foreign key edges | — |
  436. ---
  437. ## Output schemas
  438. ### `codeindex.json`
  439. ```json
  440. {
  441. "meta": {
  442. "root": "myapp/",
  443. "total_files": 60,
  444. "total_loc": 4085,
  445. "languages": ["python", "javascript"]
  446. },
  447. "nodes": [
  448. {
  449. "id": "src/auth.py",
  450. "type": "module",
  451. "language": "python",
  452. "layer": "backend",
  453. "loc": 142,
  454. "imports": ["src/db.py"],
  455. "imported_by": ["src/api.py", "src/middleware.py"],
  456. "direct_dependents": 2,
  457. "transitive_dependents": 7,
  458. "blast_score": 5.5,
  459. "symbols": [
  460. { "name": "verify_token", "line": 18, "kind": "function", "exported": true },
  461. { "name": "AuthService", "line": 44, "kind": "class", "exported": true,
  462. "methods": ["login", "logout", "refresh"] }
  463. ]
  464. }
  465. ],
  466. "links": [
  467. { "source": "src/api.py", "target": "src/auth.py", "weight": 1, "kind": "imports" }
  468. ]
  469. }
  470. ```
  471. The `symbols` field is only present when `codeindex symbols --inline` has been run.
  472. ---
  473. ### `symbolindex.json`
  474. ```json
  475. {
  476. "meta": {
  477. "generated": "2026-05-21",
  478. "repo": "myapp/",
  479. "total_symbols": 312
  480. },
  481. "symbols": {
  482. "verify_token": [
  483. {
  484. "file": "src/auth.py",
  485. "line": 18,
  486. "kind": "function",
  487. "exported": true,
  488. "doc": "Verify a JWT and return the decoded payload."
  489. }
  490. ],
  491. "AuthService": [
  492. {
  493. "file": "src/auth.py",
  494. "line": 44,
  495. "kind": "class",
  496. "exported": true,
  497. "methods": ["login", "logout", "refresh"]
  498. }
  499. ]
  500. },
  501. "file_symbols": {
  502. "src/auth.py": [
  503. { "name": "verify_token", "line": 18, "kind": "function", "exported": true },
  504. { "name": "AuthService", "line": 44, "kind": "class", "exported": true,
  505. "methods": ["login", "logout", "refresh"] }
  506. ]
  507. }
  508. }
  509. ```
  510. **Lookup patterns:**
  511. - *"Where is `verify_token` defined?"* → `symbols["verify_token"][0].file` + `.line` — O(1)
  512. - *"What symbols live in `src/auth.py`?"* → `file_symbols["src/auth.py"]` — O(1)
  513. - *"What's the blast radius of changing `verify_token`?"* → cross-reference `codeindex.json` via the file
  514. ---
  515. ### CLAUDE.md symbol section
  516. When `--claude-md` is used, a compact section is upserted into `CLAUDE.md` bounded by HTML comment markers so re-runs update in place:
  517. ```
  518. <!-- codeindex-symbols-start -->
  519. ## Symbol Index
  520. _Generated by codeindex. Update: `codeindex symbols --claude-md`_
  521. ```symbolindex
  522. src/auth.py: verify_token:fn:18 AuthService:cls:44[login,logout,refresh]
  523. src/db.py: connect:fn:12 query:fn:28 close:fn:55
  524. ```
  525. <!-- codeindex-symbols-end -->
  526. ```
  527. Format per symbol: `name:kind_abbr:line[methods...]`
  528. Kind abbreviations: `fn` function · `cls` class · `st` struct · `en` enum · `tr` trait · `if` interface · `ty` type · `co` const
  529. ---
  530. ## AI workflow comparison
  531. | Task | Without codeindex | With symbolindex.json |
  532. |------|-------------------|----------------------|
  533. | Find where `process_payment` is defined | Grep / scan ~200 files | Load 1 file, O(1) lookup |
  534. | Understand blast radius of a change | Manual tracing | `codeindex impact <file>` |
  535. | Load only relevant context | Full repo scan | File + line from symbol map |
  536. | Estimated token savings | baseline | **60–90% on symbol tasks** |
  537. ---
  538. ## Optional dependencies
  539. | Package | Purpose | Install |
  540. |---------|---------|---------|
  541. | `sqlite-vec` | Semantic vector search in `codeindex search` and `semantic_search` MCP tool | `pip install 'codeindex[semantic]'` |
  542. | `watchdog` | `--watch` file change detection | `pip install 'codeindex[watch]'` |
  543. | `PyYAML` | Better Docker Compose / CI YAML parsing | `pip install 'codeindex[yaml]'` |
  544. | `tomli` | Rust `Cargo.toml` on Python < 3.11 | `pip install 'codeindex[toml]'` |
  545. ### Semantic search configuration
  546. Semantic search requires a self-hosted embedding endpoint (Ollama, LM Studio, llama.cpp server, or any OpenAI-compatible `/v1/embeddings` API) and the `sqlite-vec` extension.
  547. ```bash
  548. pip install 'codeindex[semantic]'
  549. # Set env vars (add to your shell profile or .env)
  550. export CODEINDEX_EMBEDDING_ENDPOINT=http://localhost:11434
  551. export CODEINDEX_EMBEDDING_MODEL=nomic-embed-text
  552. export CODEINDEX_EMBEDDING_DIMS=768
  553. # Re-index to generate embeddings
  554. codeindex analyze ./myapp
  555. # Search
  556. codeindex search "validate JWT token"
  557. ```
  558. Without these env vars, `codeindex search` and the `semantic_search` MCP tool fall back to FTS5 keyword + graph search — no crash, no config required.
  559. ---
  560. ## Requirements
  561. - Python 3.9+
  562. - A modern browser (for `--viz` mode)
  563. ---
  564. ## License
  565. Apache 2.0 — free to use and build on; attribution required in derivative works and documentation. Copyright 2026 David Scheiderman.

Ratings and comments

Sign in to rate this skill.

Sign in

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