pharaoh

Codebase knowledge graph with 23 development workflow skills. Query architecture, dependencies, blast radius, dead code, and test coverage via MCP. Requires...

Security Scan

The skill's declared actions (installing an npm MCP client, adding an MCP server entry, and sending repository metadata to a remote Pharaoh service) are coherent with its description, but it relies on fetching code at install time and sending repo metadata to an external server so review is recommended before use.

Purpose & Capability

The name/description (codebase knowledge graph, MCP-based skills) align with required binaries (npx, node), the config path (~/.pharaoh/credentials.json), and network endpoints (mcp.pharaoh.so, github.com). Nothing requested appears unrelated to the stated purpose.

Instruction Scope

SKILL.md instructs running npx to install @pharaoh-so/mcp which copies SKILL.md skill files into ~/.openclaw/skills, adds an MCP entry to ~/.openclaw/openclaw.json, and then uses a local stdio proxy to relay requests to mcp.pharaoh.so where repositories are cloned and parsed server-side. This is coherent but does mean repository metadata and temporary clones are sent to an external service — a privacy/trust decision rather than a protocol mismatch.

Install Mechanism

No registry install spec is present; runtime install uses npx to pull an npm package. Fetching and running an external npm package is expected here but is higher risk than an instruction-only skill because arbitrary code is downloaded/executed at install/runtime. The SKILL.md points to a GitHub repo and npm package which should be audited before running.

Credentials

No unexpected environment variables or unrelated credentials are requested. The single config path (~/.pharaoh/credentials.json) is consistent with OAuth device flow and storing tokens. Note: the skill needs write access to ~/.openclaw/ and ~/.pharaoh/, which may contain other tooling config; adding an MCP entry to openclaw.json is part of its function.

Persistence & Privilege

The skill is not always-enabled and does not install background services. It writes its own credentials file and an MCP server entry in the OpenClaw config, which is normal for this functionality and does not indicate elevated system privileges.

Assessment

This skill appears to do what it says: it installs an npm MCP client, adds its skills to your OpenClaw skills folder, and relays repository metadata to Pharaoh's remote MCP server for parsing. Before installing: 1) Review the @pharaoh-so/mcp npm package source (GitHub and npm) to ensure you trust the code being fetched by npx. 2) Confirm your organization is comfortable installing the Pharaoh GitHub App (read-only contents and webhooks) and that its read-only scope meets policy. 3) If your repos contain sensitive information, consider using Pharaoh's self-hosted option or restrict installations to non-sensitive repositories — the service clones repos server-side and sends structural metadata to mcp.pharaoh.so. 4) Note tokens will be stored at ~/.pharaoh/credentials.json (owner-only permissions) and the installer will modify ~/.openclaw/openclaw.json and overwrite existing pharaoh skill files under ~/.openclaw/skills. 5) If you need higher assurance, ask for an install spec or publishable checksum for the npm package so you can validate the exact code that will run. If you want, I can list the specific things to audit in the GitHub repo and npm package before you run npx.

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

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. For self-hosted options, see documentation.

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 22 other skills are invoked on-demand by name.

What You Get

22 MCP Tools — codebase map, module context, function search, blast radius, dependency queries, dead code detection, test coverage, regression risk, and more.

23 Development Skills:

Category	Skills
Core	pharaoh (architectural habits, loads when MCP tools are present)
Planning	pharaoh:plan, pharaoh:brainstorm, pharaoh:execute, pharaoh:sessions, pharaoh:parallel
Implementation	pharaoh:tdd, pharaoh:debug, pharaoh:refactor, pharaoh:investigate, pharaoh:explore
Verification	pharaoh:verify, pharaoh:wiring, pharaoh:review, pharaoh:review-receive, pharaoh:pr, pharaoh:review-codex
Maintenance	pharaoh:health, pharaoh:debt, pharaoh:audit-tests, pharaoh:onboard
Git	pharaoh:worktree, pharaoh:finish

Setup Steps

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

Uninstall

# 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

Links

• Documentation: https://pharaoh.so/docs
• GitHub (parser, open-source): https://github.com/Pharaoh-so/pharaoh-parser
• GitHub (MCP proxy): https://github.com/Pharaoh-so/pharaoh-mcp
• npm: https://www.npmjs.com/package/@pharaoh-so/mcp
• MCP Server: https://mcp.pharaoh.so
• Security contact: [e-mail]