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