Codebase Indexing

Index source code for semantic search with vector embeddings.

State Machine

code

START → VALIDATE_PATH → SCAN_CODEBASE → CHECK_EXISTING
      ├→ NEW_INDEX ────┐
      └→ INCREMENTAL ──┴→ INDEX → [SUCCESS | PARTIAL] → REPORT → END

Execution

Path A: Subagent (preferred)

code

Task(
  subagent_type: "summarizer",
  prompt: "Index codebase at PATH for project PROJECT_ID with name NAME"
)

Path B: Direct scripts

bash

# Main orchestrator (validates, scans, and indexes)
bun .opencode/skills/codebase-index/index.ts index PROJECT_ID NAME PATH [OPTIONS]

# Subcommands
bun .opencode/skills/codebase-index/index.ts validate PATH [--quiet]
bun .opencode/skills/codebase-index/index.ts scan PATH [--quiet]
bun .opencode/skills/codebase-index/index.ts reindex PROJECT_ID NAME PATH
bun .opencode/skills/codebase-index/index.ts search PROJECT_ID QUERY [--limit N]
bun .opencode/skills/codebase-index/index.ts list PROJECT_ID
bun .opencode/skills/codebase-index/index.ts delete PROJECT_ID CODEBASE_ID

Path C: Direct script execution

bash

# Run individual scripts
bun .opencode/skills/codebase-index/lib/scripts/validate-path.ts PATH [--quiet]
bun .opencode/skills/codebase-index/lib/scripts/scan-codebase.ts PATH [--quiet]
bun .opencode/skills/codebase-index/lib/scripts/index.ts PROJECT_ID NAME PATH [OPTIONS]

Commands

index - Main Index

bash

bun .opencode/skills/codebase-index/index.ts index PROJECT_ID NAME PATH [OPTIONS]

Validates path, scans codebase, and creates or updates index.

Options:

•--dry-run: Preview without indexing
•--validate-only: Only validate path and scan, no indexing
•--quiet: JSON output only

Exit codes:

•0 = success
•1 = error
•2 = partial failure (< 90% coverage)

reindex - Full Re-index

bash

bun .opencode/skills/codebase-index/index.ts reindex PROJECT_ID NAME PATH

Rebuilds entire index from scratch, useful after major refactors.

Exit codes:

•0 = success
•1 = error

search - Semantic Search

bash

bun .opencode/skills/codebase-index/index.ts search PROJECT_ID QUERY [--limit N]

Searches indexed codebase using semantic similarity.

Options:

•--limit N: Maximum results (default: 10)

Exit codes:

•0 = success (results returned)
•1 = error

list - List Codebases

bash

bun .opencode/skills/codebase-index/index.ts list PROJECT_ID

Lists all codebases indexed for a project.

Exit codes:

•0 = success
•1 = error

delete - Delete Codebase

bash

bun .opencode/skills/codebase-index/index.ts delete PROJECT_ID CODEBASE_ID

Deletes a codebase index and all its embeddings.

Exit codes:

•0 = success
•1 = error

validate - Validate Path

bash

bun .opencode/skills/codebase-index/index.ts validate PATH [--quiet]
# or
bun .opencode/skills/codebase-index/lib/scripts/validate-path.ts PATH [--quiet]

Checks:

•Path exists
•Path is a directory
•Returns validation result with error details if invalid

Exit codes:

