Analyze once.
Reuse context everywhere.

DevMap reads your codebase and writes a map that developers and AI agents start from: entry points, critical files, features and routes. Read it as files, or let your agent ask over MCP.

npm i -g @flaid/devmap

Read the docs

Needs Node 22 or newer. An API key is optional and only adds the AI layer.

~/your-project

$ npx @flaid/devmap analyze

✓scanning files

✓building dependency graph

✓detecting framework · routes · database

✓ranking critical files

→writing .devmap/index.json

context ready for any agent

Illustrative output.

Works with every agent.

One devmap analyze for Claude Code, Codex, Cursor, Gemini CLI, OpenCode and more. If a tool can read files, it can read the map. If it speaks MCP, it can ask for it.

Use it with your agent GitHub

Claude Code
Codex
Cursor
OpenCode
Gemini CLI
Windsurf
GitHub Copilot
Cline
Kilo Code
Roo Code
Amp
Antigravity

AGENTS.md
```
Start at .devmap/index.json
then the feature map
then source files
```
Instructions
Tells the agent the reading order and where the map lives. Written once by init, never overwritten.
.devmap/index.json
```
"entryPoints": [
  "src/index.ts"
],
```
Entry point
Entry points, critical files and a pointer to every feature. Small enough to read first.
.devmap/features/*.json
```
"name": "Billing",
"files": [
  "src/billing/…"
```
Feature maps
One file per feature with the files that implement it, so the agent opens only what it needs.

Or let the agent ask.

devmap mcp runs DevMap as an MCP server. The agent calls a tool and gets structured JSON back, so it reads only the part of the map it needs. Read-only by default, and every answer says if the snapshot is stale.

Analyze once
Run devmap analyze in the project. It writes .devmap/snapshot.json.
Register the server
Add the command below to Claude Code, or the config to Cursor, Codex and opencode.
Ask the agent
It calls the tools it needs instead of reading the whole map up front.

Claude Code

claude mcp add devmap -- npx -y @flaid/devmap mcp

.mcp.json

{
  "mcpServers": {
    "devmap": {
      "command": "npx",
      "args": ["-y", "@flaid/devmap", "mcp"]
    }
  }
}

Nothing is sent anywhere. --auto-refresh and --allow-ai are opt-in.

devmap_overview
Framework, entry points, critical files, features and flows. Where an agent starts.
devmap_map
Dependency map of the project, one feature or one file.
devmap_flow
Trace a feature or an API request from entry to database.
devmap_routes
List page and API routes.
devmap_impact
What breaks if this file changes, followed through the import graph.
devmap_find
Find features, files and routes by keyword.
devmap_analyze
Re-analyze and refresh the snapshot. Writes only inside .devmap/.
devmap_explain
Explain a file, feature or function with your own AI key.
needs --allow-ai

MCP setup for your client

The code didn't change. The understanding gets rebuilt anyway.

Every new session, every new agent and every new teammate starts the same way: open files, trace imports, guess which ones matter.

Without DevMap

RepositoryClaude explores filescontext rebuilt
RepositoryCodex explores filescontext rebuilt
RepositoryNew session explores filescontext rebuilt

With DevMap

Repositorydevmap analyzeshared project context

Claude Code
Codex
Cursor
Gemini CLI
Windsurf
future agents

Your project, as files an agent can read.

devmap analyze writes a .devmap folder next to your code. Agents open the small index first and follow it to the one feature they need, instead of exploring the whole repository.

01
.devmap/index.json
Start here. Entry points, critical files and a pointer to each feature.
02
.devmap/features/*.json
One map per feature, with the files that implement it.
03
.devmap/snapshot.json
The full analysis, read only when the two above are not enough.

.devmap/index.jsonhighlighted: entry points

{  "project": {    "name": "devmap-workspace",    "framework": "astro",    "language": "typescript",    "workspaceType": "monorepo"  },  "entryPoints": [    "packages/cli/src/index.ts",    "apps/web/src/pages/docs.astro",    "apps/web/src/pages/index.astro"  ],  "criticalFiles": [    "packages/cli/src/commands/analyze.ts",    "packages/cli/src/commands/init.ts",    "packages/cli/src/commands/map.ts"  ],  "features": [    {      "name": "CLI Commands",      "map": ".devmap/features/cli-commands.json"    }  ]}

Trimmed, from analyzing this repository.

Nine commands.

Pick one and see what it prints. Most of them need no API key.

Set up

~/devmapillustrative

devmap init

◆ Validating Groq API key

◆ Groq API key is valid

◆ Config saved to ~/.devmap/config.json

◆ Added .devmap/ to .gitignore

◆ Created DEVMAP.md

◆ Created AGENTS.md

◆ Next: devmap analyze

~/devmapillustrative

devmap config model llama-3.3-70b-versatile

◆ Default model override set to llama-3.3-70b-versatile.

~/devmapoutput from this repo

devmap doctor

DevMap Doctor

DevMap 0.8.3

Node.js v22.23.4 (supported)

OS linux/x64

Project devmap-workspace

Framework astro

Package Manager pnpm

Provider not configured

Config missing

Snapshot valid

API key not configured

Issues

◆ Run devmap init to create ~/.devmap/config.json.

Map

~/devmapoutput from this repo

devmap analyze

DevMap Analyze

◆ Scanning ~/devmap

◆ Scanned 377 files

◆ Mapping dependencies

◆ Detected 7 features

◆ Project index built

Project devmap-workspace

Framework astro

Language typescript

Package Manager pnpm

Files 377

Lines 55284

Entry Points

◆ packages/cli/src/index.ts

◆ apps/web/src/pages/docs.astro

… 3 more

◆ Snapshot saved to .devmap/snapshot.json

◆ Agent navigation saved to .devmap/index.json and .devmap/features/

~/devmapoutput from this repo

devmap map

DevMap — map: project

Features

- AI Integration (5 files)

- Caching (5 files)

- CLI Commands (9 files)

- Doc (5 files)

- Documentation (11 files)

- Home (16 files)

- Testing (1 file)

Feature relationships

- Caching → AI Integration

- CLI Commands → AI Integration

- CLI Commands → Caching

- Doc → Home

- Documentation → Doc

48 of 377 files belong to a detected feature.

◆ Wrote .devmap/maps/project.mermaid

~/devmapoutput from this repo

devmap flow

AI flow narration is not configured. Run devmap init to enable it.

Flows written

◆ AI Integration flow

◆ Caching flow

◆ CLI Commands flow

◆ Request /robots.txt

◆ Request /sitemap.xml

◆ Wrote .devmap/flows/cli-commands-flow.md

◆ Wrote .devmap/flows/cli-commands-flow.mermaid

Read

~/devmapoutput from this repo

devmap onboarding

DevMap Onboarding

devmap-workspace

Typescript · Astro · Groq · OpenRouter

What this is

devmap-workspace handles ai integration, caching, cli commands. Integrates with Groq, OpenRouter.

Start here

File examples/todo-app/prisma/schema.prisma

Why read this Understand the data model and entity relationships

File packages/cli/src/index.ts

Why read this Execution entry point — see available commands or routes

File apps/web/src/pages/docs.astro

Why read this Execution entry point — see available commands or routes

~/devmapillustrative

devmap explain packages/cli/src/index.ts

Context files: packages/cli/src/index.ts

Answer

The CLI entry point. It builds the commander program and hands

init, analyze, onboarding, map, flow, explain, config, doctor and mcp

to their command handlers.

Serve

~/devmapillustrative

devmap mcp

DevMap MCP server ready (root: ~/devmap)

Agent calls devmap_impact

→ file: packages/cli/src/commands/analyze.ts, depth: 2

DevMap answers

Features CLI Commands, Caching

Dependents 6 direct, 7 within 2 steps

◆ packages/cli/src/index.ts

◆ packages/cli/src/mcp/refresh.ts

… 4 more

◆ snapshot.stale: false

The same code gives the same map.

Files, imports, routes, features and flows come from static analysis, so the result doesn't change between runs. AI is optional and is used in three places: inferring what the project is for, describing files, and answering questions. If the provider fails, devmap analyze still finishes.

12: pipeline steps
3: optional AI calls
0: keys needed to analyze

Scan files
Analyze files
Build the dependency graph
Detect the framework
Detect routes
Detect the database
Extract entities
Detect capabilities
Detect features
Infer the domainoptional AI
Rank critical files
Generate flows

Routes mapped for 18 frameworks.

Next.js to NestJS, in the same monorepo if that's what you have. JavaScript and TypeScript come first; other languages are read with lighter tools.

Next.jsFull-stack
AstroContent
NuxtFull-stack
SvelteKitFull-stack
RemixFull-stack
React RouterRouting
TanStackRouting
Expo RouterMobile
SolidStartFull-stack
Qwik CityFull-stack
AngularFrontend
ExpressBackend
FastifyBackend
HonoBackend
ElysiaBackend
KoaBackend
AdonisJSBackend
NestJSBackend

Full syntax trees

Exports, symbols and imports read with ts-morph.

TypeScript
JavaScript
Vue
Svelte
Astro

Pattern matching

Imports, exports and declarations.

Python
PHP
Go
Ruby
C#
Java

Run it on the repo you have open.

npx @flaid/devmap analyze

Free and open source under the MIT license. Install it globally with npm install -g @flaid/devmap when you want it on every project.

Read the docs Star it on GitHub

Analyze once.Reuse context everywhere.

Works with every agent.

Instructions

Entry point

Feature maps

Or let the agent ask.

Analyze once

Register the server

Ask the agent

The code didn't change. The understanding gets rebuilt anyway.

Without DevMap

With DevMap

Your project, as files an agent can read.

Nine commands.

Set up

01devmap initSet up DevMap for this project and pick an AI provider if you want one.

02devmap config modelPick the model the AI-powered commands use.needs an AI provider

03devmap doctorCheck your setup and print a report you can paste into a bug report.

Map

04devmap analyzeScan the project and write the .devmap folder. Static analysis, no AI required.

05devmap mapShow the dependency tree from the saved analysis, without scanning again.

06devmap flowWalk a feature or request step by step, as a Mermaid diagram or in the terminal.

Read

07devmap onboardingA reading order for someone new to the codebase: where to start, what to read next.

08devmap explainAsk about a file or feature and get an answer grounded in the analysis.needs an AI provider

Serve

09devmap mcpRun DevMap as an MCP server. Your agent starts it and calls tools; you rarely run it by hand.

The same code gives the same map.

Routes mapped for 18 frameworks.

Full syntax trees

Pattern matching

Run it on the repo you have open.

Analyze once.
Reuse context everywhere.