Symdex Code Search

# SymDex Code Search

Use SymDex before broad file browsing.
Use it to save tokens by retrieving the exact code the agent needs instead of scanning whole files.
SymDex currently covers 21 language surfaces, including Python, Go, Kotlin, Dart, Swift, HTML, CSS, Shell, Vue/Svelte script blocks, and Markdown headings plus supported fenced code blocks.

## Current SymDex Snapshot

- Package version: `0.1.26`
- Latest public tag: `v0.1.26`
- MCP tool surface: 21 tools
- Language coverage: 21 language surfaces, including Android/Kotlin, Flutter/Dart, iOS/Swift, HTML, CSS-family stylesheets, Shell, Vue/Svelte script blocks, Markdown headings, and supported fenced code blocks
- Route extraction: Python, JavaScript/TypeScript, Spring/Kotlin, Laravel, Gin-style Go, ASP.NET, Rails/Sinatra, Phoenix, and Actix
- Search outputs: one-line CLI token-savings footers plus MCP `roi`, `roi_summary`, and `roi_agent_hint`
- Quality outputs: MCP results and CLI JSON include `quality` with confidence, freshness, parser mode, language surface, generated-file hints, and embedding availability
- Context packs: CLI `symdex pack` and MCP `build_context_pack` assemble token-budgeted evidence bundles for broader feature questions
- Semantic backends: local `sentence-transformers`, Voyage, OpenAI-compatible `/embeddings`, Gemini, and compatible proxies
- Hosted embedding support: `SYMDEX_EMBED_RPM` plus `symdex index --lazy` for foreground structural indexing with background embedding fill
- No-embedding mode: `symdex index --no-embed` skips semantic embedding work entirely
- Watch behavior: low-memory structural refresh by default; use `symdex watch --embed` only when semantic embeddings must refresh continuously
- State model: global `~/.symdex` by default, optional workspace-local `./.symdex` with `registry.json`
- Markdown support: `.md`, `.markdown`, and `.mdx` headings plus supported fenced code blocks are indexed alongside source files

## Start Here

1. If the SymDex CLI reports a newer release, prefer upgrading before long sessions.
2. Confirm the repo id.
3. If the repo id is already known, pass `repo` on every scoped tool call.
4. If the repo id is unknown, call `list_repos` and match the current worktree.
5. Check freshness with `get_index_status(repo)`.
6. If the current worktree is not indexed, call `index_folder(path=".")`.
7. If the workspace already has `.symdex`, treat it as the intended local SymDex state and reuse it.
8. Reuse the returned `repo` id for the rest of the task.

If SymDex is unavailable or indexing fails, say so clearly and fall back to normal file reads only as needed.

## Core Rules

- Search first.
- Pass `repo` whenever you know it.
- Use `build_context_pack` for broad "how does this feature work?", docs, API, or bug-investigation questions before issuing many separate narrow searches.
- Prefer `get_symbol` or `get_file_outline` over full-file reads.
- Use call graph and route tools before manual tracing.
- Re-check `get_index_status` after major edits or worktree switches.
- Read full files only when editing, reviewing unsupported or generated content, or when SymDex cannot answer.
- Optimize for lower-token retrieval, not broad context loading.
- If a search tool returns `roi`, `roi_summary`, or `roi_agent_hint`, mention the approximate token savings briefly in your response.
- Inspect `quality` before reasoning from a result. Prefer fresh, parser-backed, high-confidence evidence; warn the user when evidence is stale, generated, fallback text, or missing embeddings.
- If the repo uses workspace-local SymDex state