zoekt-code-search

name	zoekt-code-search
description	Fast trigram-indexed code search across a repository using Zoekt. Use instead of grep/ripgrep for broad codebase searches. Supports regex, literal strings, file filters, and symbol queries. Auto-installs zoekt binaries and uses a local index on first use.

Zoekt Code Search

Fast, trigram-indexed code search powered by Zoekt — the engine behind GitHub and Sourcegraph code search.

When to Use This Skill

• Search the codebase for a string, pattern, or symbol
• Find all references to a function, type, or variable
• Find where something is defined
• Find implementations of an interface or method
• Broad code search across the project

When NOT to Use This Skill

• Searching within a single known file
• Searching non-code content like logs or binary files
• The answer is already in current context

Quick Start

# Index the current repository
bash skills/zoekt-code-search/scripts/zoekt-index.sh

# Search for a string
bash skills/zoekt-code-search/scripts/zoekt-search.sh "AgentSession"

Search Examples

# Literal string search
bash skills/zoekt-code-search/scripts/zoekt-search.sh "AgentSession"

# Regex search
bash skills/zoekt-code-search/scripts/zoekt-search.sh "func.*Start"

# Symbol / type definitions
bash skills/zoekt-code-search/scripts/zoekt-search.sh "type AgentSession struct"

# Filter by filename pattern
bash skills/zoekt-code-search/scripts/zoekt-search.sh "handleRequest file:\.go$"

# Filter by file path
bash skills/zoekt-code-search/scripts/zoekt-search.sh "TODO file:internal/"

# Exclude files
bash skills/zoekt-code-search/scripts/zoekt-search.sh "Session -file:test"

# Plain text output
bash skills/zoekt-code-search/scripts/zoekt-search.sh --no-json "AgentSession"

Zoekt Query Syntax

Zoekt queries are made of expressions. Multiple expressions separated by spaces are implicit AND. Use or for alternatives, - for negation, and parentheses for grouping.

How Zoekt Works

• Zoekt is optimized for code search with positional trigram indexes, so broad literal, regex, file-filtered, and symbol searches should use Zoekt before grep, ripgrep, or find.
• Regex queries are accelerated when they contain extractable literal substrings. Prefer regexes that include stable literal anchors, for example content:"error.*handler".
• Each query needs at least one positive atom. Negations like -file:test prune results from positive matches; pure negation cannot generate useful results by itself.
• Case defaults to case:auto: lowercase patterns tend to be case-insensitive, while uppercase characters make matching case-sensitive unless case:no or case:yes is specified.
• Results are ranked with code-aware signals such as atom matches, proximity between terms, word boundaries, filename quality, and symbol matches when symbol data is available.
• Indexes are local shard files under .zoekt/ and can be several times larger than the indexed text. The leading dot is required; do not use zoekt/. Keep .zoekt/ ignored by git. The indexer also writes .zoekt/.gitignore with * so all index contents are ignored.

Fields

Field	Aliases	Values	Meaning	Example
bare text		text	Search content and filenames	AgentSession
quoted text		string	Exact text	"exact phrase"
content:	c:	string or regex	Search file content	content:"search term"
file:	f:	string or regex	Search/filter file names and paths	file:"main.go"
regex:		regex	Match content with regex	regex:"foo.*bar"
lang:	l:	text	Filter by language	lang:typescript
sym:		text	Search symbol names	sym:"MyFunction"
case:	c:	yes, no, auto	Control case sensitivity	case:yes content:"Foo"
repo:	r:	string or regex	Filter repositories when metadata exists	repo:"github.com/user/project"
branch:	b:	text	Filter branch when metadata exists	branch:main
archived:	a:	yes or no	Filter archived repositories	archived:no
fork:	f:	yes or no	Filter forked repositories	fork:no
public:		yes or no	Filter public repositories	public:yes
type:	t:	filematch, filename, file, repo	Control result type	type:filename README

Operators

Syntax	Meaning	Example
space	Implicit AND	content:test lang:python
or	Alternative expressions	lang:go or lang:java
-	Negation	Session -file:test
(...)	Grouping	content:test (lang:python or lang:javascript)

Values

Text fields accept quoted strings. Regex metacharacters work inside quoted values. Escape embedded quotes with backslashes.

Important: Slash-delimited regex syntax (content:/pattern/) does not work. The / character has no special meaning in Zoekt's query parser — slashes are treated as literal characters, not regex delimiters. Always use quoted strings or bare field values.

Goal	Query
Match literal text	content:"foo bar"
Match embedded quote	content:"foo\"bar"
Match regex	content:"func\s+.*\("
Match Go files containing package main	file:".*\\.go" content:"package main"

Known limitation: \w and \w+ character classes can silently fail with certain literal prefixes due to Zoekt's trigram extraction. Prefer .* over \w* for reliability.

Result Type Scope

type: applies to the whole expression in its current scope, including or clauses. type:repo foo or bar is equivalent to type:repo (foo or bar). Use parentheses to scope it to one branch, for example (type:repo foo) or bar.

Examples

AgentSession
"exact phrase"
content:"TODO" file:internal/
Session -file:test
case:yes content:"HTTPClient"
sym:"MyFunction" lang:typescript
content:"needle" (file:\.ts$ or file:\.tsx$)
content:"error.*handler" -lang:javascript
public:yes archived:no fork:no
type:filename file:"README.md"

Reindex

bash skills/zoekt-code-search/scripts/zoekt-index.sh

Index a specific directory:

bash skills/zoekt-code-search/scripts/zoekt-index.sh /path/to/source

Reading Results

JSONL Output (default)

Each line is a JSON object. Useful fields:

• FileName — file path relative to repo root
• LineNum — 1-based line number of the match
• Line — matched line content

Results are ranked by relevance.

Plain Text Output (--no-json)

Human-readable format with file paths, line numbers, and matched content.

Configuration

Setting	Default	Override
Index directory	<repo-root>/.zoekt/	--index-dir <path> or ZOEKT_INDEX_DIR
Binary location	skills/zoekt-code-search/bin/	Binaries on PATH are also detected

Prerequisites

• Go toolchain — required for building zoekt from source
• Binaries are auto-installed to skills/zoekt-code-search/bin/ on first use

Tips

• Prefer Zoekt over grep/ripgrep for broad searches
• Reindex after major changes if results seem stale
• Combine file: filters with search terms to narrow results

Error Handling

Error	Resolution
"No index found"	Run zoekt-index.sh first
"Go is not installed"	Install Go from https://go.dev/dl/
"Not inside a git repository"	Run from within a git repo or pass --index-dir