Pharaoh — Codebase Knowledge Graph + Developer Skill Library

Pharaoh parses your source files server-side to extract structural metadata (names, signatures, imports, relationships) and stores that metadata — not source code bodies — in a knowledge graph. AI agents then query the graph instead of reading files one at a time.

What the Installer Does

Running npx @pharaoh-so/mcp --install-skills performs these actions:

1. Downloads the @pharaoh-so/mcp npm package (source, npm)
2. Copies 23 skill directories (SKILL.md markdown files) into ~/.openclaw/skills/ — warning: overwrites existing pharaoh skill files on reinstall (uses cpSync with force: true; does not touch non-pharaoh skills)
3. Adds an MCP server entry "pharaoh" to ~/.openclaw/openclaw.json under mcpServers (skips if already present, refuses to write if JSON is corrupted)
4. If OpenClaw is not detected (~/.openclaw/ doesn't exist), prints manual installation instructions and exits — does not create directories or modify config

Authentication happens separately when the MCP server first runs (not during --install-skills):

• Device flow (RFC 8628) — displays a code, you authorize on any device with a browser
• Credentials stored at ~/.pharaoh/credentials.json (file permissions 0600, owner-only)

No background processes are installed. No cron jobs. No system services.

Architecture: The @pharaoh-so/mcp package runs a local stdio proxy process — it starts when your AI client launches it and stops when the session ends. This proxy relays MCP messages to the remote Pharaoh server at mcp.pharaoh.so, where parsing and graph queries execute. Your repository metadata is sent to and stored on Pharaoh's servers (see Data & Privacy below). The proxy itself does not parse code or store data locally.

Authentication & Permissions

OAuth flow: GitHub device authorization grant (RFC 8628). You approve access in your browser — no secrets are embedded in the package.

GitHub App scopes (when installed on your org):

• contents: read — read-only access to parse repository files via tree-sitter
• metadata: read — repo names, languages, default branch
• Webhooks on push events — triggers automatic graph refresh when code changes

No write access. The GitHub App cannot modify code, create branches, open PRs, or change settings.

Credential storage: ~/.pharaoh/credentials.json — OAuth access token + refresh token. Tokens expire after 7 days with automatic refresh. Clear with npx @pharaoh-so/mcp --logout.

Data & Privacy