code_search

A CLI tool for querying Elixir/Erlang call graph data stored in SurrealDB. Designed for LLMs to efficiently explore and understand codebases without consuming context windows by reading source files directly.

Why?

When LLMs analyze codebases, they typically read source files one by one, quickly exhausting their context window. This tool provides structured queries over pre-extracted call graph data, allowing LLMs to:

• Find function definitions and their locations
• Trace call chains (who calls what, and who calls them)
• Discover module dependencies
• Identify unused code, hotspots, and code smells
• Search by pattern without reading files

One query can answer questions that would otherwise require reading dozens of files.

Installation

cargo build --release

Quick Start

1. Set up the database

# Create database schema in .code_search/surrealdb.rocksdb
code_search setup

# Or, create schema AND install Claude Code templates (skills + agents)
code_search setup --install-skills

# Or, install git hooks for automatic incremental updates after each commit
code_search setup --install-hooks

# Or, install everything (skills + hooks)
code_search setup --install-skills --install-hooks

The database is automatically created at .code_search/surrealdb.rocksdb in your project root.

2. Import call graph data

Import a call graph JSON file (generated by ex_ast):

code_search code import --file call_graph.json

3. Query the data

# Find where a function is defined
code_search code location get_user MyApp.Accounts

# What does this function call?
code_search code calls-from MyApp.Accounts get_user

# Who calls this function?
code_search code calls-to MyApp.Repo get

# Trace the full call chain from a function
code_search code trace MyApp.Web.UserController show

# Find unused functions
code_search code unused -P

# Find hotspots (most called functions)
code_search code hotspots -l 10

Output Formats

All commands support three output formats via --format or -o:

• table (default): Human-readable output for terminal use
• json: Structured JSON for programmatic use
• toon: Token-optimized format for LLM consumption (minimal tokens while preserving structure)

Commands

Use code_search code <command> --help for detailed help on any command.

Query Commands

Command	Usage	Description
calls-to	calls-to <MODULE> [FUNCTION] [ARITY]	Find what calls a function
calls-from	calls-from <MODULE> [FUNCTION] [ARITY]	Find what a function calls
trace	trace <MODULE> <FUNCTION>	Forward call chain traversal
reverse-trace	reverse-trace <MODULE> <FUNCTION>	Backward call chain traversal
path	path --from-module M --from-function F --to-module M --to-function F	Find call path between two functions

Search Commands

Command	Usage	Description
search	search <PATTERN> [-k modules|functions]	Search modules/functions by name
location	location <FUNCTION> [MODULE]	Find function definition location
function	function <MODULE> <FUNCTION>	Show function signature
browse-module	browse-module <MODULE>	List all definitions in a module

Type Search Commands

Command	Usage	Description
accepts	accepts <PATTERN> [MODULE]	Find functions accepting a type
returns	returns <PATTERN> [MODULE]	Find functions returning a type
struct-usage	struct-usage <PATTERN> [MODULE]	Find functions using a type

Module Commands

Command	Usage	Description
depends-on	depends-on <MODULE>	Show module's outgoing dependencies
depended-by	depended-by <MODULE>	Show module's incoming dependencies
clusters	clusters [MODULE]	Analyze namespace-based clustering
cycles	cycles [MODULE]	Detect circular dependencies

Analysis Commands

Command	Usage	Description
hotspots	hotspots [MODULE] [-k incoming|outgoing|total|ratio]	Find high-connectivity functions
unused	unused [MODULE] [-p|-P]	Find uncalled functions
boundaries	boundaries [MODULE]	Find boundary modules (high fan-in, low fan-out)
god-modules	god-modules [MODULE]	Find modules with high function count and connectivity
duplicates	duplicates [MODULE]	Find duplicate function implementations
complexity	complexity [MODULE]	Display cyclomatic complexity metrics
large-functions	large-functions [MODULE]	Find functions with many lines
many-clauses	many-clauses [MODULE]	Find functions with many pattern-matched heads

Setup & Data Commands

Command	Usage	Description
setup	setup [--install-skills] [--install-hooks] [--force]	Create database schema, install templates and/or git hooks
import	import --file <FILE>	Import call graph JSON

