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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pharaoh.so/docs/guides/explore-your-codebase.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.