Codesearch

Hybrid code search powered by ML embeddings, BM25-style keyword matching, and Reciprocal Rank Fusion. Finds code by meaning and by exact keyword — both in a single query, by default.

When to Use This Skill

Invoke this skill immediately when:

• User asks to find code by intent (e.g., "where is authentication handled?")

• User asks to understand what code does (e.g., "how does the indexer work?")

• User asks to explore functionality (e.g., "find error handling logic")

• User asks about implementation details (e.g., "how are embeddings generated?")

• You need to discover code related to a concept rather than an exact string

• User asks about blast radius or impact of changing a function/symbol

• User asks who calls a function or what does a function call (symbol context)

When to Use Built-in Tools Instead

Use Grep/Glob for:

• Exact text matching: Grep "fn new_indexer" (find exact function name)

• Specific imports: Grep "use tokio" (find import statements)

• File patterns: Glob "**/*.rs" (find files by extension)

• Variable references: Grep "config_path" (find exact variable name)

Installation

If the codesearch binary is not found, install it automatically by running the install script bundled with this skill:

INSTALL_DIR="$HOME/.local/bin" sh .claude/skills/codesearch/install.sh

After installation, verify it works:

codesearch --version

Note: The script downloads the latest release binary from GitHub for the current OS/architecture. It installs to $INSTALL_DIR (defaults to $HOME/.local/bin above). Ensure $HOME/.local/bin is in your PATH . If it's not already in your PATH, add this line to your shell profile (~/.bashrc , ~/.zshrc , etc.):

export PATH="$HOME/.local/bin:$PATH"

Then reload your shell configuration: source ~/.bashrc (or source ~/.zshrc ).

Prerequisites

Before using codesearch, the target repository must be indexed:

Index a repository (run once, supports incremental updates)

codesearch index /path/to/repo

Index with a custom name

codesearch index /path/to/repo --name my-project

Force full re-index (ignores cached file hashes)

codesearch index /path/to/repo --force

Search

Use codesearch search to find code. By default it runs hybrid search (semantic vector similarity + BM25 keyword matching, fused via RRF) for best precision and recall.

Hybrid search — default, no flag needed

codesearch search "user authentication flow" codesearch search "error handling middleware" codesearch search "database connection setup" codesearch search "API request validation"

Semantic-only search (disable keyword leg, pure vector similarity)

codesearch search "user authentication flow" --no-text-search

Limit number of results (default: 10)

codesearch search "error handling" --num 5

Filter by minimum relevance score

Note: hybrid RRF scores are ~0.016–0.033; semantic cosine scores are 0.0–1.0

codesearch search "authentication" --min-score 0.02 # for hybrid results codesearch search "authentication" --no-text-search --min-score 0.5 # for semantic-only

Filter by programming language

codesearch search "struct definition" --language rust codesearch search "class hierarchy" --language python --language typescript

Filter by repository (when multiple repos are indexed)

codesearch search "config loading" --repository my-project

Hybrid vs Semantic-only

Mode Flag Best for

Hybrid (default) (none) Most queries — combines meaning and keyword precision

Semantic-only --no-text-search

Abstract intent queries where exact keywords unlikely to match

Supported Languages

Codesearch supports: Rust, Python, JavaScript, TypeScript, Go, HCL, PHP, C++

What Gets Indexed

Codesearch uses Tree-sitter to extract and index these code constructs:

• Functions and methods

• Structs, classes, and enums

• Traits and implementations

• Modules, constants, and typedefs

• Import statements

Call Graph Analysis

Once a repository is indexed, the call graph is available for two complementary commands.

Impact Analysis — blast radius of a change

Who breaks if authenticate changes? (default depth: 5 hops)

codesearch impact authenticate

Limit to 2 hops

codesearch impact authenticate --depth 2

Restrict to one repository; JSON output for scripts

codesearch impact authenticate --repository my-api --format json

Symbol Context — 360-degree callers + callees

Who calls authenticate, and what does it call?

codesearch context authenticate

Limit results per direction

codesearch context authenticate --limit 10

JSON output

codesearch context authenticate --format json

Repository Management

List all indexed repositories

codesearch list

View indexing statistics

codesearch stats

Delete a repository from the index

codesearch delete <id-or-path>

Query Best Practices

Do:

codesearch search "How are file chunks created and stored?" codesearch search "Vector embedding generation process" codesearch search "Configuration loading and validation" codesearch search "HTTP request routing logic"

Don't:

codesearch search "func" # Too vague codesearch search "error" # Too generic codesearch search "HandleRequest" # Use Grep for exact name matches

Recommended Workflow

• Start with codesearch search to find relevant code semantically

• Use Read tool to examine the files and lines from search results

• Use Grep only for exact string searches when you know the identifier name

• Use codesearch search again with refined queries if initial results aren't specific enough

Advanced Configuration

Use a custom data directory for the index

codesearch --data-dir /custom/path search "query"

Use a namespace to isolate projects

codesearch --namespace my-project search "query"

Use in-memory storage (no persistence, useful for one-off searches)

codesearch --memory-storage search "query"

Disable result reranking (faster but less accurate)

codesearch --no-rerank search "query"

Keywords

semantic search, hybrid search, code search, natural language search, find code, explore codebase, code understanding, intent search, AST analysis, embeddings, code discovery, code exploration, BM25, keyword search, RRF, reciprocal rank fusion, call graph, impact analysis, blast radius, symbol context, callers, callees, dependency analysis