codebase-search

name	codebase-search
description	Search the codebase by concept using semantic search, then drill into results with Grep/Read. Use when exploring unfamiliar code, tracing behavior, or answering "how does X work?" questions.
argument-hint	<search query>

Codebase Search

Search the codebase using semantic search (concept/intent-based) backed by the qdrant-search MCP server, then drill into results with targeted Grep/Read.

Query: $ARGUMENTS

When to Use This

• "How does authentication work?"
• "Where is session reconnection handled?"
• "What happens when an environment disconnects?"
• Any question about behavior, flow, or intent — not exact symbol names

Search Strategy

Step 1: Semantic search

Use mcp__qdrant-search__semantic_search with the user's query. Always scope to the current catalog.

mcp__qdrant-search__semantic_search(query: "<user's question>", catalog: "grackle")

Review the results — they're ranked by relevance with breadcrumbs showing the code path.

Examples

Conceptual question — "how does the pairing flow work?"

mcp__qdrant-search__semantic_search(query: "pairing code generation and redemption flow", catalog: "grackle")

Tracing behavior — "what happens when an agent session completes?"

mcp__qdrant-search__semantic_search(query: "session completion event processing status transition", catalog: "grackle")

Finding related code — "where are tokens injected into sessions?"

mcp__qdrant-search__semantic_search(query: "token injection push credentials to PowerLine before spawn", catalog: "grackle")

Cross-cutting concern — "how does error handling work across the WebSocket bridge?"

mcp__qdrant-search__semantic_search(query: "WebSocket error handling disconnect reconnection", catalog: "grackle")

Step 2: View top results

Use mcp__qdrant-search__view_chunks to read the full source of the most relevant hits (top 3-5). Use selectors to get specific chunks:

mcp__qdrant-search__view_chunks(ids: ["abc123"])       // all chunks for that file
mcp__qdrant-search__view_chunks(ids: ["abc123:2-4"])   // chunks 2 through 4
mcp__qdrant-search__view_chunks(ids: ["abc123:3"])     // single chunk

Example

Semantic search returns a hit f7a2b3c1:2 with breadcrumb @grackle-ai/server > src > pairing.ts > redeemPairingCode. To read the full function:

mcp__qdrant-search__view_chunks(ids: ["f7a2b3c1:2-3"])

Step 3: Follow references with Grep/Read

Once you've identified the key files from semantic search, use Grep to find exact symbol references and Read to examine specific implementations. Semantic search finds the area, Grep/Read finds the details.

Example

Semantic search found that redeemPairingCode in pairing.ts is the core function. Now trace who calls it:

Grep: pattern="redeemPairingCode" → finds call sites across the server package
Read: the relevant handler file to see how the gRPC/HTTP layer invokes it

Step 4: Synthesize

Report findings with specific file paths and line numbers. Connect the dots between components.

When NOT to Use This

Use Grep/Glob directly when you:

• Know the exact symbol name: Grep: pattern="class SessionStore"
• Need a regex pattern: Grep: pattern="status.*=.*completed"
• Are looking for a specific file: Glob: pattern="**/pairing.ts"

Rules

1. Always start with semantic search — don't skip to Grep for conceptual questions
2. Always scope to the canonical catalog — use catalog: "grackle" regardless of whether you're in a worktree or the main repo.
3. Use Grep for follow-up, not initial discovery — Grep finds exact strings, semantic search finds concepts
4. Include file:line references in your response
5. Run multiple semantic searches if needed — different phrasings surface different results. If the first query doesn't find what you need, rephrase.