Setup flags:

• --install-skills: Install skill and agent templates to .claude/ (28 skills + 1 agent)
• --install-hooks: Install post-commit git hook for automatic incremental updates
• --mix-env <ENV>: Mix environment for git hook (used with --install-hooks, default: dev)
• --force: Overwrite existing template/hook files (preserves by default)
• --dry-run: Show what would be created without making changes

Common Options

Most commands support these options:

• -l, --limit <N>: Maximum results to return (default: 100, max: 1000)
• -r, --regex: Treat patterns as regular expressions
• --db <PATH>: Database file path (auto-resolved if not specified)
• -o, --format <FORMAT>: Output format (table, json, toon)

Database path resolution:

The code_search setup command creates the database at .code_search/surrealdb.rocksdb by default.

If --db is not specified, commands automatically search for the database in this order:

1. .code_search/surrealdb.rocksdb (project-local, recommended)
2. ./surrealdb.rocksdb (current directory, legacy)
3. ~/.code_search/surrealdb.rocksdb (user-global)

Examples

# Find all functions that accept a User.t type
code_search code accepts "User.t"

# Find modules with circular dependencies
code_search code cycles MyApp.Core

# Find the most complex functions in a namespace
code_search code complexity MyApp.Accounts --min 10

# Trace how a controller action flows through the codebase
code_search code trace MyApp.Web.UserController create --depth 10

# Find all paths from an API endpoint to a database call
code_search code path --from-module MyApp.API --from-function create_user \
                 --to-module MyApp.Repo --to-function insert

# Find god modules (too large, too connected)
code_search code god-modules --min-functions 30 --min-loc 500

# Find boundary modules that many depend on
code_search code boundaries --min-ratio 3.0

Claude Code Integration

This tool includes built-in templates for Claude Code, making it easy to explore codebases with AI assistance.

Installing Templates

# Install skills and agents to .claude/skills/ and .claude/agents/
code_search setup --install-skills

# Force overwrite existing templates
code_search setup --install-skills --force

This installs:

• 28 skill templates documenting each command with examples
• 1 Haiku-powered agent for fast, cost-efficient codebase exploration

Git Hooks for Automatic Updates

Keep your code graph database automatically in sync with each commit:

# Install post-commit hook (database auto-resolves to .code_search/surrealdb.rocksdb)
code_search setup --install-hooks

# Or install both skills and hooks together
code_search setup --install-skills --install-hooks

The post-commit hook automatically:

• Compiles your project with debug info
• Extracts AST data for changed files using ex_ast --git-diff
• Updates the database incrementally (no need to re-analyze the entire codebase)
• Database path is auto-resolved to .code_search/surrealdb.rocksdb

No configuration required! The hook works out of the box. Optional configuration:

git config code-search.mix-env test  # Default: dev

See docs/GIT_HOOKS.md for detailed documentation and troubleshooting.

Git Worktrees

When using git worktrees, each worktree must have its own local database. Run setup and import once in each worktree directory:

mix compile
ex_ast --output /tmp/call_graph.json
code_search setup
code_search code import --file /tmp/call_graph.json

See docs/WORKTREES.md for full details and troubleshooting.

Using with Claude Code

Once templates are installed, Claude Code can automatically help you explore your codebase:

"Where is the authenticate function defined?"
"What calls process_payment?"
"Trace execution from handle_request in ApiController"
"Find unused functions"
"What are the most complex modules?"

The code-search-explorer agent will automatically activate and use the appropriate commands to answer your questions.

Template Structure

After installation:

.claude/
├── agents/
│   └── code-search-explorer.md     # Haiku agent for exploration
└── skills/
    ├── accepts/                      # Type search skills
    ├── browse-module/                # Module exploration
    ├── code-search-explorer/         # Quick reference docs
    ├── ... (24 other command skills)
    └── workflows/                    # Common workflow guides

Architecture

• Written in Rust using clap for CLI parsing
• Uses SurrealDB (RocksDB-backed) for graph queries
• Call graph data is extracted separately by ex_ast
• One database per project (stored in .code_search/surrealdb.rocksdb)
• Embeds templates in binary for self-contained distribution