CodeScry

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.

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 and freshness:

codescry status

MCP setup

Run the MCP server over stdio:

codescry serve

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.

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/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 embeddings are local deterministic hash vectors.
• Optional embedding providers include Ollama, OpenAI, and sentence-transformers. See docs/embedding-providers.md.
• 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 embeddings are local deterministic hash vectors.
• Default configuration does not send source code to external APIs.
• 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.
• Local deterministic hash embeddings, not quality-tuned semantic embeddings.
• SQLite storage scans/scoring in Python, no ANN/vector extension yet.
• Freshness is committed-code freshness; dirty working-tree edits are reported but not indexed.