Descry

Polyglot codebase knowledge graph with call-graph analysis, semantic search, and SCIP integration. Built for AI coding agents (MCP), with CLI and Web UI interfaces.

Descry indexes your codebase into a knowledge graph of symbols (functions, classes, constants) and their relationships (calls, imports, defines). SCIP-backed type-aware resolution is available for Rust, TypeScript, JavaScript, Svelte, Python, Java (+ Kotlin / Scala), Go, Ruby, PHP, C# (+ VB.NET), C / C++, and Dart. The .js / .jsx / .svelte paths run through scip-typescript; pure Kotlin / Scala source needs scip-java (which doesn't always work on Kotlin-DSL Gradle projects — see CHANGELOG known limitations).

⚠️ Disclaimer — please read

Descry was built with heavy assistance from AI coding agents. While the codebase has been through an internal security and correctness review, AI-authored code can still contain subtle defects, missed edge cases, or security assumptions that weren't obvious to the reviewer. Treat this tool as experimental pre-1.0 software: do not rely on it for safety-critical analysis, and do not point it at code or repositories you don't trust.

This tool is designed to run locally on your own machine. The web UI (descry-web) binds to 127.0.0.1 and is unauthenticated by design — the threat model assumes a single trusted user on the host.

• Do not expose descry-web to a network. No reverse proxy, no public tunnel, no --host 0.0.0.0. If you need remote access, put it behind your own authenticated reverse proxy and understand that any browser tab on the host machine can still reach it via localhost.
• Do not run Descry on untrusted repositories. Indexing a repository executes configuration from its .descry.toml, walks its file tree, and feeds its docstrings/source to your LLM (if you use the MCP server). The same trust boundary that applies to cargo build, npm install, and opening the repo in your IDE applies here.
• Report security issues privately — see SECURITY.md.

Embedding models

Semantic search embeds one text per symbol: its name, signature, docstring and the first 1,500 characters of its source. With no model configured, descry uses embeddinggemma; if HuggingFace refuses that download because the account has not accepted its licence, it warns and uses f2llm-v2-0.6b instead.

[embeddings]
model = "f2llm-v2-0.6b"       # alias, full HuggingFace repo id, or a local path

descry embedding-models       # what is available, and what is selected

To use the default model, accept its licence once and authenticate:

# 1. accept the licence at https://huggingface.co/google/embeddinggemma-300m
hf auth login                 # 2. or export HF_TOKEN=...
descry index                  # 3. each index tries the default first

Searches use whichever model built the current index, so the switch happens at the next descry index. A model named in .descry.toml is used as given: it never falls back, and naming f2llm-v2-0.6b skips the attempt and the warning.

Measured with tests/eval/ — docstring→symbol queries, leave-one-out leakage control, paired bootstrap:

descry (3,014 nodes, 1,377 queries, Python)

ripgrep at 3fce3b5 (3,820 nodes, 691 queries, Rust)

Rerun on your own project — the ranking is measured, not universal:

python tests/eval/compare.py /path/to/.descry_cache/codebase_graph.json

Each entry carries its own pinned revision and task prompts, both of which feed the cache key — changing model re-embeds rather than silently reusing vectors from a different embedding space. descry never loads a model with trust_remote_code — not for registry entries, and not for a model you name yourself, which is also loaded unpinned.

Quick Start

# Install with all optional features
pip install descry-codegraph[all]

# Index your project
cd your-project
descry index

# Search for symbols
descry search authenticate

# Find callers of a function
descry callers validate_token

# One-step lookup (search + full context)
descry quick handle_request

Interfaces

MCP Setup

Claude Code

Add to your Claude Code MCP settings (.claude/settings.json or global):

{
  "mcpServers": {
    "descry": {
      "command": "descry-mcp",
      "args": []
    }
  }
}

Or with a specific Python path:

{
  "mcpServers": {
    "descry": {
      "command": "/path/to/venv/bin/descry-mcp",
      "args": []
    }
  }
}

Other MCP Hosts

Descry uses the standard MCP stdio transport. Any MCP-compatible host can spawn descry-mcp as a subprocess.

Tools

Descry provides 19 tools, available through all interfaces:

Configuration

Descry works zero-config by auto-detecting your project root. The walker looks for any of: .git, .descry.toml, Cargo.toml, package.json, pyproject.toml, setup.py, go.mod, Gemfile, composer.json, build.gradle{,.kts}, settings.gradle{,.kts}, pom.xml, build.sbt, global.json, pubspec.yaml, CMakeLists.txt, or compile_commands.json.

For customization, add a .descry.toml to your project root.

