Map Open-Source Repos

Your AI tool needs to understand a library's architecture to use it well - where the public API lives, how modules connect, what the entry points are. Pharaoh can map any public GitHub repo. Once mapped, you query it the same way you query your own code.

The workflow

1. Map the repo

Ask your AI tool:

Map the vercel/next.js repo so I can query it.

This triggers map_open_source_repo. Pharaoh clones the public repo, parses it with tree-sitter, and builds the knowledge graph. This takes 1-5 minutes depending on repo size.

Pharaoh supports TypeScript and Python repos. The repo must be public on GitHub.

2. Explore the architecture

Ask your AI tool:

What modules does next.js have?

This triggers get_codebase_map on the mapped repo. You get the full module list, dependency graph, entry points, and hot files - the same output you get for your own repos.

3. Trace dependencies

Ask your AI tool:

How does the routing module connect to the build module in next.js?

This triggers query_dependencies. You get forward and reverse dependency paths, circular dependency warnings, and shared dependencies between the two modules.

4. Search for specific functions

Ask your AI tool:

Find all functions related to caching in next.js.

This triggers search_functions across the mapped repo. Useful when you need to understand how a library implements a specific feature, or when you're debugging behavior that originates in a dependency.

What to look for

• Module boundaries - where the library draws its internal lines. Understanding the module structure helps you predict which parts of the library are affected when you see a breaking change in a release.

• Entry points - the public API surface. These are the functions you're actually calling. Everything else is internal implementation that could change without notice.

• Dependency paths - how data flows through the library. When debugging unexpected behavior, tracing the dependency path from the function you called to the internal module that's misbehaving is faster than reading source files one at a time.

Tips

• Map your key dependencies. If your app depends on a framework or library, understanding its architecture makes debugging faster and usage more correct. You stop guessing at API behavior and start seeing the implementation structure.

• Mapped public repos are shared across all Pharaoh users. If someone else already mapped the repo, your query returns results immediately - no waiting for a fresh parse.

• For large monorepos (50K+ files), the initial mapping takes longer. If you only care about a specific package within the monorepo, mention that in your prompt - the AI can scope subsequent queries to the relevant module.