> For the complete documentation index, see [llms.txt](https://pharaoh.so/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pharaoh.so/docs/guides/map-open-source.md). # 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://pharaoh.so/docs/guides/map-open-source.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.