CodeSearch

Fast, intelligent code search and analysis for 48+ programming languages.

Find what you need in seconds: functions, classes, duplicates, dead code, complexity issues.

---

Why CodeSearch?

Stop Wasting Time Searching Code

Problem: You're working in a large codebase and need to:

• Find where authentication logic is implemented
• Identify all usages of a deprecated function before refactoring
• Track down technical debt (TODOs, FIXMEs) scattered across files
• Understand complex function relationships and dependencies
• Find duplicated code that violates DRY principles
• Spot overly complex functions that need refactoring

Traditional tools fall short:

• grep is slow and doesn't understand code structure
• IDE search is limited to single projects/languages
• Manual code review is time-consuming and error-prone

CodeSearch solves these problems:

# Find authentication logic instantly
codesearch "authenticate" ./src --rank
# Result: All authentication code, ranked by relevance

# Track technical debt before sprint planning
codesearch deadcode ./src --format csv --output debt.csv
# Result: 15 unused functions, 23 TODOs, 8 unreachable blocks

# Find duplicates before they become maintenance nightmares
codesearch duplicates ./src
# Result: 12 code clones (80%+ similarity)

What Makes CodeSearch Different?

Unlike Joern (CPG graph DB, Scala queries, security research) or CodeQL (QL logic language, GitHub extractors, path queries), CodeSearch needs no indexing or config—and beats them on time-to-result:

• Unified graph (codesearch graph unified) — AST+CFG+DFG in one, like Joern's CPG but no DB
• Data-flow trace (codesearch flow <var>) — path-style tracing without extractors
• Security scan (codesearch security) — eval/exec/SQL patterns instantly
• First result — sub-second vs. minutes of import/build

See docs/CAPABILITY_REDESIGN.md for full comparison.

Feature	Benefit	Example
Language-Aware	Understands functions, classes, imports in 48+ languages	Find fn main in Rust, def main in Python
Lightning Fast	Parallel processing with Rust, typical searches in 3-50ms	Search 1000 files in < 50ms
Intelligent	Fuzzy matching handles typos, semantic search understands context	codesearch "authetication" finds "authentication"
Code Quality	Detects dead code, duplicates, complexity issues automatically	codesearch complexity flags functions needing refactoring
Graph Analysis	6 types of graphs for deep code understanding	Call graphs show function relationships
Developer-Friendly	Interactive mode, multiple export formats, MCP for AI agents	codesearch interactive for REPL-style search

Real-World Impact

• Save Hours per Week: Replace manual code hunting with instant searches
• Ship Better Code: Catch dead code and complexity issues before review
• Understand Faster: Visualize code relationships with graph analysis
• Reduce Technical Debt: Track and eliminate code quality issues systematically

---

Quick Start

Installation

# Clone and build
git clone https://github.com/yingkitw/codesearch.git
cd codesearch
cargo build --release

# The binary will be at: ./target/release/codesearch
# Optional: Add to PATH
export PATH="$PATH:$PWD/target/release"

Basic Usage

# Simple search - find anything in your codebase
codesearch "function" ./src

# Search with file type filter
codesearch "class" ./src --extensions rs,py

# Fuzzy search (handles typos!)
codesearch "calcualtor" ./src --fuzzy

# Interactive mode
codesearch interactive

---

Usage Examples

1. Everyday Search Tasks

Find Function Definitions

# Find all functions named "process"
codesearch "fn process" ./src --extensions rs

# Find class definitions
codesearch "class User" ./src --extensions py

# Find async functions
codesearch --regex "async\s+fn\s+\w+" ./src --extensions rs

Track Technical Debt

# Find all TODOs and FIXMEs
codesearch "TODO\|FIXME" ./src

# Export to CSV for tracking
codesearch "TODO" ./src --format csv --output todos.csv

Refactor Safely

# Find all usages before refactoring
codesearch "old_function_name" ./src

# Case-sensitive search for exact matches
codesearch "MyStruct" ./src --case-sensitive

2. Code Quality Analysis

Health Score

# Get overall code health score
codesearch health ./src

# Output:
# 🏥 Code Health Report
# Overall Health Score: 85/100 ✅
# 
# Components:
#   • Dead Code: 90/100 (3 issues)
#   • Duplicates: 95/100 (2 duplicates)
#   • Complexity: 70/100 (5 high-complexity functions)

# CI/CD integration with fail threshold
codesearch health ./src --fail-under 80

Detect Dead Code

# Find unused code
codesearch deadcode ./src

# Output:
# ⚠️ Found 12 potential dead code items:
#    [var] L 10: variable 'unused_var'
#    [∅] L 42: empty_helper()
#    [?] L 58: TODO marker
#    [!] L 72: unreachable code

# Export for code review
codesearch deadcode ./src --format markdown --output review.md

Analyze Complexity

# Find complex functions that need refactoring
codesearch complexity ./src

# Output:
# 📊 Files by Complexity:
#   src/auth.rs: Cyclomatic 45, Cognitive 38 (HIGH)
#   src/parser.rs: Cyclomatic 28, Cognitive 22 (MEDIUM)

# Comprehensive code metrics
codesearch analyze ./src --metrics

