searchfox 0.17.0

Python bindings for searchfox.org API

searchfox-cli

A command-line interface for searching Mozilla codebases using searchfox.org, written by and for Claude Code.

Also available as a Rust library (searchfox-lib) and Python package (searchfox-py).

Features

• Search across multiple Mozilla repositories (mozilla-central, beta, release, ESR branches, comm-central)
• Symbol search using searchfox's native indexing for precise lookups
• Advanced definition finding with complete function/class extraction using intelligent brace matching
• Call graph analysis: Understand code flow with calls-from, calls-to, and calls-between queries (LLM-friendly markdown output)
• Field layout inspection: Display C++ class/struct memory layout with size, alignment, and field offsets
• Language filtering (C++, C, WebIDL, JavaScript)
• Path patterns and regular expressions
• Request logging for performance analysis

Installation

cargo install searchfox-cli

CLI Usage

Basic Search

# Search for "AudioStream" in mozilla-central
searchfox-cli -q AudioStream

# Search with case sensitivity
searchfox-cli -q AudioStream -C

# Search with regular expressions
searchfox-cli -q '^Audio.*' -r

# Limit results to 10 matches
searchfox-cli -q AudioStream -l 10

Symbol and Definition Search

# Find symbol definitions
searchfox-cli --symbol AudioContext

# Find exact identifier matches (not prefix-based)
searchfox-cli --id main

# Search for symbols using searchfox's symbol index
searchfox-cli --symbol 'AudioContext'
searchfox-cli --symbol 'CreateGain'

# Search for symbols in specific paths
searchfox-cli -q 'path:dom/media symbol:AudioStream'

Repository Selection

# Search in beta branch
searchfox-cli -q AudioStream -R mozilla-beta

Path Filtering

# Search only in dom/media directory
searchfox-cli -q AudioStream -p ^dom/media

# Search in specific file patterns
searchfox-cli -q AudioStream -p '\.cpp$'

# Use -p alone to search for files by path pattern
searchfox-cli -p PContent.ipdl
searchfox-cli -p AudioContext.cpp

# Using advanced path syntax in query
searchfox-cli -q 'path:dom/media AudioStream'
searchfox-cli -q 'pathre:^dom/(media|audio) AudioStream'

Language Filtering

Filter search results by programming language using language-specific flags:

# Search only in C++ files (.cc, .cpp, .h, .hh, .hpp)
searchfox-cli -q AudioContext --cpp
searchfox-cli --define AudioContext -p dom/media --cpp

# Search only in C files (.c, .h)
searchfox-cli -q malloc --c

# Search only in WebIDL files (.webidl)
searchfox-cli -q AudioContext --webidl

# Search only in JavaScript files (.js, .mjs, .ts, .cjs, .jsx, .tsx)
searchfox-cli -q AudioContext --js

# Without language filters, all file types are included
searchfox-cli --define AudioContext -p dom/media

Advanced Query Features

# Search with context lines
searchfox-cli -q AudioStream --context 3

# Text search with regex
searchfox-cli -q 're:AudioContext::.*Create'

# Exact text search (escapes regex chars)
searchfox-cli -q 'text:function main()'

# Combined advanced queries
searchfox-cli -q 'context:3 pathre:dom/media symbol:AudioStream'

Symbol Search

The --symbol flag uses searchfox's native symbol indexing for precise symbol lookups:

# Search for symbols by name
searchfox-cli --symbol 'AudioContext'
searchfox-cli --symbol 'CreateGain'

# Combine with path filtering
searchfox-cli -q 'path:dom/media symbol:AudioStream'

Symbol search relies on searchfox's own symbol database, which includes properly mangled C++ symbols and other language constructs as indexed by the searchfox infrastructure.

Advanced Definition Finding

The --define flag provides an advanced way to find symbol definitions by:

1. Symbol Search: Uses id: prefix internally for precise symbol lookups
2. Class/Struct Priority: Prioritizes class and struct definitions over constructors
3. Definition Resolution: Searches both "Definitions" and "Declarations" categories (for C++ classes)
4. Context Extraction: Fetches the source file and displays the complete method/function/class

# Find class definition with full body
searchfox-cli --define AudioContext -p dom/media

# Find method definition with full context
searchfox-cli --define 'AudioContext::CreateGain'

# Filter by language
searchfox-cli --define AudioContext -p dom/media --cpp

# The tool will:
# 1. Search using id:AudioContext for precise matches
# 2. Prioritize class definitions over constructor declarations
# 3. Extract the complete class body (with brace matching)
# 4. Display the full definition with proper highlighting

This approach leverages searchfox's comprehensive symbol database for reliable definition finding.

Example Output:

For class definitions:

$ searchfox-cli --define AudioContext -p dom/media --cpp
>>>  135: class AudioContext final : public DOMEventTargetHelper,
     136:                            public nsIMemoryReporter,
     137:                            public RelativeTimeline {
     138:   AudioContext(nsPIDOMWindowInner* aParentWindow, bool aIsOffline,
     139:                uint32_t aNumberOfChannels = 0, uint32_t aLength = 0,
     140:                float aSampleRate = 0.0f);
     141:   ~AudioContext();
     142: 
     143:  public:
     144:   typedef uint64_t AudioContextId;
     145: 
     146:   NS_DECL_ISUPPORTS_INHERITED
     147:   NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(AudioContext, DOMEventTargetHelper)
     148:   MOZ_DEFINE_MALLOC_SIZE_OF(MallocSizeOf)
     ...
     335:   void RegisterNode(AudioNode* aNode);
   ...  : (method too long, truncated)

For method definitions:

$ searchfox-cli --define 'AudioContext::CreateGain'
>>>  469: already_AddRefed<GainNode> AudioContext::CreateGain(ErrorResult& aRv) {
     470:   return GainNode::Create(*this, GainOptions(), aRv);
     471: }

The tool automatically:

• Searches searchfox's structured data for definition entries
• Uses searchfox's native symbol indexing for accurate results
• Finds the actual source file location (not generated binding files)
• Fetches the source code and displays complete methods/functions
• Highlights the exact definition line with >>>

Complete Function and Class Extraction

When using --define, the tool automatically detects and extracts complete function/method bodies and class definitions using intelligent brace matching:

For simple functions:

$ searchfox-cli --define 'AudioContext::CreateGain'
>>>  469: already_AddRefed<GainNode> AudioContext::CreateGain(ErrorResult& aRv) {
     470:   return GainNode::Create(*this, GainOptions(), aRv);
     471: }

For complex constructors with initializer lists:

$ searchfox-cli --define 'AudioContext::AudioContext'
>>>  154: AudioContext::AudioContext(nsPIDOMWindowInner* aWindow, bool aIsOffline,
     155:                            uint32_t aNumberOfChannels, uint32_t aLength,
     156:                            float aSampleRate)
     157:     : DOMEventTargetHelper(aWindow),
     158:       mId(gAudioContextId++),
     159:       mSampleRate(GetSampleRateForAudioContext(
     160:           aIsOffline, aSampleRate,
     161:           aWindow->AsGlobal()->ShouldResistFingerprinting(
     162:               RFPTarget::AudioSampleRate))),
     163:       mAudioContextState(AudioContextState::Suspended),
     164:       ...
     179:       mSuspendedByChrome(nsGlobalWindowInner::Cast(aWindow)->IsSuspended()) {
     180:   bool mute = aWindow->AddAudioContext(this);
     181:   // ... full method body continues ...
     205: }

Features of complete extraction:

• Multi-language support: Handles C++, Rust, and JavaScript function syntax
• Class and struct definitions: Extracts complete class/struct bodies with proper brace matching
• Smart brace matching: Ignores braces in strings, comments, and character literals
• Complex signatures: Handles multi-line function signatures and initializer lists
• Constructor support: Properly extracts C++ constructors with member initialization lists
• Class termination: Handles classes/structs ending with semicolons correctly
• Safety limits: Truncates extremely long definitions (>200 lines) to prevent output overflow
• Accurate parsing: Correctly handles nested braces, escape sequences, and comment blocks

File Retrieval

# Fetch and display a specific file
searchfox-cli --get-file dom/media/AudioStream.h

Available Repositories

• mozilla-central (default) - Main Firefox development
• mozilla-beta - Beta release branch
• mozilla-release - Release branch
• mozilla-esr115 - ESR 115 branch
• mozilla-esr128 - ESR 128 branch
• mozilla-esr140 - ESR 140 branch
• comm-central - Thunderbird development

Command Line Options

• -q, --query <QUERY> - Search query string (supports advanced syntax)
• -R, --repo <REPO> - Repository to search in (default: mozilla-central)
• -p, --path <PATH> - Filter results by path prefix using regex, or search for files by path pattern
• -C, --case - Enable case-sensitive search
• -r, --regexp - Enable regular expression search
• -l, --limit <LIMIT> - Maximum number of results to display (default: 50)
• --get-file <FILE> - Fetch and display contents of a specific file
• --symbol <SYMBOL> - Search for symbol definitions using searchfox's symbol index
• --id <IDENTIFIER> - Search for exact identifier matches
• --context <N> - Show N lines of context around matches
• --define <SYMBOL> - Find and display the definition of a symbol with full context
• --log-requests - Enable detailed HTTP request logging with timing and size information
• --cpp - Filter results to C++ files only (.cc, .cpp, .h, .hh, .hpp)
• --c - Filter results to C files only (.c, .h)
• --webidl - Filter results to WebIDL files only (.webidl)
• --js - Filter results to JavaScript files only (.js, .mjs, .ts, .cjs, .jsx, .tsx)
• --calls-from <SYMBOL> - Show what functions are called by the specified symbol
• --calls-to <SYMBOL> - Show what functions call the specified symbol
• --calls-between <SOURCE,TARGET> - Show direct calls from source class/namespace to target class/namespace
• --depth <N> - Set traversal depth for call graph searches (default: 1)
• --field-layout <CLASS> - Display C++ class/struct memory layout (aliases: --class-layout, --struct-layout)

Call Graph Analysis

Understand code flow and dependencies with LLM-friendly markdown output:

# What does a function call?
searchfox-cli --calls-from 'mozilla::AudioCallbackDriver::DataCallback'

# What calls this function?
searchfox-cli --calls-to 'mozilla::AudioCallbackDriver::Start'

# How do two classes interact?
searchfox-cli --calls-between 'mozilla::dom::AudioContext,mozilla::MediaTrackGraph' --depth 2

Output features:

• Results grouped by parent class/namespace
• Both definition and declaration locations shown
• Overloaded functions collapsed with all variants listed
• Mangled symbols included for subsequent queries
• Direct call edges (for calls-between)

Examples

# Find all AudioStream references
searchfox-cli -q AudioStream

# Find function definitions starting with "Audio"
searchfox-cli -q '^Audio.*' -r

# Search only in media-related files
searchfox-cli -q AudioStream -p ^dom/media

# Get a specific file
searchfox-cli --get-file dom/media/AudioStream.h

# Search in Thunderbird codebase
searchfox-cli -q "MailServices" -R comm-central

# Find where AudioContext is defined
searchfox-cli --symbol AudioContext

# Find exact matches for "main" function
searchfox-cli --id main

# Search with context lines
searchfox-cli -q AudioStream --context 5

# Symbol search using searchfox's symbol index
searchfox-cli --symbol 'AudioContext'
searchfox-cli --symbol 'CreateGain'

# Find complete definition with context
searchfox-cli --define 'AudioContext::CreateGain'
searchfox-cli --define 'AudioContext'

# Language filtering
searchfox-cli --define AudioContext -p dom/media --cpp
searchfox-cli -q malloc --c
searchfox-cli -q AudioContext --js

# File path search
searchfox-cli -p PContent.ipdl
searchfox-cli -p AudioContext.cpp

# Advanced query syntax
searchfox-cli -q 'path:dom/media symbol:AudioStream'
searchfox-cli -q 're:AudioContext::.*Create'

# Class memory layout inspection
searchfox-cli --field-layout 'mozilla::dom::AudioContext'
searchfox-cli --class-layout 'soundtouch::SoundTouch'

# Performance analysis with request logging
searchfox-cli --log-requests --define 'AudioContext::CreateGain'
searchfox-cli --log-requests -q AudioStream -l 10

# Cache control for file fetches
searchfox-cli --get-file dom/media/AudioStream.h --force-refetch
searchfox-cli --get-file dom/media/AudioStream.h --no-cache
searchfox-cli --clear-cache

Request Logging

searchfox-cli --log-requests --define 'AudioContext::CreateGain'

Shows HTTP request timing, response sizes, and baseline latency for performance analysis.

File Cache Policy

--get-file uses an on-disk SQLite cache at $XDG_CACHE_HOME/searchfox-cli/cache.db, or ~/.cache/searchfox-cli/cache.db when XDG_CACHE_HOME is unset.

• Fresh TTL: cached file contents are reused for 1 hour without a network request.
• Revalidation: after 1 hour, the client sends conditional requests with ETag and Last-Modified when available. A 304 Not Modified response refreshes the cache timestamp without reparsing the file.
• Retention: cache entries older than 7 days are pruned when the client opens the cache database.
• Scope: the cache currently applies to --get-file / SearchfoxClient::get_file.

Manual cache control:

searchfox-cli --clear-cache
searchfox-cli --get-file dom/media/AudioStream.h --force-refetch
searchfox-cli --get-file dom/media/AudioStream.h --no-cache

• --clear-cache deletes the cache database and exits.
• --force-refetch bypasses any cached file entry for the current invocation, fetches fresh content from searchfox, and updates the cache if caching is enabled.
• --no-cache disables cache reads and writes for the current invocation.

Python API

import searchfox

client = searchfox.SearchfoxClient("mozilla-central")
results = client.search(query="AudioStream", limit=10)
definition = client.get_definition("AudioContext::CreateGain")
content = client.get_file("dom/media/AudioStream.h")

Installation:

cd searchfox-py && maturin develop  # Development
cd searchfox-py && maturin build --release  # Distribution wheel

See python/examples/ for complete examples.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.