---

name: codebase-index description: Index project files for semantic code search. Supports incremental updates, progress tracking, and batch embedding generation. metadata: subagent: summarizer version: "1.0" category: code-search allowed-tools: Bash(bun:*)

Codebase Indexing

Index source code for semantic search with vector embeddings.

State Machine

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

Execution

Path A: Subagent (preferred)

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

Path B: Direct scripts

Copy# Validate path first
bun .opencode/skills/codebase/lib/scripts/validate-path.ts PATH

# Check if already indexed
bun .opencode/skills/codebase/lib/scripts/check-existing.ts PROJECT_ID PATH

# Run indexing
bun .opencode/skills/codebase/index.ts PROJECT_ID NAME PATH

Commands

Validate Path

Copybun .opencode/skills/codebase/lib/scripts/validate-path.ts PATH [--quiet]

Checks:

• Path exists and is directory
• Counts indexable files
• Estimates chunks
• Detects languages

Check Existing

Copybun .opencode/skills/codebase/lib/scripts/check-existing.ts PROJECT_ID PATH [--quiet]

Exit codes:

• 0 = exists (incremental recommended)
• 2 = not found (full index needed)

Index Codebase

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

Options:

• --dry-run: Preview without indexing
• --quiet: JSON output only

Exit codes:

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

Get Status

Copybun .opencode/skills/codebase/lib/scripts/status.ts CODEBASE_ID [--quiet]

Exit codes:

• 0 = healthy (excellent/good)
• 2 = stale (> 24 hours old)
• 3 = unhealthy (< 90% coverage)

Environment Variables

Workflow

New Codebase

1. lib/scripts/validate-path.ts → confirm valid
2. lib/scripts/check-existing.ts → exits 2 (not found)
3. index.ts → creates codebase + full index

Incremental Update

1. lib/scripts/check-existing.ts → exits 0 (exists)
2. index.ts → detects changes, indexes diff

Health Indicators

Output Example

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

🔍 Checking for existing codebase...
   Mode: Incremental update

🚀 Starting indexing...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔄 Reindexing existing codebase...

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

   ├─ New files: 3 📝
   ├─ Modified: 2 ✏️
   ├─ Deleted: 0 🗑️
   ├─ Total chunks: 45
   └─ Indexed: 45

   Embedding coverage: 100%
   Duration: 12.3s

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