CIDX - Semantic Code Search and Intelligence

Comprehensive CIDX (Code Indexer) documentation for AI coding assistants.

INDEX MANAGEMENT - CRITICAL FIRST STEP

Before querying, verify indexes exist. Queries fail or return empty results without proper indexes.

Check Index Status

cidx status                  # Semantic/FTS index status (shows indexed files, last update)
cidx scip status             # SCIP indexes per project (shows SUCCESS/FAILED/PENDING)
cidx scip status -v          # Detailed status with error messages

Status interpretation:

• Semantic/FTS: Shows file count, languages, last indexed time
• SCIP SUCCESS: Project indexed successfully, queries will work
• SCIP FAILED: Generation failed (check -v for errors, fix issues, rebuild)
• SCIP PENDING: Not yet generated (run

  cidx scip generate

  )
• SCIP LIMBO: Partial success (some projects succeeded, some failed)

Create Indexes

# Semantic + FTS indexes (required for cidx query)
cidx init                    # Initialize .code-indexer/ in project
cidx index                   # Index current codebase
cidx index --index-commits   # Also index git history (enables temporal search)

# SCIP indexes (required for cidx scip commands)
cidx scip generate           # Generate SCIP indexes for all discovered projects
cidx scip generate --project backend/  # Generate only for specific project

Re-index / Update Indexes

# Semantic/FTS re-indexing
cidx index                   # Re-indexes changed files (incremental)
cidx index --force           # Full re-index (ignores cache)

# SCIP re-indexing
cidx scip rebuild PROJECT    # Rebuild specific project
cidx scip rebuild --failed   # Rebuild all failed projects
cidx scip rebuild --force PROJECT  # Force rebuild even if succeeded

Supported Languages

Semantic/FTS: All text-based source files (auto-detected)

SCIP (requires language-specific tooling):

Language	Project Marker	Requirement
Java	pom.xml	Maven
TypeScript	package.json	npm/yarn
Python	pyproject.toml	Poetry
Kotlin	build.gradle.kts	Gradle
C#	*.sln, *.csproj	.NET SDK 8.0+
Go	go.mod	Go SDK 1.18+

---

SEMANTIC SEARCH - MANDATORY FIRST ACTION

CIDX FIRST: Always use

cidx query

before grep/find/rg for semantic searches.

Decision Rule:

• "What code does", "Where is X implemented" → CIDX semantic (default)
• Exact text (identifiers, function names) →

  --fts

• Pattern matching (regex) →

  --fts --regex

  (10-50x faster than grep)
• CIDX unavailable → grep/find (fallback only)

Key Flags:

--limit N

(default 10, start with 5-10 to conserve context) |

--language python

|

--path-filter */tests/*

|

--exclude-path PATTERN

|

--exclude-language LANG

|

--min-score 0.8

|

--accuracy high

|

--quiet

Context Conservation: Start with low

--limit

values (5-10) on initial queries. High limits consume context window rapidly when results contain large code files.

Example:

cidx query "authentication" --language python --exclude-path "*/tests/*" --limit 5 --quiet

---

FULL-TEXT SEARCH (FTS)

Use For: Exact names, identifiers, TODO comments, typo debugging.

Flags:

--fts

|

--case-sensitive

|

--fuzzy

|

--edit-distance N

|

--snippet-lines N

Example:

cidx query "authenticate_user" --fts --case-sensitive --quiet

Hybrid:

--fts --semantic

runs both in parallel.

---

REGEX MODE (Grep Replacement)

Flags:

--fts --regex

| Incompatible with

--semantic

and

--fuzzy

Token-Based: Matches individual tokens only.

• Works:

  def

  ,

  login.*

  ,

  test_.*

• Doesn't work:

  def\s+\w+

  (whitespace removed)

Example:

cidx query "def.*auth" --fts --regex --language python --quiet

Fallback: Use grep only when CIDX unavailable.

---

TEMPORAL SEARCH (Git History)

Use For: Code archaeology, commit message search, bug history, feature evolution.

Prerequisite:

cidx index --index-commits

(indexes git history)

Flags:

--time-range-all

|

--time-range YYYY-MM-DD..YYYY-MM-DD

|

--chunk-type commit_message

|

--chunk-type commit_diff

|

--author EMAIL

Examples:

• When added:

  cidx query "JWT auth" --time-range-all --quiet

• Bug history:

  cidx query "database bug" --time-range-all --chunk-type commit_message --quiet

• Author work:

  cidx query "refactor" --time-range-all --author "dev@company.com" --quiet

Indexing Options:

--all-branches

|

--max-commits N

|

--since-date YYYY-MM-DD

---

SCIP CALL GRAPH AND DEPENDENCY ANALYSIS

CIDX provides precise code intelligence via SCIP (Source Code Intelligence Protocol) indexes.

Prerequisite:

cidx scip generate

(generates SCIP indexes)

For complete SCIP documentation: See reference/scip-intelligence.md

Quick reference - SCIP commands:

• cidx scip definition SYMBOL

  - Find where a symbol is defined

• cidx scip references SYMBOL

  - Find all references to a symbol

• cidx scip dependencies SYMBOL

  - Get symbols this symbol depends on

• cidx scip dependents SYMBOL

  - Get symbols that depend on this symbol

• cidx scip callchain FROM TO

  - Trace call chains between symbols

• cidx scip context SYMBOL

  - Get smart context (curated file list)

• cidx scip impact SYMBOL

  - Analyze change impact

Common options:

--limit N

|

--exact

|

--project PATH

|

--depth N

---

REFERENCE DOCUMENTATION

Detailed documentation available in reference/ directory:

• reference/semantic-search.md - Semantic search flags and patterns
• reference/fts-search.md - Full-text search, regex, fuzzy modes
• reference/temporal-search.md - Git history search guide
• reference/scip-intelligence.md - Complete SCIP call graph and dependency analysis guide