Heads-up on list-typed fields. Several settings below are lists that REPLACE descry's defaults when set, not merge. These include [project] excluded_dirs, [code_files] extensions, [test_detection] path_patterns / file_suffixes, and [git] churn_exclusions. Leave them out unless you have a specific reason — descry's defaults already cover a wide language matrix. If you do set them, copy the full default list (see _DEFAULT_* constants in src/descry/handlers.py) and modify from there. [syntax.lang_map] is the one list-shaped field that merges with defaults.

[project]
# OPTIONAL — REPLACES the 25-element default. Leave unset to keep defaults
# (.git, .gradle, .next, .svelte-kit, .venv, node_modules, target, build, …).
# excluded_dirs = ["target", "node_modules", "dist", "build", "vendor"]
# OPTIONAL — in a git repository, files git ignores are not indexed.
# Default true; false indexes them too.
# respect_gitignore = true
max_stale_hours = 24

[features]
enable_scip = true         # Type-aware resolution (auto-detects which indexers are on PATH)
enable_embeddings = true   # Semantic search (requires sentence-transformers)

[embeddings]
model = "embeddinggemma"   # see "Embedding models"; `descry embedding-models` lists them

[test_detection]
# OPTIONAL — REPLACES defaults. Defaults cover Rust/Python/TS/Go/Ruby/Java/Kotlin/
# Scala/PHP/C#/Dart/C/C++ test conventions.
# path_patterns = ["/tests/", "/test/", "/__tests__/"]
# file_suffixes = ["_test.rs", ".test.ts", ".spec.ts", "_test.py"]

[code_files]
# OPTIONAL — REPLACES the 35-element default (.rs/.py/.ts/.tsx/.mts/.cts/.js/
# .jsx/.mjs/.cjs/.svelte/.proto/.go/.java/.kt/.scala/.rb/.rake/.gemspec/.php/
# .cs/.vb/.c/.cc/.cpp/.cxx/.cu/.h/.hh/.hpp/.hxx/.dart/.css/.scss/.html). Leave
# unset to keep defaults.
# extensions = [".rs", ".py", ".ts", ".tsx", ".go", ".java"]
# OPTIONAL — larger files are skipped by the indexer (it logs each one) and
# refused by the web source view. Default 10; 0 = no limit.
# max_file_mb = 10
# OPTIONAL — a file whose parsing takes longer is left as far as it got (the
# indexer logs it) and the next one is read. Default 120; 0 = no limit. Not
# enforced on Windows.
# max_parse_seconds = 120

[git]
# OPTIONAL — REPLACES defaults (.descry_cache/, .beads/, Cargo.lock,
# package-lock.json, yarn.lock, pnpm-lock.yaml).
# churn_exclusions = [".descry_cache/", "Cargo.lock", "package-lock.json"]
timeout = 30

[timeouts]
scip_minutes = 30      # per indexer; 0 = unlimited
embedding_seconds = 60
query_ms = 4000
index_minutes = 30     # Timeout for `descry index` subprocess

[query]
max_depth = 3
max_nodes = 100
max_children_per_level = 10
max_callers_shown = 15

[scip]
extra_args = ["--exclude-vendored-libraries"]
skip_crates = []         # Crate names to skip during SCIP indexing

[scip.rust]
toolchain = "1.92.0"     # Pin rust-analyzer version via rustup

[syntax.lang_map]
# MERGES with defaults (additive). Maps file extensions to syntax-highlight names.
".svelte" = "svelte"
".proto" = "protobuf"

[cross_lang]
# Frontend -> backend handler tracing via OpenAPI spec. An operation's handler
# is the function its operationId names; where several functions share the
# name, the one whose attributes or decorators write the operation's path
# (`#[utoipa::path(.., path = "/x")]`, `@app.get("/x")`), else the one outside
# test code. A handler named otherwise is found by the path it declares.
openapi_path = "public/api/openapi.json"   # must resolve inside project_root
# OPTIONAL — only functions in files whose path holds one of these are
# handlers. Needed only where the rules above leave a name ambiguous.
# backend_handler_patterns = ["backend/src/routes"]
api_prefixes = ["/api/v1", "/api/v2", "/api"]      # stripped when matching spec paths

Environment Variables

Configuration precedence: defaults < .descry.toml < environment variables.

Language Support

JavaScript and TypeScript cover .js, .jsx, .mjs, .cjs, .ts, .tsx, .mts and .cts.

