Reading unfamiliar code is a different skill from reading notes. You are not following an argument. You are tracing which pieces call each other, where data goes, and what depends on what. A folder full of files does not show you that shape. You build it in your head, file by file.
Coding agents can now do that tracing for you. Claude Code and Codex can open a repository on your machine, read the files that matter, and work out how the parts fit together. With MindMap AI connected, the agent turns what it finds into a mind map you can open, edit, and share. You do not paste anything. The agent reads the code, and the map appears in MindMap AI.
This guide covers both agents, tested on the same open source project (Uptime Kuma), so you can use whichever one is already part of your workflow.
What you get
Short answer: a mind map of your project's architecture, created directly in MindMap AI by a coding agent that has read the actual code.
A repository is organised for a compiler, not for a person trying to get oriented. A mind map reorganises the same information around what a person needs to understand first:
- Entry points. Where execution starts and what triggers each path.
- Core logic versus helpers. The main flow, separated from the supporting code.
- Data flow. What gets passed where and what comes back.
- Dependencies. What each part relies on, inside the project and outside it.
Once that is a map instead of a folder tree, onboarding onto a new codebase, reviewing a large pull request, or explaining an architecture to someone else all get faster.
Who this is for
- Developers joining a new codebase who need to get oriented before making changes.
- Tech leads preparing an architecture overview for a review or a new hire.
- Technical writers documenting how a system works when no diagram exists yet.
- Students learning to read real code and wanting to see its shape, not just the syntax.
- Open source contributors trying to understand a project before opening a pull request.
Why use a coding agent on a local repo
Short answer: Claude Code and Codex read your code the way a developer does, with file search and shell tools, so they can handle a whole project instead of one pasted file.
You could paste a file into a normal chat and ask for a structure. That works for one function. It falls apart at the project level because a chat window has no way to explore a repository.
A coding agent is different. It runs on your machine, in the folder where your code already lives. It can list the tree, search for a function name across every file, read only the files it needs, and follow imports. That is what makes a project-level map possible. And because it works on your local clone, it uses the same up-to-date code you are editing, so the map can be refreshed whenever the code changes (more on that below).
Both agents connect to MindMap AI through MCP, so the agent creates and edits the map directly. If you have not connected MindMap AI yet, follow the setup guides first: how to use MindMap AI in Claude, how to use MindMap AI in ChatGPT, or the integrations help centre.
Before you start: one prompt that works
Short answer: ask for an architecture map organised by responsibility, limited to about three levels deep, and tell the agent which folders to skip.
The most common mistake is asking for everything at once: folder structure, every file, every feature, and how they all connect. That produces a map with hundreds of nodes that nobody can read. Every node the agent creates also uses MindMap AI credits (see the pricing page for how credits work), so a scoped first pass is cheaper as well as clearer.
Use this as your starting prompt with either agent:
Analyze this project and create a mind map in MindMap AI titled "[Project name] Architecture". Organise it by responsibility (for example: entry points, front end, back end and API, data layer, external services), not by folder. Go about three levels deep and keep it to roughly 40 to 80 nodes. Name nodes after the real files, classes, and functions. Group large sets of similar files, such as notification providers or migrations, into one node with a count and a few examples. Skip node_modules, .git, build output, and vendored dependencies. Add a short note to each top-level branch explaining what it does.
Give the map a clear title. You will use that title later when you ask the agent to update it.
How to turn a codebase into a mind map with Claude Code
Claude Code runs inside the Claude desktop app and in the terminal. This walkthrough uses the desktop app.
1. Connect MindMap AI, then open your project
Connect MindMap AI in Claude first. Connectors you add in Claude are available in Claude Code automatically, but only for sessions started after you connect. If you connect while a session is already open, start a new session.
Then open the Claude desktop app, go to Code, and start a new session. In the composer, set the environment to Local and pick the folder that holds your project. The folder name and branch appear as chips above the prompt box.
2. Ask Claude Code to map the project
Paste the starting prompt from above. Claude Code explores the folder, reads the files it needs, and sends the structure to MindMap AI, which builds the map. You can watch it work: it lists directories, inspects the server class, routers, models, and front-end routes, then calls MindMap AI once it has what it needs.
3. Review and refine
The map renders inside the session as soon as it is created. Check the main branches. Are the entry points right? Are external services and third-party libraries their own branch? Is anything important missing?
Refine in the same conversation. Claude Code edits the existing map rather than starting over. For example:
Expand the "Data layer" branch and show how a record moves from the API request to the database and back.
Add a "Read these first" branch listing the five files a new developer should understand before anything else.
The map is too detailed. Collapse the helpers into a single branch and keep only the top two levels elsewhere.
Create a beginner-friendly version that explains what each top-level folder is for.
4. Keep working in MindMap AI
Open the map in MindMap AI to rearrange branches, rename nodes, add notes, change the layout, or share it with your team.
How to turn a codebase into a mind map with Codex
Codex is OpenAI's coding agent. Since July 2026 it lives inside the ChatGPT desktop app for macOS and Windows, alongside Chat and Work. It is also available as a command-line tool and an IDE extension.
1. Install the MindMap AI plugin, then open your project
In the ChatGPT desktop app, install the MindMap AI plugin from the plugin directory and connect your account. Plugin connections are shared across Chat, Work, and Codex.
Switch to Codex and start a new task. Select the local folder that holds your project; the folder, Local, and branch appear as chips above the prompt box. In the panel on the right, under Sources, add MindMap AI so the task can use it.
If you use Codex from the terminal or an IDE instead, add MindMap AI as a Streamable HTTP MCP server pointing at https://mindmapai.app/mcp. The steps are in the integrations help centre.
2. Ask Codex to map the project
Paste the starting prompt. Codex reads the workspace, identifies the relationships between files, and uses MindMap AI to build the map. Expect it to take a few minutes on a project this size.
On Uptime Kuma, Codex landed at 77 nodes and grouped the big file sets the way the prompt asked: 109 notification providers, 27 monitor types, and 63 migrations each became a single node with a count instead of a folder dump.
3. Review and refine
Check the map the same way: entry points, main components, external dependencies. Then refine in the same task. For example:
Organise the map into user interface, business logic, data storage, and external services.
Expand the monitoring engine and show how a heartbeat is recorded and evaluated.
Highlight the files another developer should understand first.
Simplify this for someone without coding experience.
4. Keep working in MindMap AI
Open the map in MindMap AI to edit, restyle, or share it.
Keep the map current as the code changes
Short answer: re-run a saved prompt after each merge and ask the agent to update the existing map instead of creating a new one.
An architecture diagram goes stale the week after someone draws it. This workflow does not have that problem, because the agent that made the map can also update it. MindMap AI's connector lets the agent add, rename, move, and delete nodes on an existing map, so the map can follow the code.
After a batch of changes, run something like this in a new session on the same folder:
Find my mind map titled "[Project name] Architecture" in MindMap AI. Run git log --since="14 days ago" --name-only --pretty=format: to see which files changed. Compare the changed files with the map, update only the affected branches, and add a branch called "Changed in the last two weeks" that lists what was added, what moved, and what was removed.
One thing to check first: your clone needs history. A shallow clone (git clone --depth 1) has no past commits, so git reports every file as new. Run git fetch --unshallow if you cloned that way.
Save the prompt. Running it takes a few minutes and gives you a living architecture map plus a change summary you can drop into a team update. The refresh is something you trigger, whenever suits your team: after each release, at the end of a sprint, or as part of an onboarding checklist. Keep the map title unique so the agent finds the right one.
Other ways to do this
Short answer: for a small repository or a single pull request, a GitHub connector in a normal Claude or ChatGPT chat is enough. For a real project, use the local agent.
You can connect GitHub to Claude or ChatGPT and ask the chat to map a repository straight from GitHub, with no local clone. This works for small repos, a single file, or the diff in one pull request. It struggles on anything larger, because a chat model has no search or shell tools. It has to request files one at a time and hold everything in one context window, so it tends to skim and generalise.
Claude Code and Codex on a local folder avoid that. They search, follow imports, and read selectively, which is why the map reflects the code rather than a guess about it. Note that Claude Code on the web currently exposes only its built-in GitHub integration, so the MindMap AI connector is available in the desktop app and terminal, not in web sessions.
Types of code this works well for
- A whole service or application. The main use case: map the architecture before you change it.
- One module or package. Point the agent at a subfolder for a focused map.
- Class hierarchies. Parent and child classes, and which methods are overridden.
- API structure. Endpoints, request flow, and what each endpoint touches.
- An unfamiliar legacy codebase. Build a mental model before making changes.
- A large pull request. Ask the agent to map only the files in the diff to see what changed structurally.
Common mistakes to avoid
- Asking for everything in one map. Scope the first pass to architecture by responsibility, then expand the branches you care about.
- Letting the agent map vendored code. Tell it to skip node_modules, .git, build folders, and generated files, or they will dominate the map.
- Mapping by folder instead of by responsibility. Folder layout and architecture are not the same thing. Ask for the map to be organised by what each part does.
- Losing external dependencies. If the code calls a library, service, or API, make sure it appears as its own branch. It is often the first thing a new developer needs to know.
- Skipping verification. The agent decides what counts as "important". Check the entry points, error handling, and integrations against the code. Treat the map as a strong first draft.
- Forgetting the title. Give the map a unique title so you can ask the agent to update it later.
Tips for better results
- Name the language and framework if the repo mixes several. It helps the agent apply the right conventions.
- Ask for a specific kind of map. Call flow, class hierarchy, and data flow each produce a different, more useful map than a generic "structure".
- Keep node names tied to real code. Real file, class, and function names keep the map useful as a reference next to the code.
- Ask for notes, not just labels. A one-line note on each top-level branch turns the map into documentation.
- Save your prompts. The first prompt and the update prompt are the whole workflow. Keep them in the repo's README or a team wiki.
FAQ
Yes. Claude Code and Codex both work across mainstream languages, and they read a repository the same way regardless of what it is written in: by listing files, searching, and following imports. For less common languages, name the language and framework in your prompt so the agent applies the right conventions when it decides what counts as an entry point, a module, or a dependency. Mixed-language repositories, such as a TypeScript front end with a Python back end, work too. In that case ask for the map to be organised by responsibility, so the front end and back end each get their own branch instead of being mixed together.
Yes, and that is the normal way to use it. Because the agent works on the local folder with search and shell tools, it is not limited to what fits in one paste. The real limit is readability. A map with several hundred nodes is not useful to anyone, so ask for an architecture-level first pass of roughly 40 to 80 nodes, then expand the branches you need in follow-up prompts. For very large monorepos, map one service or package at a time and give each map its own title.
Re-run an update prompt on the same folder and tell the agent to find the existing map by title. MindMap AI's connector lets the agent edit the map in place, so it can update only the branches touched by recent changes and add a branch summarising them. There is no automatic scheduler in this workflow. You decide when to refresh: after a release, at the end of a sprint, or whenever a new person joins. Because it is a saved prompt, refreshing takes a few minutes. Make sure your clone has git history, since a shallow clone reports every file as new.
You can, and for a small repository or a single pull request it is a reasonable shortcut. Connect GitHub to Claude or ChatGPT, ask the chat to read the repository, and have it create the map in MindMap AI. For anything larger, the local agent gives better results. Claude Code and Codex can search across files and read selectively, while a chat model has to pull files one at a time into a single context window and tends to produce a shallower map.
Not at the moment. Claude Code on the web exposes only its built-in GitHub integration, not the connectors from your Claude account, so MindMap AI is not available there. Use Claude Code in the desktop app or the terminal, where connectors you have added in Claude are available automatically for any session started after you connect.
No. Claude Code or Codex reads your files locally, or within its own environment. What reaches MindMap AI is the content the agent decides to put on the map: node names, short notes, and the structure between them. Your source files are not uploaded to MindMap AI. Even so, avoid asking the agent to include configuration values or secrets in node text, as you would with any tool that stores notes.
No. Think of it as a fast way to get oriented, and as a first draft for a diagram or an onboarding document. It is also a good way to notice where the documentation and the code have drifted apart. Always verify the map against the code, especially error handling, edge cases, and integrations.
Yes. The map is a normal MindMap AI map. You can rename branches, move nodes, add notes and links, change the layout, or restyle it, and you can share it with your team like any other map. You can also keep refining it through the agent in later sessions.
Final takeaway
Code holds its structure in syntax, and you normally have to rebuild that structure in your head every time you open an unfamiliar project. Claude Code and Codex can do the reading, and MindMap AI turns what they find into a map you can look at while you work. Open the next unfamiliar repository with the agent, run the prompt, and see the codebase instead of the code.
