# Pharaoh — Codebase Intelligence for AI Coding Agents

> Pharaoh maps your codebase into a knowledge graph and gives AI coding tools full architectural awareness — every function relationship, dependency chain, module boundary, and entry point — before they write a single line.

## The Problem Pharaoh Solves

AI coding tools read your codebase one file at a time. On a 200-file repo, the AI sees fragments — never architecture. The result:

- It creates a retry utility without knowing one exists three modules away
- It refactors a function without knowing 14 downstream callers depend on the exact signature
- It writes new endpoints that are never wired to any entry point
- It produces PRDs that ignore existing module boundaries and duplicate existing functionality
- It burns 40K+ context tokens reading files to build understanding that a 2K-token graph query provides instantly

This isn't an AI limitation. It's a context limitation. The AI is smart enough — it just can't see the codebase.

## How It Works

Pharaoh gives AI tools the complete structural picture:

1. **Install the GitHub App** (read-only access, 30 seconds)
2. **Automatic parsing** — tree-sitter extracts every function, import, export, call chain, endpoint, cron handler, and environment variable from TypeScript and Python codebases
3. **Knowledge graph** — all relationships stored in Neo4j with dual-layer per-tenant isolation
4. **MCP endpoint** — your AI tool queries the graph silently before every decision
5. **Always current** — webhooks re-map on every push to your default branch
6. **PR Guard** — automated structural checks on every pull request (reachability, regression risk, test coverage, breaking changes)

No config files. No per-repo setup. No maintenance. Source code is read during parsing and immediately discarded — only structural metadata is stored.

## The 16 MCP Tools