Each call is resolved from evidence: imports (including go.mod, Cargo.toml, package.json and tsconfig.json), declared and returned types, lexical scope, the class hierarchy and the language's visibility rules. Names bound by loops, patterns, destructuring and closure parameters are typed from declarations, and each language's standard library is described by generated data (src/descry/stdlib/), so a chain through library types keeps its type. A call ends as resolved to one definition, unresolved when nothing in the source decides — the definitions that fit are kept on the edge as candidates — or external when it leaves the project; the index summary reports all three. Nothing is matched by name alone when more than one definition fits, nothing by file path, and a receiver whose type is not known is never guessed. SCIP adds type-aware resolution through traits and generics, and is verified for Rust workspaces; the other indexers' output is used only where it names a node in the graph.

Share of project calls resolved without SCIP, measured on public repositories at the commits named:

The remainder is unresolved, not wrong: of 450 resolved edges drawn at random from these repositories and read against the source, every one reaches the definition the call reaches. Ruby is low because the language declares no types and calls inside DSL blocks run with another self; libuv because most of its functions exist once for Unix and once for Windows, and the build files, not the source, choose between them.

Installation

Minimal (graph + CLI only)

pip install descry-codegraph

With MCP server

pip install descry-codegraph[mcp]

With Web UI

pip install descry-codegraph[web]

With semantic search

pip install descry-codegraph[embeddings]

To select embeddinggemma-2, install its extra instead (adds Pillow and torchvision, and requires sentence-transformers 6.1 or newer):

pip install "descry-codegraph[embeddinggemma-2]"

Everything

pip install descry-codegraph[all]

Development

git clone https://github.com/06chaynes/descry.git
cd descry
just install    # Creates venv and installs with dev deps
just test       # Run tests
just lint       # Ruff linting
just fmt        # Ruff formatting

Requires uv and just.

How It Works

1. Index — Descry walks your codebase, parses source files into an AST-like representation, and builds a graph of symbols and their relationships. If SCIP is available, it overlays type-aware call resolution.

2. Cache — The graph is cached as JSON in .descry_cache/codebase_graph.json. Embeddings are cached separately. SCIP indices are cached per-crate/package.

3. Query — All tools query the cached graph. Keyword search uses TF-IDF scoring. Semantic search uses sentence-transformer embeddings. Call-graph traversal follows edges in the graph.

4. Freshness — ensure regenerates the graph when its age exceeds [project] max_stale_hours (default 24), or the --max-age-hours flag (CLI) / max_age_hours argument (MCP) when one is given. The same setting drives the "STALE" badge in descry status. The MCP server pre-warms the graph on startup.

Design Notes

Web UI is local-only — same-origin + DNS-rebind defenses

descry-web is designed as a single-user local development tool. It binds to 127.0.0.1 by default, has no authentication, and deliberately omits CORSMiddleware so browsers enforce same-origin by default — a tab on evil.com cannot read /api/source. Requests that change state (/api/index, /api/index/stream, /api/ensure) are refused unless they come from the page's own origin, so it cannot trigger a reindex either. This is deliberate:

• The UI is served by the same process that reads your repository; any authentication layer would be a shared-secret between your browser and your own terminal.
• TrustedHostMiddleware rejects requests whose Host header isn't loopback (127.0.0.1, localhost, ::1), defeating DNS-rebinding attacks that would otherwise bypass the 127.0.0.1 bind.
• The --host flag is validated by _loopback_host and rejects non-loopback values with a clear error pointing at the reverse-proxy guidance.
• Path-traversal hardening on /api/source is independent of any CORS posture: it enforces project-root containment, rejects non-regular files, caps size at [code_files] max_file_mb, refuses non-text content, and opens every path component with O_NOFOLLOW to defeat symlink swaps.
• The page's scripts are pinned with Subresource Integrity hashes and a Content-Security-Policy is sent with every response; rendered repository markdown cannot load remote images.
• The reindex endpoints (/api/index, /api/index/stream) accept no path parameter; they always index the configured project root, one run at a time (a second request gets 409).

Do not expose descry-web to an untrusted network. If you need remote access, put it behind your own authenticated reverse proxy.

Versioning

Descry is pre-1.0. Minor version bumps (0.1.x → 0.2.x) may include breaking changes to the library API, graph schema, CLI, or MCP tool signatures. Patch releases (0.1.0 → 0.1.1) will not introduce breaking changes. Once we reach 1.0.0, the project will follow semver strictly.

The only stable public API in pre-1.0 releases is descry.__version__. Submodules (descry.handlers, descry.query, etc.) are not considered stable API yet — refactor freely.

Further Reading

• CHANGELOG — release notes.
• SECURITY — security policy and disclosure.

License

MIT. The bundled standard-library data is derived from other projects; see THIRD-PARTY-NOTICES.