Exploring Codebases with Context Engine

When to Use

• "How does authentication work?"
• "What's the project structure / where do I find X?"
• "Show me the main components of feature Y"
• "What calls this function?" (via call-graph annotations)
• Understanding code you haven't seen before

Workflow

1. list-repos                                              → get repoId, confirm status=indexed
2. codebase-retrieval({repoId, information_request: "<concept you want to understand>"})
                                                           → ranked snippets across the whole repo
3. Follow [callers:…] / [calls:…] annotations to navigate the call graph
4. file-retrieval({repoId, file_path, information_request}) → zoom into a specific file
5. Read <file>:<lines>                                     → exact content before any edit

If list-repos shows the index is stale (lastCommitSha ≠ local HEAD) → see context-engine-sync.

Checklist

- [ ] list-repos → repoId + freshness check
- [ ] codebase-retrieval with a NATURAL-LANGUAGE description of the concept (not an identifier)
- [ ] Review the ranked snippets and their file#line ranges
- [ ] Follow [calls:…] outward / [callers:…] inward to map the flow
- [ ] file-retrieval to drill into the most relevant file
- [ ] Read the source at the returned line ranges for implementation detail

Tools

codebase-retrieval — the primary tool. Describe WHAT you want in natural language:

codebase-retrieval({repoId, information_request: "single-app aggregate Hono bootstrap and route mounting"})
→ core/apps/iam/src/app.ts#L1-87 [calls: createServiceApp, registerRoutes, …]
→ apps/models-router/apps/api/src/app.ts#L1-133 [callers:3]
→ core/packages/sdk-server/src/hono/factory.ts#L1-86 [callers: buildApp, buildIamApp +8 more]

• Good query: "Where is the database connection pool initialised?"
• Bad query: "find definition of class Foo" → use grep for exact identifiers
• limit (default 30, max 50) widens/narrows the result set.

file-retrieval — when you know the file but not the line range:

file-retrieval({repoId, file_path: "core/apps/iam/src/app.ts", information_request: "where publicPaths for STS are declared", top_k: 5})
→ snippets with line numbers → then Read to confirm

Query Strategy

Example: "How does the IAM PDP authorize requests?"

1. list-repos → repoId=be1730bd-…, status=indexed
2. codebase-retrieval({repoId, information_request: "IAM PDP authorize decision evaluation flow"})
   → core/apps/iam/src/api/authz.routes.ts, services/authz/… (PDP)
3. Follow [calls:…] into the policy evaluation + decision cache symbols
4. file-retrieval on authz.routes.ts for the exact handler
5. Read the handler + evaluator for implementation details