Find Code Duplicates

# Identify copy-pasted code
codesearch duplicates ./src

# Output:
# 🔍 Found 8 duplicate code blocks:
#   auth.rs:120-145 vs user.rs:89-114 (85% similar)

3. Understanding Codebases

Codebase Overview

# Get high-level metrics
codesearch analyze ./src

# Output:
# Overview
#   Total files: 156
#   Total lines: 45,230
#   Languages: Rust (60%), Python (25%), TypeScript (15%)
#   Functions: 892
#   Classes: 124

Explore Function Relationships

# Generate call graph
codesearch callgraph ./src --format text

# Output:
# Call Graph Analysis:
#   Functions: 28
#   Function calls: 156
#   Recursive: authenticate()
#   Dead (never called): legacy_auth()

Control Flow Analysis

# Understand execution paths
codesearch graph cfg ./src/auth.rs --format text

# Shows: Basic blocks, branches, loops, unreachable code

Unified Graph (CPG-style, no DB)

# AST + CFG + DFG in one—like Joern's CPG, instant
codesearch graph unified ./src/main.rs

# Output: Syntax edges, execution edges, data edges

Data-Flow Trace (path-query style)

# Trace variable flow—no extractors, no indexing
codesearch flow input ./src --sink eval

Security Pattern Scan

# Instant security checks—eval, exec, SQL concat, etc.
codesearch security ./src --extensions js,py,php

Advanced Symbol Search

# Find symbols with rich context and relationships
codesearch symbols "authenticate" ./src --kind function --context 3

# Get detailed symbol information with documentation
codesearch symbol-details "User" ./src/auth.rs --include-related

# Find symbol relationships and hierarchies
codesearch symbol-relations "AuthService" --types inherits,calls

# Build comprehensive symbol index
codesearch index-symbols ./src --extensions rs,py

4. Advanced Workflows

Interactive Mode

codesearch interactive

# Commands in interactive mode:
# authenticate       - Search for "authenticate"
# /f                 - Toggle fuzzy matching
# /i                 - Toggle case sensitivity
# analyze            - Show codebase metrics
# complexity         - Show complexity analysis
# deadcode           - Find dead code
# help               - Show all commands

Search with Ranking

# Get results ranked by relevance
codesearch "auth" ./src --rank

# Best match first:
#   src/auth/mod.rs:10 - pub fn authenticate() { ... }
#   src/user.rs:45     - fn check_auth() { ... }

Export Results

# CSV for spreadsheets
codesearch "TODO" ./src --format csv --output todos.csv

# Markdown for documentation
codesearch analyze ./src --format markdown --output analysis.md

# JSON for automation
codesearch "function" ./src --format json | jq '.matches'

5. Special Features

Search Git History

# Search through commit history
codesearch git-history "TODO" ./src

Search Remote Repositories

# Search GitHub/GitLab without cloning
codesearch remote --github "pattern" owner/repo

Build Index for Large Codebases

# Incremental indexing for faster searches
codesearch index ./src

# Watch for changes and auto-update
codesearch watch ./src

---

Common Commands Reference

Search Commands

codesearch "<query>" [path] [options]

# Options:
--extensions, -e     # Filter by file extensions (e.g., rs,py,js)
--case-sensitive     # Case-sensitive matching
--fuzzy              # Fuzzy matching (handles typos)
--regex              # Use regular expressions
--rank               # Rank results by relevance
--format             # Output format (text, csv, markdown, json)
--output, -o         # Output file path

Analysis Commands

codesearch health [path]            # Overall health score
codesearch deadcode [path]          # Find unused code
codesearch complexity [path]        # Analyze complexity
codesearch duplicates [path]        # Find duplicates
codesearch analyze [path]            # Codebase metrics
codesearch circular [path]          # Circular dependencies
codesearch design-metrics [path]    # Coupling & cohesion

Graph Commands

codesearch ast [file]               # Abstract Syntax Tree
codesearch cfg [file]               # Control Flow Graph
codesearch dfg [file]               # Data Flow Graph
codesearch callgraph [path]         # Call Graph
codesearch depgraph [path]          # Dependency Graph
codesearch pdg [file]               # Program Dependency Graph
codesearch graph-all [file]         # All graph types

Utility Commands

codesearch files [path]             # List searchable files
codesearch languages                # List supported languages
codesearch interactive              # Interactive mode
codesearch index [path]             # Build index
codesearch watch [path]             # Watch for changes
codesearch git-history <query>      # Search git history
codesearch remote --github <query>  # Search GitHub

---

Real-World Examples

Example 1: Pre-Code Review Checklist

#!/bin/bash
# review.sh - Automated code review checklist

echo "=== Code Review Report ==="
echo ""

echo "1. Dead Code Issues:"
codesearch deadcode ./src --format markdown

echo ""
echo "2. Complexity Issues:"
codesearch complexity ./src --threshold 15

echo ""
echo "3. Duplicate Code:"
codesearch duplicates ./src

echo ""
echo "4. Technical Debt:"
codesearch "TODO\|FIXME\|HACK" ./src

Example 2: Learning a New Codebase

