# 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: 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/readme.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.