- [Recon](https://pharaoh.so/llms-full.txt#recon): Batched reconnaissance — codebase map + module context + function search + blast radius in one call
- [Codebase Map](https://pharaoh.so/llms-full.txt#codebase-map): Full structural overview — modules, dependency graph, entry points, hot files
- [Module Context](https://pharaoh.so/llms-full.txt#module-context): Complete module profile — files, functions, DB tables, endpoints, env vars, external callers
- [Search Functions](https://pharaoh.so/llms-full.txt#function-search): Search all functions across the codebase before creating duplicates
- [Design System](https://pharaoh.so/llms-full.txt#design-system): Discover design system components, tokens, and anti-patterns before creating UI
- [Blast Radius](https://pharaoh.so/llms-full.txt#blast-radius): Trace all downstream callers before refactoring — endpoints, cron jobs, DB operations affected
- [Query Dependencies](https://pharaoh.so/llms-full.txt#dependencies): Trace how any two modules connect — forward, reverse, circular, shared dependencies
- [Trace Flow](https://pharaoh.so/llms-full.txt#trace-flow): Walk a function's call tree to understand how a feature works — signatures, docs, and connections at every step
- [Check Reachability](https://pharaoh.so/llms-full.txt#reachability): Verify functions are wired to production entry points (API endpoints, CLI, cron handlers, MCP tools)
- [Vision Docs](https://pharaoh.so/llms-full.txt#vision): Compare CLAUDE.md files and PRDs against actual implementation
- [Vision Gaps](https://pharaoh.so/llms-full.txt#vision-gaps): Find specs without code AND complex code without specs
- [Cross-Repo Audit](https://pharaoh.so/llms-full.txt#cross-repo): Compare two repositories for code duplication and structural overlap
- [Consolidation Opportunities](https://pharaoh.so/llms-full.txt#consolidation): Find duplicate code, parallel consumers, competing DB access, signature twins
- [Unused Code](https://pharaoh.so/llms-full.txt#dead-code): Find functions unreachable from any production entry point with text-reference backup verification
- [Test Coverage](https://pharaoh.so/llms-full.txt#test-coverage): Per-module coverage summary — which files have tests, which high-complexity functions lack them
- [Regression Risk](https://pharaoh.so/llms-full.txt#regression-risk): Score functions by likelihood of breaking production — complexity, exposure, churn, caller count

## Operational Tools

- [Request Upload](https://pharaoh.so/llms-full.txt#upload): Get a presigned URL to upload parsed codebase data — map repos without the GitHub App
- [Map Open Source Repo](https://pharaoh.so/llms-full.txt#map-open-source): Map any public GitHub repo into Pharaoh so you can query its architecture with all analysis tools
- [Environment Setup](https://pharaoh.so/llms-full.txt#environment-setup): Install Pharaoh's curated plugin bundle — LSP, security scanning, code review, tailored to your codebase languages
- [Account](https://pharaoh.so/llms-full.txt#account): Manage subscription, toggle PR Guard, trigger graph refreshes
- [Feedback](https://pharaoh.so/llms-full.txt#feedback): Report false positives or provide feedback on tool results
- [Admin](https://pharaoh.so/llms-full.txt#admin): Administrative operations for org management
- [Pharaoh Docs](https://pharaoh.so/llms-full.txt#pharaoh-docs): Query Pharaoh's own documentation — setup, tools, security, pricing, troubleshooting

## Without Pharaoh vs With Pharaoh

### Without Pharaoh
- **Planning a refactor**: AI reads files hoping to find all callers. Misses indirect callers 3 hops away. Breaks an endpoint it didn't know existed.
- **Creating a utility function**: AI writes a new helper. A nearly identical function already exists in another module. Now you have two.
- **Reviewing a PR**: Reviewer manually traces imports to check if new code is wired up. Misses that a new export is unreachable from any entry point.
- **Writing a PRD**: AI produces a spec that proposes building functionality that already exists, in a module it didn't explore.

### With Pharaoh
- **Planning a refactor**: AI queries blast radius — gets every downstream caller, affected endpoint, and impacted cron job. Knows the exact risk before touching anything.
- **Creating a utility function**: AI searches the graph first. Finds the existing function. Imports it instead of duplicating.
- **Reviewing a PR**: AI verifies all new exports are reachable from production entry points. Catches orphaned code before it merges.
- **Writing a PRD**: AI queries the codebase map and module context. The spec is grounded in what actually exists.

## Security

- **Hosted, not installed** — no packages on developer machines, no transitive dependencies to audit, no supply chain attack surface. If Pharaoh gets a vulnerability, we remediate server-side. You do nothing.
- **Read-only GitHub access** — Pharaoh cannot write to your repository, push commits, or modify code. The GitHub App requests repository contents (read) and metadata (read). No write access. Ever.
- **No source code stored** — the graph contains function names, file paths, dependency edges, complexity scores. Source code is read during parsing, used to generate the graph in memory, then discarded. The graph is a table of contents, not the book.
- **Per-tenant isolation** — dual-layer defense: every Neo4j query is repo-anchored AND application-level ownership checks run before every tool call. Both must fail for cross-tenant access. CI enforces this — every new query is automatically tested for isolation violations.
- **Encrypted at rest** — GitHub tokens and sensitive graph properties (signatures, JSDoc, API routes) encrypted with AES-256-GCM using HKDF per-tenant derived keys. Each token uses a unique random initialization vector. Compromising one tenant does not expose others.
- **GitHub-based access control** — remove someone from your GitHub org, their Pharaoh access revokes within minutes. No API tokens to rotate, no credentials on developer machines. Org membership re-verified on every token refresh.
- **Open source parser** — the Cartographer that reads your code is [fully auditable](https://github.com/Pharaoh-so/pharaoh-parser)
- **Account deletion** — uninstall the GitHub App or delete your account: knowledge graph deleted, encrypted tokens destroyed, audit logs retained 90 days then purged. No lock-in.

## Who Benefits Most

- **Solo devs building production apps** — your AI stops creating duplicate code and breaking things it can't see
- **Small teams (2-10) without dedicated DevOps** — architectural awareness without hiring a staff engineer to maintain it
- **Open source maintainers** — evaluate contributor PRs against the full dependency graph, not just the diff
- **Vibe coders** — you move fast and let AI handle the details. Pharaoh makes sure those details include architectural context.
- **CI/CD pipelines and autonomous agents** — device flow and token exchange auth let headless agents query the graph without human interaction
- **Any developer using Claude Code, Cursor, OpenClaw, or MCP-compatible tools** — if your AI tool supports MCP, Pharaoh makes it better

## Why Pharaoh exists - the research

AI coding tools degrade on mature codebases without architectural context:
- 1.7x more bugs in AI-generated code (CodeRabbit, 470 PRs)
- 19% slower on mature codebases - developers thought they were 20% faster (METR RCT, 246 tasks)
- 4x growth in duplicated code blocks (GitClear, 211M lines)
- 154% larger PRs, 91% longer reviews (Google DORA 2025)

Pharaoh fixes the root cause: AI can't see the codebase. A 2K-token graph query replaces 40K tokens of file reading.

Full research: https://pharaoh.so/research

## Optional

- [Full Documentation](https://pharaoh.so/llms-full.txt): Complete tool reference with parameters, use-when triggers, and example output
- [Without vs With](https://pharaoh.so/llms-full.txt#without-vs-with): Concrete before/after scenarios
- [Security Model](https://pharaoh.so/llms-full.txt#security): What Pharaoh stores, what it doesn't, how data is protected
- [Who Benefits](https://pharaoh.so/llms-full.txt#who-benefits): Which developer profiles get the most value
- [Authentication](https://pharaoh.so/llms-full.txt#auth): OAuth, device flow (RFC 8628), and token exchange for CI/CD
- [Architecture](https://pharaoh.so/llms-full.txt#architecture): Why knowledge graphs, deterministic parsing, and Neo4j
- [PR Guard](https://pharaoh.so/llms-full.txt#pr-guard): Automated structural checks on every pull request
- [Dashboard](https://pharaoh.so/llms-full.txt#dashboard): Web UI for repo management, PR Guard config, and audit logs
- [Guided Workflows](https://pharaoh.so/llms-full.txt#guided-workflows): 10 MCP prompt playbooks for planning, reviewing, refactoring, and cleanup
- [Workflow Patterns](https://pharaoh.so/llms-full.txt#workflows): Common multi-tool sequences
- [Pricing](https://pharaoh.so/llms-full.txt#pricing): Free tier, Personal ($27/mo), Team ($99/mo), PR Guard ($5/repo/mo)
- [Configuration](https://pharaoh.so/llms-full.txt#config): .pharaoh.yml per-repo settings
- [Local Parsing](https://pharaoh.so/llms-full.txt#local-parsing): Air-gapped/compliance option — parse locally, upload only metadata
- [FAQ](https://pharaoh.so/llms-full.txt#faq): Common questions about security, pricing, setup, and competitive positioning
- [Parser (open source)](https://github.com/Pharaoh-so/pharaoh-parser): Audit exactly what gets extracted

## Documentation

Full setup guides, how-to guides, and conceptual docs at https://pharaoh.so/docs

- [Pharaoh](https://pharaoh.so/docs)
- [Table of contents](https://pharaoh.so/docs/SUMMARY)
- [Concepts](https://pharaoh.so/docs/concepts)
- [How Pharaoh Works](https://pharaoh.so/docs/concepts/how-it-works)
- [Pricing](https://pharaoh.so/docs/concepts/pricing)
- [Security](https://pharaoh.so/docs/concepts/security)
- [Guides](https://pharaoh.so/docs/guides)
- [Check Test Coverage](https://pharaoh.so/docs/guides/check-test-coverage)
- [Explore Your Codebase](https://pharaoh.so/docs/guides/explore-your-codebase)
- [Find Dead Code](https://pharaoh.so/docs/guides/find-dead-code)
- [Map Open-Source Repos](https://pharaoh.so/docs/guides/map-open-source)
- [Multi-Agent Teams](https://pharaoh.so/docs/guides/multi-agent-teams)
- [Set Up PR Guard](https://pharaoh.so/docs/guides/pr-guard)
- [Review Pull Requests](https://pharaoh.so/docs/guides/review-pull-requests)
- [Refactor Safely](https://pharaoh.so/docs/guides/safe-refactoring)
- [Claude.ai](https://pharaoh.so/docs/setup/claude-ai)
- [Claude Code](https://pharaoh.so/docs/setup/claude-code)
- [Cursor](https://pharaoh.so/docs/setup/cursor)
- [Install the GitHub App](https://pharaoh.so/docs/setup/github-app)
- [Headless / SSH / CI](https://pharaoh.so/docs/setup/headless)
- [OpenClaw](https://pharaoh.so/docs/setup/openclaw)
- [Windsurf](https://pharaoh.so/docs/setup/windsurf)
- [Tools Reference](https://pharaoh.so/docs/tools)
- [Audit Tools](https://pharaoh.so/docs/tools/audit)
- [Investigate Tools](https://pharaoh.so/docs/tools/investigate)
- [Manage Tools](https://pharaoh.so/docs/tools/manage)
- [Orient Tools](https://pharaoh.so/docs/tools/orient)
- [Tool Overview](https://pharaoh.so/docs/tools/overview)