•0 = valid
•1 = invalid (path doesn't exist or not a directory)

scan - Scan Codebase

bash

bun .opencode/skills/codebase-index/index.ts scan PATH [--quiet]
# or
bun .opencode/skills/codebase-index/lib/scripts/scan-codebase.ts PATH [--quiet]

Scans:

•Counts total files
•Counts indexable files (by extension)
•Detects languages (TypeScript, JavaScript, Python, Go, Rust, etc.)
•Estimates chunk count
•Reports language breakdown with percentages

Exit codes:

•0 = success
•1 = error

Environment Variables

Variable	Default	Description
`BRAINY_API_URL`	`http://localhost:3000`	API endpoint
`BRAINY_PROJECT_ID`	`3afb861a-...`	Default project
`INDEX_EXTENSIONS`	`.ts,.js,.py,.go,.rs,.md,.tsx,.jsx`	File types to index
`INDEX_EXCLUDE_DIRS`	`node_modules,.git,dist,build,target,.next`	Directories to skip
`INDEX_CHUNK_SIZE`	`100`	Lines per chunk

Workflow

New Codebase

bash

# Step 1: Validate path
bun .opencode/skills/codebase-index/index.ts validate /path/to/project

# Step 2: Scan for language analysis
bun .opencode/skills/codebase-index/index.ts scan /path/to/project

# Step 3: Create full index
bun .opencode/skills/codebase-index/index.ts index PROJECT_ID NAME /path/to/project

Incremental Update

bash

# Reindex after major changes
bun .opencode/skills/codebase-index/index.ts reindex PROJECT_ID NAME /path/to/project

Search Codebase

bash

bun .opencode/skills/codebase-index/index.ts search PROJECT_ID "your query here"

Validate Only

bash

bun .opencode/skills/codebase-index/index.ts index PROJECT_ID NAME PATH --validate-only

Runs validation and scanning without performing indexing.

Dry Run

bash

bun .opencode/skills/codebase-index/index.ts index PROJECT_ID NAME PATH --dry-run

Previews what would happen without making changes.

Direct Script Execution

The CLI commands (validate, scan, index) are wrappers around these scripts:

•validate → lib/scripts/validate-path.ts (validates codebase path)
•scan → lib/scripts/scan-codebase.ts (analyzes language distribution)
•index → lib/scripts/index.ts (creates embeddings via API)

Language Detection

The scanner supports the following languages:

Extension	Language
`.ts`, `.tsx`	TypeScript
`.js`, `.jsx`	JavaScript
`.py`	Python
`.go`	Go
`.rs`	Rust
`.java`	Java
`.kt`	Kotlin
`.c`, `.cpp`, `.h`, `.hpp`	C/C++
`.cs`	C#
`.swift`	Swift
`.rb`	Ruby
`.php`	PHP
`.md`	Markdown
`.json`, `.yaml`, `.yml`	Config
`.sh`, `.bash`, `.zsh`	Shell
`.svelte`, `.vue`	Frameworks

Output Example

code

━━━ Codebase Indexing ━━━
   Project: 3afb861a-b783-45a6-bba2-4b6d96468aeb
   Name: BrAIny
   Path: /home/dev/projects/brainy
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Validating path...
   Path: ./BrAIny
   Absolute: /home/dev/projects/brainy/BrAIny

✅ Path validated successfully

🔍 Scanning codebase...
   Path: /home/dev/projects/brainy/BrAIny

   ├─ Total files: 245
   ├─ Indexable: 198 (81%)
   ├─ Estimated chunks: ~99
   └─ Total size: 2.45 MB

Languages detected:
   ├─ TypeScript: 142 files (72%)
   ├─ JSON: 31 files (16%)
   ├─ Markdown: 18 files (9%)
   └─ Shell: 7 files (3%)

✅ Codebase scan complete

🚀 Starting indexing...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Mode: Full index (new codebase)

📁 Creating new codebase index...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

   ├─ Files indexed: 198
   ├─ Chunks created: 99
   └─ Embeddings: 99

   Embedding coverage: 100%
   Duration: 12.3s

✅ Indexing complete!
   Codebase ID: xyz-789
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

{
  "success": true,
  "codebaseId": "xyz-789",
  "mode": "new",
  "stats": {
    "totalFiles": 198,
    "newFiles": 198,
    "modifiedFiles": 0,
    "deletedFiles": 0,
    "totalChunks": 99,
    "indexedChunks": 99,
    "failedChunks": 0
  },
  "timing": {
    "totalMs": 12300
  }
}

Examples

Basic indexing

bash

bun .opencode/skills/codebase-index/index.ts index 3afb861a-b783-45a6-bba2-4b6d96468aeb BrAIny /path/to/BrAIny

Validate path before indexing

bash

bun .opencode/skills/codebase-index/index.ts validate /path/to/project

Scan for language analysis

bash

bun .opencode/skills/codebase-index/index.ts scan /path/to/project

Reindex codebase (full rebuild)

bash

bun .opencode/skills/codebase-index/index.ts reindex 3afb861a-b783-45a6-bba2-4b6d96468aeb BrAIny /path/to/BrAIny

Search indexed codebase

bash

bun .opencode/skills/codebase-index/index.ts search 3afb861a-b783-45a6-bba2-4b6d96468aeb "authentication middleware" --limit 5

List codebases for project

bash

bun .opencode/skills/codebase-index/index.ts list 3afb861a-b783-45a6-bba2-4b6d96468aeb

Delete a codebase index

bash

bun .opencode/skills/codebase-index/index.ts delete 3afb861a-b783-45a6-bba2-4b6d96468aeb xyz-789

Validate-only mode (no indexing)

bash

bun .opencode/skills/codebase-index/index.ts index 3afb861a-b783-45a6-bba2-4b6d96468aeb MyProject /path/to/project --validate-only

Dry run preview

bash

bun .opencode/skills/codebase-index/index.ts index 3afb861a-b783-45a6-bba2-4b6d96468aeb MyProject /path/to/project --dry-run

JSON output only

bash

bun .opencode/skills/codebase-index/index.ts index 3afb861a-b783-45a6-bba2-4b6d96468aeb BrAIny /path/to/BrAIny --quiet

Script Structure

Entry Point

code

.opencode/skills/codebase-index/index.ts

Main CLI entry point with subcommand dispatch:

•index → Create or update codebase index
•reindex → Full re-index from scratch
•search → Semantic search within indexed codebase
•list → List all codebases for a project
•delete → Delete a codebase index
•validate → Validate codebase path (alias for validate-path)
•scan → Scan for language analysis (alias for scan-codebase)

Core Scripts (lib/scripts/)

Script	CLI Alias	Purpose
`index.ts`	`index`	Creates embeddings and indexes via API
`validate-path.ts`	`validate`	Validates that a path exists and is a directory
`scan-codebase.ts`	`scan`	Analyzes file types, languages, and estimates chunk count

Naming Convention

•CLI commands: Single lowercase words (index, reindex, search, scan)
•Script files: kebab-case with descriptive names (validate-path.ts, scan-codebase.ts)
•Output: JSON-formatted results for machine consumption