SymDex

The codebase oracle AI coding agents wish every repo already had.

Index once. Jump straight to the exact symbol, route, caller, callee, or file slice. Read only what you need.

<br>

<br> <h2 align="center">7,500 tokens -> 200 tokens</h2> <p align="center"><strong>Per lookup. Every lookup. Approximate, but directionally real.</strong></p> <p align="center"> <img src="docs/images/symdex-hero-16x9.png" alt="SymDex hero visual showing token reduction and code intelligence workflow" width="100%" /> </p>

# Install the lean core
pip install symdex

# Add local semantic search when you want the sentence-transformers backend
pip install "symdex[local]"

# Or install the local-backend CLI as an isolated tool
uv tool install "symdex[local]"

# Or run without installing
uvx symdex --help

# Upgrade an existing install
py -m pip install -U symdex
uv tool upgrade symdex
uvx symdex@latest --help

# Install the SymDex agent skill globally for supported agents
npx skills add https://github.com/husnainpk/SymDex --skill symdex-code-search --yes --global

</div>

Why SymDex

SymDex exists for one reason:

stop agents from reading whole files just to find one function

In plain terms:

SymDex is not another grep wrapper and not another black-box hosted index
SymDex is the repo-local intelligence layer that makes coding agents feel like they already know your codebase
it turns blind file-browsing into exact retrieval
and it does that while cutting token spend hard

SymDex pre-indexes a repository into:

a symbol table with byte offsets
semantic embeddings for intent search
a call graph
extracted HTTP routes
a registry in the active SymDex state directory (~/.symdex by default or workspace-local ./.symdex)

That lets an agent jump straight to the exact symbol or file slice it needs, which means fewer blind file reads and materially lower token burn.

Current main-branch highlights:

symdex index prints a code summary with files, Lines of Code, symbol counts, routes, skipped files, and language breakdown
symdex search, find, text, and semantic print approximate token-savings footers
Kotlin, Dart, and Swift are now grammar-backed parser targets, so Android, Flutter, and iOS codebases are first-class citizens
route extraction now covers Spring and Kotlin, Gin-style Go routers, ASP.NET, Rails and Sinatra, Phoenix, and Actix in addition to Python, JS/TS, and Laravel
normal CLI commands now show an upgrade notice when a newer SymDex release is available
--repo is the canonical naming flag, with --name retained as a compatibility alias
omitting --repo on index and watch auto-generates a stable repo id from the current git branch and worktree path hash
local sentence-transformers embeddings now live behind the optional symdex[local] extra
Voyage AI is available as an optional embedding backend, including optional multimodal asset indexing
optional workspace-local state keeps repo databases plus registry.json inside ./.symdex for Docker and portable workspaces

SymDex Skill For Agents

Install the SymDex code-search skill to make agents use SymDex before broad file browsing:

npx skills add https://github.com/husnainpk/SymDex --skill symdex-code-search --yes --global

If you want the interactive installer instead, omit --yes --global.

What it does:

checks repo/index readiness first
uses SymDex before Read/Grep/Glob for discovery
prefers symbol-level and outline-level retrieval over full-file reads
guides agents toward callers, callees, routes, and semantic search when those are the better fit
keeps the workflow centered on lower-token code retrieval instead of broad file reads

The skill lives in this repo at skills/symdex-code-search/SKILL.md and follows the standard skills/<name>/SKILL.md layout.

If you are wiring SymDex into an agent workflow directly from this repo, start with AGENTS.md too.

Installing through the skills CLI is also the path that feeds skills.sh discovery telemetry.

60-second quickstart

# Install
pip install "symdex[local]"
# or
uv tool install "symdex[local]"

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

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

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

# 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 an approximate ROI footer with tokens read, tokens avoided, and tokens saved.
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 now also accept MCP-shaped names like index-folder, index-repo, and list-repos.
Semantic search requires stored embeddings. If a repo was indexed before symdex[local] or Voyage was enabled, re-index it after enabling the backend you want.

Add to your agent config:

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

HTTP mode:

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

Workspace-local state and Docker

SymDex still defaults to ~/.symdex, but it now also supports a workspace-local state directory for portable and containerized workflows.

Use it like this on first setup:

SYMDEX_STATE_DIR=.symdex symdex index ./myproject --repo myproject

That creates:

./.symdex/<repo>.db
./.symdex/registry.db
./.symdex/registry.json

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.

After the local state exists, SymDex auto-discovers it from the current workspace or any nested subdirectory.

What you get

| Feature | Details | |---|---| | Symbol search | Find functions, classes, and methods with exact byte offsets | | Semantic search | Find code by intent instead of exact name | | Text search | Search indexed files by literal text across the repo | | Byte-precise retrieval | Read only the symbol span you need | | File outline | List symbols in a file without transferring the whole file | | Repo outline | Get a directory tree plus repo summary through MCP | | Call graph | Trace callers, callees, and circular dependencies | | HTTP routes | Extract Flask, FastAPI, Django, Express, Spring/Kotlin, Laravel, Gin-style Go, ASP.NET, Rails/Sinatra, Phoenix, and Actix routes | | Auto-watch | Re-index on change and keep the index fresh | | Cross-repo registry | Manage multiple indexed repos from one local registry | | Workspace-local state | Keep repo databases plus registry.json inside ./.symdex for Docker and portable workspaces | | Search ROI footer | Approximate token savings after successful search commands | | Code summary | Files, Lines of Code, symbols, routes, skipped files, and languages after indexing | | Optional embedding backends | Add symdex[local] for local embeddings or symdex[voyage] for hosted embeddings only when needed |

Where SymDex Fits

The old README used a named-tool matrix. I removed it during the cleanup because those claims go stale quickly and are hard to keep precise. This smaller section keeps the positioning signal without overcommitting on other t

SymDex

Install / Use

README

SymDex

Why SymDex

SymDex Skill For Agents

60-second quickstart

Workspace-local state and Docker

What you get

Where SymDex Fits