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) - 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) - 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 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 - INLINECODE15 — 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) - INLINECODE20 — 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 | INLINECODE22 (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
- 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
CODEBLOCK0
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: security@pharaoh.so
技能名称: pharaoh
详细描述:
Pharaoh — 代码库知识图谱 + 开发者技能库
Pharaoh 在服务端解析你的源文件，提取结构元数据（名称、签名、导入、关系），并将这些元数据（而非源代码主体）存储在知识图谱中。AI 代理随后查询该图谱，而不是逐个读取文件。
安装程序的作用
运行 npx @pharaoh-so/mcp --install-skills 会执行以下操作：
- 1. 下载 @pharaoh-so/mcp npm 包（源码，npm）
- 复制 23 个技能目录（SKILL.md markdown 文件）到 ~/.openclaw/skills/ — 警告：重新安装时会覆盖现有的 pharaoh 技能文件（使用 force: true 的 cpSync；不会触及非 pharaoh 技能）
- 添加 MCP 服务器条目 pharaoh 到 ~/.openclaw/openclaw.json 的 mcpServers 下（如果已存在则跳过，如果 JSON 损坏则拒绝写入）
- 如果未检测到 OpenClaw（~/.openclaw/ 不存在），则打印手动安装说明并退出 — 不会创建目录或修改配置
认证在 MCP 服务器首次运行时单独进行（不在 --install-skills 期间）：
- - 设备流程（RFC 8628）— 显示一个代码，你在任何有浏览器的设备上授权
- 凭据存储在 ~/.pharaoh/credentials.json（文件权限 0600，仅所有者可访问）
不会安装后台进程。没有定时任务。没有系统服务。
架构： @pharaoh-so/mcp 包运行一个本地 stdio 代理进程 — 当你的 AI 客户端启动它时开始运行，会话结束时停止。此代理将 MCP 消息中继到远程 Pharaoh 服务器 mcp.pharaoh.so，解析和图查询在此执行。你的仓库元数据被发送并存储在 Pharaoh 的服务器上（参见下面的数据与隐私）。代理本身不解析代码或本地存储数据。
认证与权限
OAuth 流程： GitHub 设备授权许可（RFC 8628）。你在浏览器中批准访问 — 包中不嵌入任何密钥。
GitHub 应用范围（当安装到你的组织时）：
- - contents: read — 通过 tree-sitter 解析仓库文件的只读访问权限
- metadata: read — 仓库名称、语言、默认分支
- push 事件的 Webhooks — 当代码更改时触发自动图谱刷新
无写入权限。 GitHub 应用无法修改代码、创建分支、打开 PR 或更改设置。
凭据存储： ~/.pharaoh/credentials.json — OAuth 访问令牌 + 刷新令牌。令牌在 7 天后过期，自动刷新。使用 npx @pharaoh-so/mcp --logout 清除。
数据与隐私
解析工作原理： Pharaoh 使用 GitHub 应用安装令牌在服务端克隆你的仓库，然后运行其开源解析器（基于 tree-sitter，MIT 许可）来提取结构元数据。在解析期间会读取源文件以构建 AST。解析后，克隆的文件会从磁盘删除。提取的元数据包括：
- - 函数/类名称、签名和导出可见性
- 文件路径和模块成员关系
- 导入/导出关系和调用链
- 复杂度评分（圈复杂度）
- JSDoc/文档字符串文本（使用每个租户的 AES-256-GCM 密钥进行静态加密）
不存储的内容： 源代码主体（函数实现、模板字面量、字符串内容等）。图谱包含名称、路径、关系和评分。源文件被临时克隆用于解析，然后删除 — 它们不会被持久化或记录。
数据存储位置： Neo4j Aura（云，GCP）上的 Neo4j 知识图谱。Pharaoh 是一个远程服务 — 你的元数据存储在 Pharaoh 的基础设施上，而非本地。每个租户的数据通过应用级别的仓库锚定（每个查询限定于你的仓库）和所有权检查进行隔离。关于自托管选项，请参阅文档。
数据保留： 当你的账户活跃时，图谱数据持续存在。从 Pharaoh 删除一个仓库会清除其所有节点和关系。账户删除会移除所有租户数据。
接触的网络端点：
- - mcp.pharaoh.so — MCP 服务器（工具调用和响应）
- github.com — OAuth 授权和 API 调用（仓库元数据、安装令牌）
何时使用
安装后，核心 pharaoh 技能会在 Pharaoh MCP 工具可用的会话中自动加载。它教会你的代理在读取文件前查询架构，在修改代码前检查影响范围，以及在创建重复项前搜索函数。其他 22 个技能按名称按需调用。
你将获得
22 个 MCP 工具 — 代码库地图、模块上下文、函数搜索、影响范围、依赖查询、死代码检测、测试覆盖率、回归风险等。
23 个开发技能：
| 类别 | 技能 |
|---|
| 核心 | pharaoh（架构习惯，当 MCP 工具存在时加载） |
| 规划 |
pharaoh:plan、pharaoh:brainstorm、pharaoh:execute、pharaoh:sessions、pharaoh:parallel |
|
实现 | pharaoh:tdd、pharaoh:debug、pharaoh:refactor、pharaoh:investigate、pharaoh:explore |
|
验证 | pharaoh:verify、pharaoh:wiring、pharaoh:review、pharaoh:review-receive、pharaoh:pr、pharaoh:review-codex |
|
维护 | pharaoh:health、pharaoh:debt、pharaoh:audit-tests、pharaoh:onboard |
|
Git | pharaoh:worktree、pharaoh:finish |
设置步骤
- 1. 安装 GitHub 应用 到你的组织，访问 github.com/apps/pharaoh-so — 授予对选定仓库的只读访问权限
- Pharaoh 自动将选定的仓库映射到知识图谱中（通常 < 5 分钟）
- 运行 npx @pharaoh-so/mcp --install-skills — 安装技能 + 连接 MCP 服务器
- 通过终端中显示的设备代码进行授权（在浏览器中打开 GitHub OAuth）
- 你的代理现在查询架构，而不是逐个读取文件
卸载
bash
移除技能（由 --install-skills 安装）
rm -rf ~/.openclaw/skills/pharaoh*
从 ~/.openclaw/openclaw.json 中移除 MCP 服务器条目（删除 mcpServers 下的 pharaoh 键）
如果直接使用 Claude Code（不使用 OpenClaw）：
claude mcp remove pharaoh
移除存储的凭据
npx @pharaoh-so/mcp --logout
或：rm ~/.pharaoh/credentials.json
链接
- - 文档：https://pharaoh.so/docs
- GitHub（解析器，开源）：https://github.com/Pharaoh-so/pharaoh-parser
- GitHub（MCP 代理）：https://github.com/Pharaoh-so/pharaoh-mcp
- npm：https://www.npmjs.com/package/@pharaoh-so/mcp
- MCP 服务器：https://mcp.pharaoh.so
- 安全联系：security@pharaoh.so
