Explore Your Codebase

Your AI reads files one at a time. Before it touches anything, give it the full architectural picture - every module, dependency, entry point, and hot file - in a single query.

The workflow

1. Get the full map

Ask your AI tool:

What does this codebase look like?

This triggers get_codebase_map. You get back:

• Every module with file count, LOC, and exported function count

• The dependency graph between modules (who imports whom)

• Entry points: HTTP endpoints, cron jobs, CLI commands

• Hot files: most modified in the last 90 days

This is the equivalent of looking at a city map before walking the streets. Start here.

2. Dive into a specific module

Ask your AI tool:

Show me the auth module before I change anything.

This triggers get_module_context. You get back the complete module profile:

• All files in the module

• Exported functions with their signatures

• Internal dependencies (what this module imports)

• External callers (what other modules import from this one)

• DB tables read or written

• HTTP endpoints served

• Environment variables used

3. Search before writing

Ask your AI tool:

Is there already a function that validates email addresses?

This triggers search_functions. It searches every function in the codebase by name, signature, and module - finding existing code before you duplicate it.

4. Check existing UI components

Ask your AI tool:

What design system components exist?

This triggers get_design_system. Returns existing UI components, design tokens, and patterns. Prevents creating a second <Button> variant that already exists.

5. Get everything at once

Ask your AI tool:

I need full context on the auth and db modules, plus search for 'validate'.

This triggers pharaoh_recon, which batches codebase map + module context + function search + blast radius into one server-side call. One round trip instead of four.

What to look for

• Bidirectional arrows in the dependency graph - two modules importing each other means circular dependencies. These make refactoring harder and signal unclear module boundaries.

• Hot files - files changed most in the last 90 days. High churn correlates with bugs. If a file appears hot and has high complexity, it deserves extra caution.

• External callers - the list of modules calling into this one. This is the audience that breaks if you change the module's API. More callers = more careful changes.

• Module size - LOC and file count give a quick read on complexity. A module with 3,000 LOC and 40 files is qualitatively different from one with 200 LOC and 3 files.

Tips

• Always start with get_codebase_map. The agent calls Pharaoh tools automatically once connected, but explicit prompts get more targeted results. "Show me the codebase" is a better first message than "Add a login endpoint."

• Use pharaoh_recon for PR reviews and task planning. It batches multiple queries server-side, which means fewer round trips and a more complete picture in one response.

• Pharaoh returns structural metadata, not source code. The AI uses the architecture to decide which files to read - it reads the actual code itself when it needs implementation details.