> 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/connect/github-app.md).

# GitHub access

Install the Pharaoh GitHub App on your account or organization. It reads the repositories you choose and writes only check results, never code.

Pharaoh maps the repositories you share with its GitHub App. Before you install it, you need:

* **A GitHub account** that can install apps on the personal account or organization that owns your code. On an organization, an owner may need to approve the install.
* **A choice of repositories.** Share all of them or select some. Pharaoh maps only the repositories you share; with none shared, there is nothing to map.
* **An agent:** [Claude Code](/docs/connect/claude-code.md) or [Codex](/docs/connect/codex.md), or a client that connects to an MCP URL, such as [Claude Chat](/docs/connect/claude-ai.md), [Cursor](/docs/connect/cursor.md) or [VS Code](/docs/connect/vscode.md).

[Install Pharaoh](https://github.com/apps/pharaoh-so/installations/new) on that account or organization. GitHub then sends you to setup, where you watch the first maps and connect your agent. Already installed? Sign in with GitHub on the setup page.

<a href="https://mcp.pharaoh.so/setup" class="button primary">Open setup</a>

The app reads repository contents and metadata to build the map. It can publish GitHub check results; it cannot push commits or edit your files. GitHub displays the requested permissions before you authorize installation.

If a repository is missing, grant the app access to it in [GitHub's installed-app settings](https://github.com/settings/installations), or for an organization in that organization's settings under GitHub Apps, then refresh setup. Organization installations may require an owner to approve access.

Each person connects their own agent and signs in with GitHub. Authentication uses your numeric GitHub user ID; a username change does not change that ID. Repository transfers and access changes are separate from a username change.

## What happens after installation

Pharaoh maps every repository that contains TypeScript, JavaScript, Python, C or C++, and the first maps start right away. Each push to a repository's default branch refreshes its map. After the trial, mapping continues for 90 days and `get_codebase_map` keeps answering; see [account and billing](/docs/use-pharaoh/pricing.md).

Pharaoh does not map a repository that is empty, archived, has no supported language or has more than 15,000 source files. A query about one names the reason. Setup lists repositories with no supported language or too many files, but not empty or archived ones.

## Checks the app posts

The app's only write access is GitHub checks:

* **Pharaoh PR Guard** reports on pull requests in Pro workspaces. See [PR Guard](/docs/use-pharaoh/pr-guard.md).
* **Pharaoh: finish setup** appears on pushes during a new workspace's first 14 days, until someone in the workspace asks Pharaoh a first question. It links to setup.

Neither blocks a merge by default: the finish-setup check is always neutral, and PR Guard reports its findings as a neutral result.

## Change or remove access

Change which repositories the app can read in [GitHub's installed-app settings](https://github.com/settings/installations); for an organization, use the organization's settings. Uninstalling revokes access and starts a 30-day retention period. Reinstalling within it restores your maps.

See [security](/docs/use-pharaoh/security.md) for processing and storage details.