AgentSkillsCN

codebase-index

为语义代码搜索对项目文件进行索引。支持增量更新、进度追踪，以及批量嵌入生成。

SKILL.md
--- frontmatter
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

code
START → VALIDATE_PATH → 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
# 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

bash
bun .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

bash
bun .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

bash
bun .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

bash
bun .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

VariableDefaultDescription
BRAINY_API_URLhttp://localhost:3090API endpoint
BRAINY_PROJECT_ID3afb861a-...Default project
INDEX_EXTENSIONS.ts,.js,.py,.go,.rs,.mdFile types to index
INDEX_EXCLUDE_DIRSnode_modules,.git,dist,buildDirectories to skip
INDEX_CHUNK_SIZE100Lines per chunk
INDEX_EMBEDDING_BATCH10Embeddings per batch
INDEX_MAX_FILES0Max files per run (0=unlimited)

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

StatusEmojiMeaning
Excellent🟢Fresh (< 8h), full coverage
Good🟡Recent (8-24h), good coverage
Stale🟠Old (> 24h), may miss changes
Unhealthy🔴Low coverage (< 90%)

Output Example

code
━━━ 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
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━