Skip to content
Back to search

SymDex

Repo-local codebase oracle for AI coding agents. Exact symbol search, semantic search, routes, and call graphs across 16 languages, from Python and Go to Dart and Swift.

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/husnainpk--symdex/badge.svg)](/listings/husnainpk--symdex)

HTML

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

# Install the lean core
pip install symdex
# or
uv tool install symdex

# Index a project
symdex index ./myproject --repo myproject

# Search by symbol name
symdex search "validate_email" --repo myproject

# Search by literal text
symdex text "JWT" --repo myproject

# Add local semantic search only when you want embeddings
pip install "symdex[local]"

# Search by intent
symdex semantic "check email format" --repo myproject

# Build a token-budgeted context pack for an agent
symdex pack "how checkout auth works" --repo myproject --budget 6000

# Show HTTP routes
symdex routes myproject -m POST

# Start the MCP server
symdex serve

Notes: - If you omit `--repo` on `symdex index` or `symdex watch`, SymDex auto-generates a stable repo id from the current git branch and worktree path hash. - After indexing, SymDex prints a code summary. - After successful search commands, SymDex prints a one-line ROI footer with approximate token savings. - MCP search tools also return `roi_agent_hint`, so agents can fold the savings into their user-facing response instead of burying it in logs. - When a newer PyPI release exists, normal CLI commands print exact upgrade commands for `pip`, `uv tool`, and `uvx`. - Set `SYMDEX_STATE_DIR=.symdex` on first index to keep repo databases, `registry.db`, and `registry.json` inside the current workspace. After that, commands run from the workspace auto-discover the local state. - `--state-dir` can be passed either globally or after the subcommand, for example `symdex --state-dir .symdex repos` or `symdex repos --state-dir .symdex`. - Canonical CLI commands are `index` and `repos`. Shell compatibility aliases also accept MCP-shaped names like `index-folder`, `index-repo`, and `list-repos`. - Semantic search requires stored embeddings. If a repo was indexed before the backend you want was enabled, re-index it with `symdex index`, `symdex index --lazy`, or `symdex watch --embed`.

Add to your agent config:

{
  "mcpServers": {
    "symdex": {
      "command": "uvx",
      "args": ["symdex", "serve"]
    }
  }
}

HTTP mode:

{
  "mcpServers": {
    "symdex": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

---

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

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

  1. <div align="center">
  2. <p>
  3. <img src="docs/images/symdex-social-banner.jpg" alt="SymDex social banner showing symbolic indexing for agentic AI systems with entities, relations, context, a symbolic index, retrieval engine, and storage layer" width="100%" />
  4. </p>
  5. # SymDex
  6. **Symbolic indexing for agentic AI systems.**
  7. *SymDex turns a checked-out repository into a local symbolic index of code structure, routes, relations, docs, tests, and context so AI coding agents can reason, retrieve, and act without reading whole files first.*
  8. <br>
  9. [![PyPI](https://img.shields.io/pypi/v/symdex?style=for-the-badge&color=3572A5&label=PyPI)](https://pypi.org/project/symdex/)
  10. [![Downloads](https://img.shields.io/pypi/dm/symdex?style=for-the-badge&color=00ADD8&label=installs%2Fmonth)](https://pypi.org/project/symdex/)
  11. [![Python](https://img.shields.io/pypi/pyversions/symdex?style=for-the-badge&color=f1e05a&labelColor=333)](https://pypi.org/project/symdex/)
  12. [![License](https://img.shields.io/badge/license-MIT-22c55e?style=for-the-badge)](https://github.com/husnainpk/symdex/blob/main/LICENSE)
  13. [![Stars](https://img.shields.io/github/stars/husnainpk/symdex?style=for-the-badge&color=f59e0b)](https://github.com/husnainpk/symdex/stargazers)
  14. <br>
  15. [![Cursor](https://img.shields.io/badge/Cursor-black?style=flat-square)](https://cursor.sh)
  16. [![Codex](https://img.shields.io/badge/Codex_CLI-black?style=flat-square&logo=openai)](https://github.com/openai/codex)
  17. [![Gemini](https://img.shields.io/badge/Gemini_CLI-black?style=flat-square&logo=google)](https://github.com/google-gemini/gemini-cli)
  18. [![Copilot](https://img.shields.io/badge/GitHub_Copilot-black?style=flat-square&logo=github)](https://github.com/features/copilot)
  19. [![Windsurf](https://img.shields.io/badge/Windsurf-black?style=flat-square)](https://codeium.com/windsurf)
  20. [![Roo](https://img.shields.io/badge/Roo-black?style=flat-square)](https://roocode.com)
  21. [![Kilo](https://img.shields.io/badge/Kilo_Code-black?style=flat-square)](https://kilocode.ai)
  22. <br>
  23. <h2 align="center">From whole-file browsing to exact repo retrieval</h2>
  24. <p align="center"><strong>Exact symbols, routes, callers, callees, file outlines, semantic matches, and token-budgeted context packs for coding agents.</strong></p>
  25. ```bash
  26. # Install the lean core
  27. pip install symdex
  28. # Add local semantic search when you want the sentence-transformers backend
  29. pip install "symdex[local]"
  30. # Or install the local semantic backend as an isolated CLI tool
  31. uv tool install "symdex[local]"
  32. # Or run without installing
  33. uvx symdex --help
  34. # Upgrade an existing install
  35. py -m pip install -U symdex
  36. uv tool upgrade symdex
  37. uvx symdex@latest --help
  38. # Install the SymDex agent skill globally for supported agents
  39. npx skills add https://github.com/husnainpk/SymDex --skill symdex-code-search --yes --global
  40. ```
  41. </div>
  42. ---
  43. ## What SymDex Does
  44. SymDex is a repo-local symbolic indexing engine for AI coding agents. It maps a project into exact symbols, files, routes, relations, docs, tests, and retrieval context, then exposes that map through CLI commands and MCP tools.
  45. AI coding agents are useful until they have to rediscover your repo from scratch. They open whole files, grep broad patterns, miss the route handler, read the same utility twice, and spend thousands of tokens just getting oriented.
  46. SymDex gives agents a repo-local retrieval layer before they start reading code. You keep the index on your machine, choose the embedding backend only when semantic search is useful, and expose the same project map through both CLI commands and MCP tools.
  47. It indexes your project into a small local SQLite knowledge base with:
  48. - exact symbols and byte offsets
  49. - file outlines and repo summaries
  50. - literal text search
  51. - optional semantic search
  52. - callers, callees, and circular dependency checks
  53. - extracted HTTP routes
  54. - query-driven context packs that assemble small evidence bundles from symbols, routes, docs, tests, text, graph neighbors, and optional semantic matches
  55. - retrieval quality metadata for freshness, confidence, parser mode, generated paths, and embedding availability
  56. - a registry for one repo, many repos, or many worktrees
  57. Then agents can ask for the narrow slice they need: the function, route, caller chain, file outline, intent match, or a token-budgeted context pack for a broader feature question. That means less blind browsing, less context waste, and responses that can explain how much token budget SymDex saved.
  58. SymDex is local-first. Base `symdex` keeps symbol, text, route, graph, and MCP features lean. Install `symdex[local]` only when you want local semantic embeddings, or point the hosted backend at Voyage, OpenAI-compatible services, Gemini, or a compatible proxy when you want remote embeddings.
  59. Current product capabilities in this checkout:
  60. - current release `0.1.26`; latest public tag `v0.1.26`
  61. - 21 MCP tools across indexing, search, context packs, outlines, routes, stats, graphs, cache invalidation, and stale-index cleanup
  62. - 21 language surfaces, including HTML, CSS, Shell, Svelte, Markdown headings, and supported fenced code blocks
  63. - Android, Flutter, and iOS coverage through Kotlin, Dart, and Swift parser targets
  64. - route extraction across Python, JavaScript/TypeScript, Spring/Kotlin, Laravel, Gin-style Go, ASP.NET, Rails/Sinatra, Phoenix, and Actix
  65. - one-line CLI token-savings footers after successful search commands
  66. - MCP `roi`, `roi_summary`, and `roi_agent_hint` fields so agents can mention savings in their final response
  67. - MCP and CLI JSON `quality` fields so agents can judge confidence, index freshness, parser mode, generated paths, and embedding availability before reasoning from a result
  68. - `symdex pack` and MCP `build_context_pack` for query-shaped, token-budgeted evidence bundles
  69. - semantic backends for local `sentence-transformers`, Voyage, OpenAI-compatible `/embeddings`, and Gemini Embedding
  70. - `SYMDEX_EMBED_RPM` request pacing for hosted embedding providers
  71. - `symdex index --lazy` for fast foreground structural indexing while embeddings build in a background watcher
  72. - low-memory `symdex watch` by default: structural refresh without loading embedding models unless `--embed` is passed
  73. - duplicate watcher protection, idle auto-exit, and state-aware watcher metadata
  74. - workspace-local `./.symdex` state for Docker, portable workspaces, and teams that do not want indexes hidden in home directories
  75. - upgrade notices with exact `pip`, `uv tool`, and `uvx` commands when a newer release exists
  76. ---
  77. ## SymDex Skill For Agents
  78. Install the SymDex code-search skill when you want supported agents to use SymDex before broad file browsing:
  79. ```bash
  80. npx skills add https://github.com/husnainpk/SymDex --skill symdex-code-search --yes --global
  81. ```
  82. If you want the interactive installer instead, omit `--yes --global`.
  83. The skill tells agents to:
  84. - check repo and index readiness first
  85. - search with SymDex before broad Read/Grep/Glob discovery
  86. - prefer symbol-level and outline-level retrieval over full-file reads
  87. - use callers, callees, routes, repo stats, and semantic search when those are the better fit
  88. - use context packs for broader "how does this feature work?" questions before many separate searches
  89. - fall back clearly when SymDex is unavailable or when semantic embeddings have not been built
  90. - keep the workflow centered on lower-token code retrieval instead of broad file reads
  91. The skill lives in this repo at `skills/symdex-code-search/SKILL.md` and follows the standard `skills/<name>/SKILL.md` layout.
  92. Installing through the `skills` CLI uses the same public path that skills.sh indexes.
  93. ---
  94. ## 60-second quickstart
  95. ```bash
  96. # Install the lean core
  97. pip install symdex
  98. # or
  99. uv tool install symdex
  100. # Index a project
  101. symdex index ./myproject --repo myproject
  102. # Search by symbol name
  103. symdex search "validate_email" --repo myproject
  104. # Search by literal text
  105. symdex text "JWT" --repo myproject
  106. # Add local semantic search only when you want embeddings
  107. pip install "symdex[local]"
  108. # Search by intent
  109. symdex semantic "check email format" --repo myproject
  110. # Build a token-budgeted context pack for an agent
  111. symdex pack "how checkout auth works" --repo myproject --budget 6000
  112. # Show HTTP routes
  113. symdex routes myproject -m POST
  114. # Start the MCP server
  115. symdex serve
  116. ```
  117. Notes:
  118. - If you omit `--repo` on `symdex index` or `symdex watch`, SymDex auto-generates a stable repo id from the current git branch and worktree path hash.
  119. - After indexing, SymDex prints a code summary.
  120. - After successful search commands, SymDex prints a one-line ROI footer with approximate token savings.
  121. - MCP search tools also return `roi_agent_hint`, so agents can fold the savings into their user-facing response instead of burying it in logs.
  122. - When a newer PyPI release exists, normal CLI commands print exact upgrade commands for `pip`, `uv tool`, and `uvx`.
  123. - Set `SYMDEX_STATE_DIR=.symdex` on first index to keep repo databases, `registry.db`, and `registry.json` inside the current workspace. After that, commands run from the workspace auto-discover the local state.
  124. - `--state-dir` can be passed either globally or after the subcommand, for example `symdex --state-dir .symdex repos` or `symdex repos --state-dir .symdex`.
  125. - Canonical CLI commands are `index` and `repos`. Shell compatibility aliases also accept MCP-shaped names like `index-folder`, `index-repo`, and `list-repos`.
  126. - Semantic search requires stored embeddings. If a repo was indexed before the backend you want was enabled, re-index it with `symdex index`, `symdex index --lazy`, or `symdex watch --embed`.
  127. Add to your agent config:
  128. ```json
  129. {
  130. "mcpServers": {
  131. "symdex": {
  132. "command": "uvx",
  133. "args": ["symdex", "serve"]
  134. }
  135. }
  136. }
  137. ```
  138. HTTP mode:
  139. ```json
  140. {
  141. "mcpServers": {
  142. "symdex": {
  143. "url": "http://localhost:8080/mcp"
  144. }
  145. }
  146. }
  147. ```
  148. ---
  149. ## Workspace-local state and Docker
  150. SymDex defaults to `~/.symdex` and also supports a workspace-local state directory for portable and containerized workflows.
  151. Use it like this on first setup:
  152. ```bash
  153. SYMDEX_STATE_DIR=.symdex symdex index ./myproject --repo myproject
  154. ```
  155. That creates:
  156. - `./.symdex/<repo>.db`
  157. - `./.symdex/registry.db`
  158. - `./.symdex/registry.json`
  159. `registry.json` is the human-readable manifest. In workspace-local mode it stores relative `root_path` and `db_path` values, so you can inspect what is indexed without opening SQLite.
  160. After the local state exists, SymDex auto-discovers it from the current workspace or any nested subdirectory.
  161. ---
  162. ## What you get
  163. <p align="center">
  164. <img src="docs/images/what-you-get-grid.png" alt="SymDex feature grid showing core capabilities including semantic search, byte-precise extraction, call graph, routes, cross-repo registry, watch mode, and CLI plus MCP tools" width="100%" />
  165. </p>
  166. | Feature | Details |
  167. |---|---|
  168. | Symbol search | Find functions, classes, and methods with exact byte offsets |
  169. | Semantic search | Find code by intent instead of exact name |
  170. | Text search | Search indexed files by literal text across the repo |
  171. | Byte-precise retrieval | Read only the symbol span you need |
  172. | File outline | List symbols in a file without transferring the whole file |
  173. | Repo outline | Get a directory tree plus repo summary through MCP |
  174. | Call graph | Trace callers, callees, and circular dependencies |
  175. | HTTP routes | Extract Flask, FastAPI, Django, Express, Spring/Kotlin, Laravel, Gin-style Go, ASP.NET, Rails/Sinatra, Phoenix, and Actix routes |
  176. | Context packs | Build token-budgeted evidence bundles from symbols, routes, text, docs, tests, graph neighbors, and optional semantic matches |
  177. | Markdown-aware docs | Index Markdown headings and supported fenced code blocks for SDK docs, specs, repo docs, and design notes |
  178. | Auto-watch | Re-index on change, avoid duplicate watchers, stay low-memory by default, and auto-exit after idle time |
  179. | Cross-repo registry | Manage multiple indexed repos from one local registry |
  180. | Workspace-local state | Keep repo databases, `registry.json`, and watcher metadata inside `./.symdex` for Docker and portable workspaces |
  181. | Search ROI footer | One-line approximate token savings after successful search commands |
  182. | Agent ROI hint | MCP tools return `roi_agent_hint` so agents can mention savings naturally in their replies |
  183. | Retrieval quality metadata | MCP and CLI JSON outputs expose confidence, freshness, parser mode, language surface, generated-file hints, and embedding availability |
  184. | Code summary | Files, Lines of Code, symbols, routes, skipped files, and languages after indexing |
  185. | Optional embedding backends | Use local embeddings, Voyage, OpenAI-compatible `/embeddings`, Gemini, or a compatible proxy only when needed |
  186. ---
  187. ## Where SymDex Fits
  188. AI codebase tools now split into a few strong categories: enterprise code search, IDE-native assistants, LSP-backed agent toolkits, repo-map systems, and whole-repo prompt packers. SymDex sits in a narrower but useful slot: a local-first retrieval layer that combines exact symbols, text search, optional semantic search, query-driven context packs, HTTP routes, callers, callees, file outlines, repo outlines, Markdown/fenced-code indexing, repo stats, token-savings hints, retrieval quality metadata, CLI access, and MCP access without requiring an editor session or hosted index.
  189. That makes SymDex strongest when an agent needs a portable codebase map it can query before reading files.
  190. | Need | Common fit | Where SymDex fits |
  191. |---|---|---|
  192. | Enterprise code search across many hosted repos | Sourcegraph-style code search | SymDex is smaller and local-first; it focuses on agent retrieval from checked-out worktrees rather than enterprise code search operations |
  193. | IDE-native codebase chat and autocomplete | Cursor, Continue, Cody, and similar editor assistants | SymDex is editor-agnostic; agents can use the same repo index from a terminal, stdio MCP, or HTTP MCP client |
  194. | IDE-grade semantic retrieval and refactoring | LSP-backed tools and Serena-style agent toolkits | SymDex does not try to be a refactoring engine; it focuses on retrieval primitives agents need before deciding what to edit |
  195. | Whole-repo context packaging | Repomix and other prompt-packing tools | SymDex builds query-driven context packs from indexed evidence instead of packing the whole repository into one prompt artifact |
  196. | Agent repo maps for coding sessions | Aider-style repository maps | SymDex exposes queryable indexes, token-budgeted context packs, routes, call graphs, Markdown headings, semantic search, ROI hints, and retrieval quality metadata rather than only a condensed map |
  197. | Lightweight local retrieval across code and docs | SymDex | SymDex's edge is the combined surface: CLI + MCP, SQLite indexes, 21 language surfaces, context packs, route extraction, call graphs, Markdown/MDX support, retrieval quality signals, optional embeddings, low-memory watch, and workspace-local state |
  198. Use a language server when you need deep type-system reasoning or editor-native refactors. Use an enterprise code search platform when you need organization-wide search, permissions, and code monitoring. Use a prompt packer when you want to hand an entire repo snapshot to a model. Use SymDex when you want an AI coding agent to ask precise repo-local questions before it spends tokens reading files.
  199. ---
  200. ## CLI reference
  201. ```bash
  202. # Indexing and maintenance
  203. symdex index ./myproject --repo myproject # Index with an explicit repo id
  204. symdex index ./myproject # Auto-name from git branch + path hash
  205. symdex index ./myproject --repo myproject --no-embed # Skip semantic embedding work
  206. symdex index ./myproject --repo myproject --lazy # Index code now, embed in a background watcher
  207. symdex watch ./myproject --repo myproject # Keep an index fresh without loading embedding models
  208. symdex watch ./myproject --repo myproject --embed # Also refresh semantic embeddings on change
  209. symdex invalidate --repo myproject # Force re-index of a repo
  210. symdex invalidate --repo myproject --file app.py
  211. symdex gc # Remove stale index databases
  212. symdex repos # List indexed repos
  213. # Search
  214. symdex search "validate_email" --repo myproject
  215. symdex search "validate_email" # Search across all indexed repos
  216. symdex find validate_email --repo myproject # Exact lookup
  217. symdex text "JWT" --repo myproject
  218. symdex semantic "check auth token" --repo myproject
  219. symdex pack "how auth token refresh works" --repo myproject --budget 6000
  220. symdex pack "document checkout API" --repo myproject --include routes,docs,tests --format json
  221. # Navigation
  222. symdex outline auth/utils.py --repo myproject
  223. symdex callers validate_email --repo myproject
  224. symdex callees validate_email --repo myproject
  225. symdex routes myproject
  226. symdex routes myproject --method POST
  227. symdex routes myproject --path /api
  228. # Server
  229. symdex serve
  230. symdex serve --port 8080
  231. ```
  232. MCP currently exposes additional repo-tree and repo-stats views that are not surfaced as dedicated CLI commands: `get_file_tree`, `get_repo_outline`, `get_index_status`, and `get_repo_stats`.
  233. ---
  234. ## MCP tools
  235. SymDex currently exposes 21 MCP tools:
  236. | Tool | Purpose |
  237. |---|---|
  238. | `index_folder` | Index a local folder and return indexing statistics |
  239. | `index_repo` | Index a repo and register it in the central registry |
  240. | `search_symbols` | Find functions, classes, and methods by name |
  241. | `semantic_search` | Find symbols by meaning using embedding similarity |
  242. | `search_text` | Search indexed files by text and return matching lines |
  243. | `build_context_pack` | Build a token-budgeted evidence bundle for an agent query |
  244. | `get_symbol` | Read one symbol by byte offsets |
  245. | `get_symbols` | Bulk exact-name symbol lookup |
  246. | `get_file_outline` | List symbols in a single file |
  247. | `get_file_tree` | Return a directory tree without file contents |
  248. | `get_repo_outline` | Return a repo tree plus summary stats |
  249. | `get_callers` | Return symbols that call a named function |
  250. | `get_callees` | Return symbols called by a named function |
  251. | `search_routes` | Query extracted HTTP routes |
  252. | `get_index_status` | Return symbol count, file count, Lines of Code, staleness, and watcher state |
  253. | `get_repo_stats` | Return repo metrics such as language mix, fan-in, fan-out, and circular dependency count |
  254. | `get_graph_diagram` | Generate a Mermaid call graph |
  255. | `find_circular_deps` | Detect circular dependencies |
  256. | `list_repos` | List all indexed repos |
  257. | `invalidate_cache` | Force re-index on next use |
  258. | `gc_stale_indexes` | Remove index databases for repos that no longer exist on disk |
  259. ---
  260. ## Supported languages
  261. | Language | Extensions |
  262. |---|---|
  263. | Python | `.py` |
  264. | JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs`, `.cjsx`, `.mjsx` |
  265. | TypeScript | `.ts`, `.tsx`, `.mts`, `.cts`, `.mtsx`, `.ctsx` |
  266. | Go | `.go` |
  267. | Rust | `.rs` |
  268. | Java | `.java` |
  269. | Kotlin | `.kt`, `.kts` |
  270. | Dart | `.dart` |
  271. | Swift | `.swift` |
  272. | PHP | `.php` |
  273. | C# | `.cs` |
  274. | C | `.c` |
  275. | C++ | `.h`, `.hh`, `.hpp`, `.hxx`, `.cpp`, `.cc`, `.cxx` |
  276. | HTML | `.html`, `.htm` |
  277. | CSS | `.css`, `.scss`, `.sass`, `.less`, `.stylus`, `.styl` |
  278. | Shell | `.sh`, `.bash`, `.zsh` |
  279. | Elixir | `.ex`, `.exs` |
  280. | Ruby | `.rb` |
  281. | Vue | `.vue` script blocks parsed as JavaScript or TypeScript |
  282. | Svelte | `.svelte` script blocks parsed as JavaScript or TypeScript |
  283. | Markdown | `.md`, `.markdown`, `.mdx` headings plus supported fenced code blocks |
  284. Powered by [tree-sitter](https://tree-sitter.github.io/tree-sitter/) for code, language-pack grammar fallbacks, and a native Markdown scanner for headings and fenced code examples.
  285. ---
  286. ## Supported platforms
  287. SymDex works with any MCP client that supports stdio or streamable HTTP.
  288. | Platform | Typical setup |
  289. |---|---|
  290. | Codex CLI | Add to MCP settings |
  291. | Gemini CLI | Add to MCP settings |
  292. | Cursor | `.cursor/mcp.json` |
  293. | Windsurf | Add to MCP settings |
  294. | GitHub Copilot | `.vscode/mcp.json` |
  295. | Roo | Add to MCP settings |
  296. | Continue.dev | `config.json` |
  297. | Cline | Add to MCP settings |
  298. | Kilo Code | VS Code MCP settings |
  299. | Zed | Add to MCP settings |
  300. | OpenCode | `opencode.json` |
  301. | Any MCP client | `uvx symdex serve` or `symdex serve --port 8080` |
  302. ---
  303. ## Semantic embedding backends
  304. Base `symdex` installs the lean core only. Choose the embedding extra that matches how you want semantic search to work:
  305. - `symdex[local]` for local `sentence-transformers`
  306. - `symdex[voyage]` for Voyage text embeddings
  307. - `symdex[voyage-multimodal]` for Voyage text plus images and PDFs
  308. Remote OpenAI-compatible and Gemini backends use the Python standard library HTTP client, so they do not add a required dependency.
  309. ### Local mode
  310. ```bash
  311. pip install "symdex[local]"
  312. SYMDEX_EMBED_BACKEND=local \
  313. SYMDEX_EMBED_MODEL=all-MiniLM-L6-v2 \
  314. symdex index . --repo myrepo
  315. ```
  316. ### Voyage text mode
  317. ```bash
  318. pip install "symdex[voyage]"
  319. SYMDEX_EMBED_BACKEND=voyage \
  320. VOYAGE_API_KEY=... \
  321. SYMDEX_VOYAGE_MODEL=voyage-code-3 \
  322. symdex index . --repo myrepo
  323. SYMDEX_EMBED_BACKEND=voyage \
  324. VOYAGE_API_KEY=... \
  325. symdex semantic "parse source code" --repo myrepo
  326. ```
  327. ### OpenAI-compatible mode
  328. Use this for OpenAI, local OpenAI-compatible servers, and proxy services that expose `POST /embeddings`.
  329. ```bash
  330. SYMDEX_EMBED_BACKEND=openai \
  331. SYMDEX_EMBED_BASE_URL=https://api.openai.com/v1 \
  332. SYMDEX_EMBED_MODEL=text-embedding-3-small \
  333. SYMDEX_EMBED_API_KEY=... \
  334. SYMDEX_EMBED_RPM=60 \
  335. symdex index . --repo myrepo --lazy
  336. ```
  337. For a local or proxy provider, set `SYMDEX_EMBED_BACKEND=custom`, point `SYMDEX_EMBED_BASE_URL` at its `/v1` base URL, and set the model name it expects. If the provider does not need an API key, omit `SYMDEX_EMBED_API_KEY`.
  338. ### Gemini mode
  339. Gemini uses `RETRIEVAL_DOCUMENT` when indexing and `RETRIEVAL_QUERY` when searching.
  340. ```bash
  341. SYMDEX_EMBED_BACKEND=gemini \
  342. GEMINI_API_KEY=... \
  343. SYMDEX_EMBED_MODEL=text-embedding-004 \
  344. SYMDEX_EMBED_RPM=60 \
  345. symdex index . --repo myrepo --lazy
  346. ```
  347. ### Voyage multimodal mode
  348. ```bash
  349. pip install "symdex[voyage-multimodal]"
  350. SYMDEX_EMBED_BACKEND=voyage
  351. SYMDEX_VOYAGE_MULTIMODAL=1
  352. VOYAGE_API_KEY=...
  353. SYMDEX_VOYAGE_MULTIMODAL_MODEL=voyage-multimodal-3.5
  354. symdex index . --repo myrepo
  355. ```
  356. Multimodal mode lets SymDex index supported images, screenshots, and PDFs as searchable asset entries.
  357. Notes:
  358. - Base `symdex` keeps symbol, text, route, and call-graph features without pulling in the local embedding stack.
  359. - If `SYMDEX_EMBED_BACKEND` is unset, SymDex uses the local backend when `symdex[local]` is installed.
  360. - Local semantic search requires `symdex[local]` and downloads the model on first use.
  361. - Voyage text mode requires `symdex[voyage]`.
  362. - Voyage multimodal mode requires `symdex[voyage-multimodal]`.
  363. - OpenAI-compatible mode reads `SYMDEX_EMBED_BASE_URL`, `SYMDEX_EMBED_MODEL`, and optional `SYMDEX_EMBED_API_KEY` or `OPENAI_API_KEY`.
  364. - Gemini mode reads `SYMDEX_EMBED_MODEL`, `SYMDEX_EMBED_BASE_URL`, and `SYMDEX_EMBED_API_KEY`, `GEMINI_API_KEY`, or `GOOGLE_API_KEY`.
  365. - `SYMDEX_EMBED_RPM` applies request pacing to remote backends. Use it when free tiers or proxies enforce requests-per-minute limits.
  366. - `symdex index --lazy` performs the fast structural index first, then starts a background `symdex watch --embed` process so embeddings can fill in without blocking the foreground command.
  367. - `symdex index --no-embed` skips semantic embedding work entirely.
  368. - If the selected backend extra is missing, SymDex prints an actionable install hint.
  369. - Multimodal indexing is only active when `SYMDEX_VOYAGE_MULTIMODAL=1`.
  370. ---
  371. ## FAQ
  372. ### What is SymDex?
  373. SymDex is a repo-local symbolic indexing engine for AI coding agents. It indexes a project into a local SQLite knowledge base so agents can retrieve exact symbols, file outlines, HTTP routes, callers, callees, text matches, semantic matches, token-budgeted context packs, and repo summaries without reading whole files first.
  374. ### What problem does SymDex solve for AI coding agents?
  375. SymDex reduces blind repo browsing. Instead of opening broad files and spending thousands of tokens on orientation, an agent can ask SymDex for the specific function, route handler, call graph edge, Markdown heading, or file outline needed for the current task.
  376. ### Can SymDex help agents find bugs or check code logic?
  377. Yes, as a code-comprehension and evidence layer. SymDex does not prove bugs by itself and is not a full static analyzer. It helps an agent investigate logic by retrieving exact definitions, callers, callees, routes, file outlines, text matches, semantic matches, documentation anchors, and query-driven context packs, then attaching quality metadata so the agent can see whether the evidence is fresh, parser-backed, generated, or missing embeddings before making a claim.
  378. ### Is SymDex an MCP server?
  379. Yes. SymDex includes an MCP server with 21 tools for indexing, symbol search, semantic search, text search, context packs, file outlines, repo outlines, route search, call graph traversal, repo stats, cache invalidation, and stale-index cleanup. It also provides CLI commands for the same repo-local retrieval workflow.
  380. ### Which AI coding agents can use SymDex?
  381. Any MCP client that supports stdio or streamable HTTP can use SymDex. Typical setups include Codex CLI, Gemini CLI, Cursor, Windsurf, GitHub Copilot, Roo, Continue.dev, Cline, Kilo Code, Zed, OpenCode, and other MCP-compatible clients.
  382. ### How is SymDex different from grep, ripgrep, embeddings, or an LSP?
  383. SymDex combines exact structural search with optional semantic search and token-budgeted context packs. Grep and ripgrep find text; language servers provide editor-native type navigation; embedding-only systems find approximate meaning; whole-repo packers produce large prompt artifacts. SymDex gives agents a pre-indexed local map with symbols, byte offsets, routes, call graphs, text search, semantic search, quality metadata, context packs, and MCP tools in one workflow.
  384. ### Does SymDex replace a language server?
  385. No. SymDex is not a full type checker or automated refactoring engine. Use a language server when editor-native type reasoning or refactors matter. Use SymDex when an agent needs fast repo-local retrieval, route discovery, code outlines, semantic search, context packs, and lower-token navigation across one or more repos.
  386. ### What languages and files does SymDex index?
  387. SymDex currently covers 21 language surfaces: Python, JavaScript, TypeScript, Go, Rust, Java, Kotlin, Dart, Swift, PHP, C#, C, C++, HTML, CSS-family stylesheets, Shell, Elixir, Ruby, Vue script blocks, Svelte script blocks, and Markdown. Markdown support includes `.md`, `.markdown`, and `.mdx` headings plus supported fenced code blocks.
  388. ### Can SymDex extract HTTP routes?
  389. Yes. SymDex extracts HTTP routes across Python, JavaScript/TypeScript, Spring/Kotlin, Laravel, Gin-style Go, ASP.NET, Rails/Sinatra, Phoenix, and Actix. Agents can query routes directly instead of manually scanning routers, decorators, controllers, or framework entry points.
  390. ### Does SymDex help documentation, SEO, or Generative Engine Optimization teams?
  391. Yes, when technical content depends on a codebase. Documentation, SEO, and Generative Engine Optimization (GEO) teams can use SymDex-powered agents to build source-backed context packs, find SDK examples, API routes, Markdown headings, feature implementations, and source-backed answers before updating developer docs, changelogs, comparison pages, or AI-search-friendly technical content. SymDex is a code retrieval layer, not a keyword research or rank tracking tool.
  392. ### Does semantic search require the internet?
  393. No, not by default. Install `symdex[local]` for local `sentence-transformers` semantic search; the model downloads once and then runs offline. Voyage, OpenAI-compatible, and Gemini embedding modes require network access unless the configured base URL points at a local server or private proxy.
  394. ### Can SymDex run without semantic embeddings?
  395. Yes. `pip install symdex` keeps the core symbol, text, route, file outline, repo outline, call graph, and MCP features lean. Use `symdex index --no-embed` to skip embedding work entirely, or add embeddings later with `symdex[local]`, Voyage, OpenAI-compatible, Gemini, `symdex index --lazy`, or `symdex watch --embed`.
  396. ### Why does `symdex semantic` say a repo has no semantic embeddings?
  397. That repo was indexed without an embedding backend, indexed with `--no-embed`, or kept fresh by the default low-memory watch mode. Enable the backend you want, then run `symdex index`, `symdex index --lazy`, or `symdex watch --embed` so semantic vectors are written into the index.
  398. ### Will `symdex watch` keep a large embedding model in memory?
  399. No, not by default. `symdex watch` refreshes structural indexes without loading local embedding models unless `--embed` is passed. Watch mode also refuses duplicate watchers for the same repo/root, can auto-exit after idle time, and stores watcher metadata in the active state directory.
  400. ### Where are SymDex indexes stored?
  401. By default, each repo gets its own SQLite database under `~/.symdex`, plus a central registry database. Set `SYMDEX_STATE_DIR=.symdex` or use `symdex --state-dir .symdex ...` to keep repo databases, `registry.db`, `registry.json`, and watcher metadata inside the current workspace.
  402. ### Can SymDex work across multiple repos and worktrees?
  403. Yes. SymDex maintains a registry of indexed repos, supports explicit `--repo` names, and can auto-generate stable repo ids from the current branch and worktree path when `--repo` is omitted. Use `symdex repos` to list indexes and `symdex gc` to clean stale entries after deleting worktrees.
  404. ### How does SymDex report token savings?
  405. Successful CLI search commands print a one-line ROI footer with approximate token savings. MCP search tools return structured `roi`, `roi_summary`, and `roi_agent_hint` fields so agents can mention retrieval savings in user-facing responses.
  406. ### What are SymDex retrieval quality signals?
  407. MCP results and CLI JSON outputs include a `quality` object with fields such as `confidence`, `confidence_reason`, `index_fresh`, `last_indexed`, `parser_mode`, `language_surface`, `is_generated`, `has_embeddings`, and `route_confidence`. Agents can use those fields to avoid over-trusting stale indexes, fallback text matches, generated files, or semantic searches from repos without embeddings.
  408. ### What does indexing print?
  409. After indexing, SymDex prints a code summary with file count, Lines of Code, symbol counts, route counts, skipped files, errors, and language breakdown. This helps teams confirm what was indexed before relying on search results.
  410. ### Can generated files be excluded?
  411. Yes. Add a `.symdexignore` file at the repo root with gitignore-style patterns. SymDex also skips common generated, dependency, and build paths by default.
  412. ### Why do some logs say `index_folder` or `list_repos` while CLI docs say `index` and `repos`?
  413. `index_folder` and `list_repos` are MCP tool names. The canonical shell commands are `symdex index` and `symdex repos`, and compatibility aliases such as `symdex index-folder` and `symdex list-repos` are also accepted.
  414. ### Do existing users get update notices?
  415. Yes. Interactive CLI commands can print a brief upgrade notice with exact commands for `pip`, `uv tool`, and `uvx`. JSON output stays quiet so structured consumers are not broken.
  416. ### Can SymDex be used without an AI agent?
  417. Yes. All core search and navigation features are available through the CLI, including symbol search, exact lookup, text search, semantic search, context packs, route search, callers, callees, outlines, repo listing, and stale-index cleanup.
  418. ---
  419. ## Contributing
  420. Issues and PRs are welcome at [github.com/husnainpk/SymDex](https://github.com/husnainpk/SymDex).
  421. If SymDex saves you tokens, a star helps other people find it.

Ratings and comments

Sign in to rate this skill.

Sign in

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