> For the complete documentation index, see [llms.txt](https://pharaoh.so/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pharaoh.so/docs/guides/explore-your-codebase.md).

# 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. 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.