# Step 1: Understand the structure
codesearch analyze ./src

# Step 2: Find entry points
codesearch --regex "(main|Main|app\.start)" ./src

# Step 3: Explore key modules
codesearch files ./src --extensions rs | head -20

# Step 4: Understand function relationships
codesearch callgraph ./src --format text | head -50

# Step 5: Find complex code to review
codesearch complexity ./src --sort | head -10

Example 3: Refactoring Workflow

# Before refactoring, find all usages
codesearch "OldAuthService" ./src --output old_usage.txt

# Check for complexity issues
codesearch complexity ./src/auth --format markdown > complexity_report.md

# Find similar code that could be consolidated
codesearch duplicates ./src/auth --output duplicates.txt

# After refactoring, verify no old code remains
codesearch "OldAuthService" ./src
# Should return: "No matches found"

Example 4: Continuous Quality Monitoring

# Add to CI/CD pipeline

# Fail if high complexity functions detected
complexity=$(codesearch complexity ./src --format json)
max_cc=$(echo "$complexity" | jq '.max_complexity')
if [ "$max_cc" -gt 20 ]; then
    echo "❌ High complexity detected: $max_cc"
    exit 1
fi

# Fail if new dead code introduced
deadcode_count=$(codesearch deadcode ./src --format json | jq '.total')
if [ "$deadcode_count" -gt 10 ]; then
    echo "❌ Too much dead code: $deadcode_count items"
    exit 1
fi

echo "✅ Code quality checks passed"

---

Demo Project

A comprehensive example project demonstrating all CodeSearch capabilities is available in the examples/demo-project/ directory.

Run the demo:

cd examples/demo-project
./demo.sh

Demo includes:

• Multi-language codebase (Rust, Python, TypeScript)
• Intentional code quality issues for detection
• All analysis types demonstrated
• Real-world usage examples

---

Architecture & Quality

Code Quality Standards

• ✅ 100% test pass rate (232 tests total: 173 unit + 36 integration + 23 MCP)
• ✅ Zero clippy warnings (clean code quality)
• ✅ Modular architecture (45+ focused modules)
• ✅ Thread-safe parallel processing with rayon
• ✅ Comprehensive error handling with custom error types
• ✅ Trait abstractions for extensibility and testability
• ✅ Advanced symbol system for deep code understanding

Performance

• Fast: 3-50ms for typical searches (< 1000 files)
• Parallel: Auto-scales to available CPU cores
• Smart caching: 70-90% cache hit rate for repeated searches
• Memory efficient: Streaming file reading, < 100MB for 10K files

Supported Languages

Native Parsers (High Performance):

• Rust - Full AST parsing with zero-allocation tokenizer
• Python - Complete syntax support including async/await
• JavaScript/TypeScript - ES6+, JSX, TSX support
• Go - Structs, interfaces, methods with receivers
• Java - Classes, interfaces, enums, annotations

48+ Additional Languages via regex patterns including: C/C++, Ruby, PHP, Swift, Kotlin, C#, Haskell, Elixir, Erlang, Scala, Lua, Perl, Shell, SQL, YAML, TOML, JSON, and more.

See codesearch languages for the complete list.

---

Additional Resources

• Demo Project - Hands-on examples
• DEMO_GUIDE.md - Comprehensive usage guide
• ARCHITECTURE.md - Technical details and design
• SPEC.md - Technical specification
• CLAUDE.md - Contributor guide
• MCP_ENHANCEMENTS.md - Advanced symbol system documentation

---

Model Context Protocol (MCP) Integration

CodeSearch provides 15 MCP tools for AI agent integration, enabling sophisticated code analysis without LLM processing:

Core Tools (9 tools)

1. search_code - Pattern search with filters and ranking
2. list_files - Directory enumeration and file discovery
3. analyze_codebase - Comprehensive codebase metrics and statistics
4. detect_complexity - Cyclomatic and cognitive complexity analysis
5. detect_duplicates - Code duplication detection
6. detect_deadcode - Dead code detection (6+ types)
7. detect_circular - Circular dependency detection
8. find_symbol - Symbol finding (definition, references, callers)
9. get_health - Overall code health scoring

Advanced Symbol Tools (6 tools)

1. search_symbols - Advanced symbol search with context and relationships
2. get_symbol_details - Comprehensive symbol information with documentation
3. find_symbol_relationships - Symbol relationship and hierarchy queries
4. build_symbol_index - Create/update symbol index with change detection
5. get_index_stats - Index metadata and performance statistics
6. find_symbol_hierarchy - Complete inheritance and implementation analysis

MCP Server Usage

# Start the MCP server
codesearch mcp

# Available via stdio transport
# Integrates with Claude Code, Cursor, Windsurf, and other MCP-compatible tools

Features:

• No LLM Dependency: All search and analysis is deterministic
• Language-Aware: Understands code structure, not just text
• Relationship-First: Maintains complete symbol relationship graph
• Performance-Optimized: Concurrent processing and efficient indexing
• AI-Ready: Rich context and metadata for agent consumption

---

---

License

Apache-2.0 License

---

Built with Rust • Fast • Precise • 48+ Languages
Version: 0.1.10