CodeScry is a local codebase retrieval tool for coding agents. It indexes committed code from local git repos into a local SQLite database, then exposes ranked snippets through a CLI and MCP stdio server.

Why CodeScry

• Local-first by default: auto-selects local Ollama mxbai-embed-large when available, otherwise falls back to hash embeddings and SQLite storage.

• Agent-ready: MCP tools for search_code, get_symbol, list_repos, and reindex.

• Large-index aware: bounded sqlite-vec candidate paths avoid scoring every chunk once vectors are backfilled.

• Semantic opt-in: Ollama, OpenAI, and sentence-transformers providers are available when quality matters more than default speed.

• Measured on real repos: public agent-natural evals and ranking/performance findings live in docs/ranking-experiment-findings.md.

Recent private ~/code mxbai eval improved from ~20.7s average query latency to ~1.8s after filtered vector serving optimizations, with Recall@10 stable at 0.800. See docs/performance.md for knobs and diagnostics.

Install

Fast path:

curl -LsSf https://raw.githubusercontent.com/Zhachory1/codescry/main/scripts/install.sh | sh

The installer uses uv tool install codescry when uv is available, otherwise pipx install codescry. If neither uv nor pipx is installed, it bootstraps pipx with python3 -m pip --user.

If you prefer explicit installs:

pipx install codescry
# or, if uv is already installed
uv tool install codescry

Node users can run the npm wrapper after installing uv:

npx codescry doctor

The npm package is a thin wrapper around the Python package. It does not bundle local SQLite index data.

For development:

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Check local readiness:

codescry doctor

First success path

For a deterministic five-minute smoke test, see docs/getting-started.md.

Index this repo or another local git repo:

codescry index /path/to/git/repo

Query it:

codescry query "where is request retry handled" -k 5

Lookup a symbol:

codescry get-symbol RepoIndex --repo /path/to/git/repo

Discover and index every git repo under a root:

codescry index-root ~/code

Show indexed repos, stale/dirty state, and CodeScry hook coverage:

codescry status

MCP setup

Run the MCP server over stdio:

codescry serve

The MCP server answers queries only. It is not a file watcher; keep committed-code freshness by running codescry reindex or installing git hooks.

Agent config example:

{
  "mcpServers": {
    "codescry": {
      "type": "stdio",
      "command": "/Users/YOU/.local/bin/codescry",
      "args": ["--db", "/Users/YOU/.codescry/index.sqlite", "serve"],
      "env": {}
    }
  }
}

npm/npx config example:

{
  "mcpServers": {
    "codescry": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codescry", "--db", "/Users/YOU/.codescry/index.sqlite", "serve"],
      "env": {}
    }
  }
}

Use which codescry to find the absolute command path for your machine when using direct CLI installs.

Freshness hooks

Install hooks for one repo or a repo root:

codescry install-hooks /path/to/git/repo
codescry install-hooks ~/code --recursive

Hooks run best-effort after commit/merge:

codescry --db <db> reindex "$PWD"

They preserve the selected DB path and must not fail git commands.

If hooks are not practical, run an opt-in committed-state watcher:

codescry watch ~/code/my-repo
codescry watch --once --jsonl

The watcher polls git HEAD for indexed repos or a specified repo, then reindexes committed snapshots only when the commit changes.

Docs

• docs/getting-started.md — install to first useful query.

• docs/mcp-clients.md — MCP config examples.

• docs/troubleshooting.md — common setup/query/freshness issues.

• docs/cli-reference.md — command reference.

• docs/output-schema.md — JSON fields.

• docs/evals.md — eval authoring and gate.

• docs/performance.md — query/index latency knobs, candidate union, batching, and debug telemetry.

• docs/embedding-providers.md — hash, Ollama, OpenAI, and sentence-transformers embedding providers.

• docs/pilot.md — 5-engineer pilot measurement plan and local reporting commands.

• docs/language-support.md — parser/regex/window support matrix.

• docs/recipes.md — common operations.

• docs/upgrade-uninstall.md — lifecycle commands.

• docs/release.md — PyPI-first and npm-wrapper release flow.

• docs/ranking-experiment-findings.md — retrieval/ranking experiments and eval findings.

Evals

The seed golden set lives in evals/golden.codescry.jsonl.

Run the eval gate:

codescry eval evals/golden.codescry.jsonl . -k 10 --fail-under 0.85

Pilot proof

Pilot task/activation/miss events are recorded in ~/.codescry/usage.jsonl without snippets. Passive query logging is opt-in with CODESCRY_ENABLE_USAGE_LOG=1. Use:

codescry pilot report

See docs/pilot.md for activation, timing, miss capture, and decision gates.

Retrieval behavior

• Default auto embeddings use local Ollama mxbai-embed-large when available, otherwise local deterministic hash vectors.

• Optional embedding providers include Ollama, OpenAI, and sentence-transformers. See docs/embedding-providers.md.

• Changing embedding provider or model requires reindexing because stored vectors are model-specific.

• Python functions/classes/methods get parser-backed symbol metadata.

• TS/JS/Go/Java/Rust/C/C++/SQL get Tree-sitter parser-backed symbol metadata.

• Other common declaration patterns get regex-backed symbol metadata.

• get_symbol uses stored symbol metadata before search fallback.

• Search blends vector, lexical, symbol, and path scores.

• Results include stale/dirty flags.

Data boundary and safety

• Default auto provider does not use hosted APIs. It uses local Ollama if available, otherwise local hash embeddings.

• Default configuration does not send source code to hosted external APIs.

• OpenAI and non-local Ollama embedding endpoints send chunks and queries outside your machine. See SECURITY.md and docs/embedding-providers.md.

• Index data is local SQLite derived data and can be deleted/rebuilt.

• Files matching high-confidence secret patterns are skipped and prior chunks for those paths are removed.

• Secret skipping is a best-effort local guardrail, not a guarantee. See SECURITY.md.

Current limits

• Python uses stdlib AST parser chunks; TS/JS/Go/Java/Rust/C/C++/SQL use Tree-sitter parser chunks; other languages use regex-backed symbol hints plus line windows.

• Default auto embeddings prefer local semantic Ollama when available and fall back to hash embeddings otherwise; hosted semantic embeddings are opt-in only.

• SQLite remains the default local store; large-index serving uses bounded sqlite-vec candidate paths where vector coverage exists.

• Freshness is committed-code freshness; dirty working-tree edits are reported but not indexed.