efficient-code-search

name	efficient-code-search
description	Efficient local codebase search and reconnaissance. Use when finding where code lives, mapping a subsystem, answering architecture/flow questions from a repo, exploring an unfamiliar codebase, or doing scout-style discovery before edits. Prefer CodeGraph when available and initialized; otherwise use narrow grep/find/read loops.

Efficient Code Search

Use this skill to search a codebase with minimal tool calls and minimal context bloat. The goal is to find enough evidence to answer or orient, not to exhaustively crawl the repository.

Core Rules

1. Do not read the whole repo. Start broad but shallow, then narrow quickly.
2. File lists before contents. First identify likely files; only then read snippets.
3. Exact search beats vague search. Use exact symbols, route names, config keys, strings, file names, and type names when you have them.
4. Concept search uses CodeGraph if available. For architecture, flows, callers/callees, and unfamiliar subsystems, try CodeGraph first when the repo already has a .codegraph/ index.
5. Stop when sufficient. Once you have evidence-backed paths and relationships, report the map or answer. Do not keep searching for completeness unless the user asked for exhaustive coverage.
6. Never mutate as part of search. Do not run index/init/sync commands or write files unless the user explicitly asked for setup or maintenance.

Subagent Budget

If you are running as a scout/subagent, be stricter than the main agent:

• Spend at most ~6-8 search/read tool calls before returning.
• If CodeGraph is available and initialized, use one focused CodeGraph query first; make at most one narrower follow-up.
• Do not spend more than one tool call loading this skill or related docs.
• Prefer returning a compact map with uncertainty over hitting a step cap while chasing completeness.

Tool Selection

If CodeGraph MCP is available

Use mcp_codegraph_codegraph_explore for:

• “How does X work?”
• “Where is X implemented?” when names are fuzzy
• “How does request/session/auth/cache flow through the system?”
• callers/callees, impact radius, dependency relationships
• large or unfamiliar repos

Guidelines:

• Include projectPath when the tool supports it and you know the absolute repo path.
• Ask one focused query first, e.g. How does authentication flow from route to session storage?.
• Treat returned source as already read; do not re-verify every result with grep/read.
• If CodeGraph says the project is not initialized or no graph exists, immediately fall back to normal search.
• If CodeGraph reports stale/pending files, read those specific files directly before relying on the stale sections.

Do not run codegraph init, codegraph sync, or other maintenance commands unless the user explicitly asks.

If searching exact text/symbols

Use dedicated grep/find/ls tools when available. If not available, use shell with rg/rg --files.

Preferred sequence:

1. Search file names/paths first.
2. Search content in files-with-matches style first.
3. Read only the top matched snippets around relevant line numbers.
4. Widen only if results are empty or contradictory.

Examples of good exact queries:

• function/type/class names: SessionManager, createAgentSession
• route strings: /api/auth, POST /login
• config keys/env vars: DATABASE_URL, timeoutMs
• error messages/log lines
• import/module names

If mapping an unfamiliar area without CodeGraph

Use this order:

1. Locate manifests/docs/entrypoints: README, package.json, pyproject.toml, Cargo.toml, src/index, main, cli, server.
2. Find likely directories by name: auth, session, routes, api, core, services, models, tests.
3. Grep for domain terms and exact symbols.
4. Read small snippets from the top hits.
5. Summarize structure and uncertainty.

Search Patterns

Filename discovery

Use for likely locations before content search:

find/glob for names like: *auth*, *session*, *route*, *config*, *server*, *agent*, *extension*

If using shell:

rg --files | rg -i 'auth|session|route|config'

Content discovery

Start with file-only results:

rg -n --glob '!node_modules' --glob '!dist' 'SessionManager|createSession|auth' path

Then read nearby lines only for shortlisted files.

If a file-only content search returns many hits, do not open the first matches blindly; narrow first with another exact term, likely directory, file type, or test/source filter.

Large repo safety

Always avoid or exclude:

.git, node_modules, dist, build, target, coverage, .next, .venv, __pycache__, vendor, .codegraph, .cocoindex_code

Use result caps and narrower paths where possible.

Reading Strategy

When a search result gives a line number:

• Read ~40-120 lines around the hit.
• Expand only if imports/types/callers are needed.
• Prefer several small snippets over one huge file read.
• For huge files, read the symbol body and nearby imports, not the entire file.

Output Format for Recon/Scout

Return compact, evidence-backed structure:

## Map
- `path/to/file`: what lives here and why it matters
- `path/to/other`: relationship to the first file

## Flow / Relationships
1. Entry point → service/helper → storage/external boundary
2. Important types/functions and where they are defined

## Tests / Validation Locations
- `path/to/test`: what it covers

## Notes / Uncertainty
- What was not confirmed, and the next best search if needed

Keep it terse. Do not include giant code blocks unless the user specifically asks.

Escalation Rules

• If exact search has no hits, broaden terms or switch to CodeGraph/conceptual search.
• If CodeGraph returns too broad a result, ask a narrower CodeGraph query with a file/symbol/path constraint.
• If results disagree, read direct source snippets and cite the paths/lines.
• If the task can be answered from one or two known files, skip broad reconnaissance.