Codesearch

Semantic code search powered by ML embeddings and Tree-sitter AST analysis. Finds code by meaning, not just text matching.

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

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.):

shell

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

Semantic Search

Use codesearch search to find code by describing what it does in natural language:

# Search with natural language
codesearch search "user authentication flow"
codesearch search "error handling middleware"
codesearch search "database connection setup"
codesearch search "API request validation"

# Limit number of results (default: 10)
codesearch search "error handling" --num 5

# Filter by minimum relevance score (0.0-1.0)
codesearch search "authentication" --min-score 0.5

# 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

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

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

1. •Start with codesearch search to find relevant code semantically
2. •Use Read tool to examine the files and lines from search results
3. •Use Grep only for exact string searches when you know the identifier name
4. •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, code search, natural language search, find code, explore codebase, code understanding, intent search, AST analysis, embeddings, code discovery, code exploration