> 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/readme.md).

# Get Started

Your AI coding tool reads your codebase one file at a time. Pharaoh gives it the full picture - every function, dependency, module boundary, and entry point - in a single query.

Two steps to set up.

## Step 1: Install the GitHub App

Go to [github.com/apps/pharaoh-so/installations/new](https://github.com/apps/pharaoh-so/installations/new) and install on your org or personal account. Select the repos you want mapped.

Pharaoh requests **read-only** access. It parses your code with tree-sitter, builds a knowledge graph of your architecture, and discards the source code. Mapping starts automatically and takes 1-3 minutes.

## Step 2: Connect your AI tool

Pharaoh uses [MCP](https://modelcontextprotocol.io/) to plug into your AI coding tool. Three ways to connect:

### Run a command (Claude Code / OpenClaw)

```bash
npx @pharaoh-so/mcp
```

A browser opens for GitHub OAuth. Authorize and you're connected.

### Add the MCP URL (Claude.ai, Cursor, Windsurf, OpenClaw)

Open your tool's MCP settings and add this server:

```
https://mcp.pharaoh.so/sse
```

Complete the GitHub OAuth flow when prompted.

| Tool          | Where to find MCP settings                |
| ------------- | ----------------------------------------- |
| **Claude.ai** | Settings → MCP Servers → Add              |
| **Cursor**    | Settings → MCP → Add Server               |
| **Windsurf**  | Settings → MCP Servers → Add              |
| **OpenClaw**  | `/mcp add` or Settings → Skills → Add MCP |

### Device auth flow (headless, SSH, containers)

No browser on the machine? No problem:

```bash
npx @pharaoh-so/mcp
```

You get a URL and a code. Open the URL on any device with a browser, enter the code, authorize with GitHub. The MCP connection runs locally via stdio.

### Detailed setup + troubleshooting

Each tool has a dedicated page with full setup steps and debug flow:

* [Claude Code](/docs/setup/claude-code.md)
* [Claude.ai](/docs/setup/claude-ai.md)
* [Cursor](/docs/setup/cursor.md)
* [Windsurf](/docs/setup/windsurf.md)
* [OpenClaw](/docs/setup/openclaw.md)
* [Headless / SSH / CI](/docs/setup/headless.md)

Need to install the GitHub App first? [Full GitHub App guide](/docs/setup/github-app.md)

## Verify

Ask your AI tool anything about your codebase:

```
What modules does this codebase have?
```

Your tool calls `get_codebase_map` automatically. If you see modules, dependencies, and endpoints, Pharaoh is working.

## What happens next

Your AI tool now queries Pharaoh's knowledge graph automatically. Before writing code, before refactoring, before reviewing PRs. You don't invoke tools manually. The agent decides when architectural context would help and queries the graph on its own.

The graph re-maps on every push to your default branch. No maintenance required.

## Guides

Get the most out of Pharaoh:

* [Explore your codebase](/docs/guides/explore-your-codebase.md) - see the full architecture before changing anything
* [Refactor safely](/docs/guides/safe-refactoring.md) - trace every caller before touching shared code
* [Review pull requests](/docs/guides/review-pull-requests.md) - structural checks, not just diffs
* [Find dead code](/docs/guides/find-dead-code.md) - unreachable functions and duplicate logic
* [Check test coverage](/docs/guides/check-test-coverage.md) - find untested high-risk code
* [Map open-source repos](/docs/guides/map-open-source.md) - query any public GitHub repo's architecture
* [Set up PR Guard](/docs/guides/pr-guard.md) - automated structural checks on every PR


---

# 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, and the optional `goal` query parameter:

```
GET https://pharaoh.so/docs/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.