version: "1.0.0" name: codebase-search description: Task-specific semantic code and documentation retrieval. Use compact context for unfamiliar repository orientation, direct lookup for known definitions, graph tools for relationships, and grep for exhaustive literal matches.

Codebase Search Skill

Important: Indexed Content

The indexed codebase contains two types of content:

1. Project Source Code — all code files in the current workspace
2. Knowledge Base Documentation — external documentation, usage guides, API references, and example programs added via add_knowledge_base (MCP/OpenCode) or knowledge_base_add (Pi).

When to Use What

Task-specific Workflow

1. Check index_status when readiness or freshness is unknown. Index only when missing, stale, or incompatible.
2. For unfamiliar repository orientation, use one compact codebase_context first pass (tokenBudget: 600, limit: 5) and inspect its evidence before broad reads or searches.
3. For known definitions, use implementation_lookup directly. For callers/callees or dependency paths, use call_graph or call_graph_path directly once endpoints are identified.
4. For known or suspected edit targets, optionally use codebase_edit_context for bounded source plus direct graph evidence.
5. Use codebase_peek for semantic locations or codebase_search for matching content when needed. Neither requires another context call when scope is already known.
6. Read known paths directly; use grep for exact identifiers and exhaustive literal matches. Apply directory/file filters when the scope is known, rather than guessing a narrower scope.

For repository implementation questions, use local source evidence before web search. External library/API documentation questions may need web sources when the local index lacks relevant documentation. Avoid repeating retrieval when existing evidence already answers the task.

Tools

codebase_peek

Find WHERE code is. Returns metadata only (file, line, name, type).

codebase_peek(query="validation logic", chunkType="function", directory="src/utils")
codebase_peek(query="authentication flow", blameAuthor="jane@example.com")

codebase_search

Find code with full content. Use when you need to see implementation.

codebase_search(query="error handling middleware", fileType="ts", contextLines=2)
codebase_search(query="rate limiter", blameSince="2025-01-01", blameUntil="2025-01-31")

find_similar

Find code similar to a given snippet. Use for duplicate detection, pattern discovery, refactoring.

find_similar(code="function validate(input) { return input.length > 0; }", excludeFile="src/current.ts", blameSince="2025-01-01")

call_graph

Query callers or callees of a function/method.

call_graph(name="validateToken", direction="callers")

index_codebase

Manually trigger indexing. Required before first search.

index_status

Check if indexed and ready.

MCP/OpenCode knowledge-base tools

• add_knowledge_base(path="/path/to/docs")
• list_knowledge_bases
• remove_knowledge_base(path="/path/to/docs")

Pi knowledge-base tools

• knowledge_base_add(path="/path/to/docs")
• knowledge_base_list
• knowledge_base_remove(path="/path/to/docs")

Query Tips

Describe behavior, not syntax:

• Good: "function that hashes passwords securely"
• Bad: "hashPassword" (use grep for exact names)

Search across documentation:

• Good: "how to configure WiFi in ESP-IDF"
• Good: "GPIO initialization example"

Filters