pharaoh

Codebase knowledge graph with 8 development workflow skills. Query architecture, dependencies, blast radius and dead code via MCP. Requires GitHub App installation (read-only repo access) and OAuth authentication. Connects to external MCP server at mcp.pharaoh.so.

Dan Greer@0xuxdesign

Install

openclaw skills install @0xuxdesign/pharaoh

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:

Downloads the @pharaoh-so/mcp npm package (source, npm)
Copies 8 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)
Adds an MCP server entry "pharaoh" to ~/.openclaw/openclaw.json under mcpServers (skips if already present, refuses to write if JSON is corrupted)
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 agent 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
checks: write — posts PR Guard results as GitHub checks (Pro)
Webhooks on push and pull_request events — push refreshes the graph; pull requests run PR Guard

No write access to code. Checks is the App's only write permission. It 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

How parsing works: Pharaoh clones your repos server-side using GitHub App installation tokens, then runs its open-source parser (tree-sitter based, MIT licensed) to extract structural metadata. Source files are read during parsing to build the AST. After parsing, cloned files are deleted from disk. The extracted metadata is:

Function/class names, signatures, and export visibility
File paths and module membership
Import/export relationships and call chains
Complexity scores (cyclomatic complexity)
JSDoc/docstring text (encrypted at rest with per-tenant AES-256-GCM keys)

What is NOT stored: Source code bodies (function implementations, template literals, string contents, etc.). The graph contains names, paths, relationships, and scores. Source files are cloned temporarily for parsing, then deleted — they are not persisted or logged.

Where data lives: Neo4j knowledge graph on Neo4j Aura (cloud, GCP). Pharaoh is a remote service — your metadata is stored on Pharaoh's infrastructure, not locally. Each tenant's data is isolated via application-level repo-anchoring (every query scoped to your repos) and ownership checks.

Data retention: Graph data persists while your account is active. Deleting a repo from Pharaoh purges all its nodes and relationships. Account deletion removes all tenant data.

Network endpoints contacted:

mcp.pharaoh.so — MCP server (tool calls and responses)
github.com — OAuth authorization and API calls (repo metadata, installation tokens)

When to Use

After installation, the core pharaoh skill loads automatically in sessions where Pharaoh MCP tools are available. It teaches your agent to query architecture before reading files, check blast radius before modifying code, and search functions before creating duplicates. The seven other skills are invoked on demand by name.

What You Get

8 MCP Tools — six that answer architecture questions (get_codebase_map, get_module_context, search_functions, pharaoh_recon, get_blast_radius, get_unused_code), pharaoh_account for your plan and mapped repos, and pharaoh_manage_repo to re-map a repo now.

8 Development Skills:

Category	Skills
Core	`pharaoh` (architectural habits, loads when MCP tools are present)
Planning	`pharaoh:plan`, `pharaoh:brainstorm`
Implementation	`pharaoh:tdd`, `pharaoh:debug`, `pharaoh:refactor`
Verification	`pharaoh:verify`, `pharaoh:review`

Setup Steps

Install the GitHub App on your org at github.com/apps/pharaoh-so — grants read-only access to selected repos
Pharaoh auto-maps selected repos into a knowledge graph (typically < 5 minutes)
Run npx @pharaoh-so/mcp --install-skills — installs skills + connects MCP server
Authorize via the device code shown in terminal (opens GitHub OAuth in browser)
Your agent now queries architecture instead of reading files one at a time

Uninstall

bash

# Remove skills (installed by --install-skills)
rm -rf ~/.openclaw/skills/pharaoh*
# Remove MCP server entry from ~/.openclaw/openclaw.json (delete the "pharaoh" key under mcpServers)

# If using Claude Code directly (without OpenClaw):
claude mcp remove pharaoh

# Remove stored credentials
npx @pharaoh-so/mcp --logout
# or: rm ~/.pharaoh/credentials.json