DevMap Docs

Quick Start

npm install -g @flaid/devmap
# or
pnpm add -g @flaid/devmap
# or run without installing
npx @flaid/devmap analyze

Requirements: Node.js 22.12+

devmap init
devmap analyze

Supported frameworks

DevMap detects your stack from package.json first (highest confidence), and falls back to file-structure heuristics only when that’s missing or incomplete.

Full support — framework detection and route mapping:

• Next.js (App Router and Pages Router)
• Astro
• Nuxt
• SvelteKit
• Remix
• React Router v7 (framework mode)
• TanStack Router and TanStack Start
• Expo Router
• SolidStart
• Qwik City
• Angular
• Express
• Fastify
• Hono
• Elysia
• Koa
• AdonisJS
• Nest (NestJS)

SPA client-side routing — framework detected, and routes declared in the client-side router (React Router, Vue Router, svelte-routing, svelte-spa-router) surface as features:

• React (Create React App, Vite)
• Vue
• Svelte

Databases & ORMs — schema/entity extraction, full field + relation fidelity:

• Prisma

Detected as dependency (badge “uses X”), schema extraction not yet implemented: Drizzle, Mongoose, Supabase, TypeORM — on the roadmap.

Raw SQL (table names from query strings, no fields/relations — lowest confidence of the three): PostgreSQL (pg), MySQL (mysql2), SQLite (better-sqlite3)

Anything else (Laravel, Django, Go, …): DevMap still scans your files, dependencies, and import graph — you just won’t get framework-specific route detection. analyze will report the framework as unknown rather than guessing wrong.

Don’t see your framework? Open an issue — route detectors are the easiest part of the codebase to extend.

Privacy & data

Without an API key configured: DevMap runs 100% locally. Zero network calls. init, map, and doctor never send project data — map never touches the network; init only validates your key against the provider’s API, doctor only checks connectivity.

With an API key configured, here’s exactly what leaves your machine, command by command:

Your whole codebase is never bulk-uploaded to generate the snapshot — only explain sends actual file contents, and only for the single file or feature you named in the command.

1. Setup — devmap init

Run once per machine/project.

• Choose provider: Groq (free-tier, default) or OpenRouter
• Enter API key — or set GROQ_API_KEY / OPENROUTER_API_KEY as an env var to skip the prompt entirely
  • Groq keys: console.groq.com/keys
  • OpenRouter keys: openrouter.ai/keys
• Pick a model — Groq shows a live model list to choose from; OpenRouter defaults to openrouter/free, or type any model ID
• Saves config to ~/.devmap/config.json
• Creates .devmap/, adds it to .gitignore
• Generates DEVMAP.md, offers to update AGENTS.md (never overwrites — asks before appending)

2. Analyze your project — devmap analyze [target]

The core command. Scans the project and builds .devmap/snapshot.json — detects framework, routes, API routes, entry points, critical files, dependencies, external services, and generates feature-level navigation.

devmap analyze
devmap analyze --fresh     # ignore cache, re-run from scratch
devmap analyze --json      # machine-readable output

Generates:

3. Using DevMap with AI agents

This is the core value prop: instead of an agent exploring the repo cold every session, it reads structured context DevMap already computed.

Recommended reading order for agents (also written into DEVMAP.md / AGENTS.md):

.devmap/index.json → feature map → relevant source files → snapshot.json (last resort)

Works with Claude Code, OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot, and any agent that can read files or consume --json output.

Use it as an MCP server

devmap mcp runs DevMap as a Model Context Protocol server over stdio. Instead of reading a context file at the start, the agent calls a tool and gets structured JSON for just the part it needs. Analyze once, then register the server:

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

Other clients launch the same command (npx -y @flaid/devmap mcp). For Cursor, Codex, opencode and any stdio client:

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

Most clients start the server in the folder you opened. If yours does not, add --root /absolute/path/to/project. The first npx download can exceed a client’s startup timeout, so after npm install -g @flaid/devmap use devmap as the command with mcp as the argument.

The server is read-only by default and runs static analysis only. Every answer includes snapshot: { generatedAt, stale } so the agent knows when to refresh. Full client setup and tool inputs: docs/mcp.md.

Why not just point my AI agent at the repo?

Fair question — most coding agents can already read your repo directly. A few reasons teams still run devmap analyze first:

• Reusable across sessions and tools. The snapshot is a file on disk. Every new agent session — or a teammate’s session, or a different agent entirely — starts from it instead of re-exploring the repo cold.
• Provider-agnostic. The snapshot isn’t tied to one vendor’s indexing. Switch agents or providers and the context comes with you.
• Deterministic. Static analysis produces the same structural map every time. An agent re-exploring a repo from scratch can come back with a slightly different picture session to session.
• Works without AI at all. devmap map and devmap analyze (no key configured) are pure static analysis — useful on their own, with or without an agent in the loop.
• Cheaper cold starts. An agent exploring a large repo blind burns tokens just finding its footing. DevMap computes that once; every session after reads the answer instead of re-deriving it.

None of this replaces your agent — DevMap hands it a map instead of a blank page.

4. Command reference

devmap onboarding (alias: devmap onboard)

Turns the snapshot into a “where do I start reading this project?” guide.

devmap onboarding
devmap onboarding --write                # writes ONBOARDING.md
devmap onboarding --write --language id  # en | id
devmap onboarding --json

devmap map [feature|file]

Dependency map — spatial view. No AI call, pure traversal of the already-computed snapshot graph.

devmap map                    # curated, feature-clustered project map
devmap map authentication     # one feature
devmap map src/lib/auth.ts    # one file — what it uses / what uses it
devmap map --all              # untruncated
devmap map --depth <n>        # override traversal depth

devmap flow [target]

Execution trace — temporal view, complements map.

devmap flow                   # curated top flows
devmap flow authentication
devmap flow --all             # include lower-confidence features + non-API routes

With a configured API key, each flow’s verified step list also gets a short AI-narrated paragraph.

devmap explain <file|feature|function>

Targeted, in-depth explanation of one thing — not a whole-codebase dump.

devmap explain src/lib/auth.ts
devmap explain "authentication feature"
devmap explain createWorkspace
devmap explain src/lib/auth.ts --write   # also saves to .devmap/explain/<slug>.md

Explains what the target does, what it imports, what imports it, and why it’s critical. Uses AI, but scoped to just that one target — so it stays fast and cheap even on large codebases. Without --write, the answer only prints to the terminal.

devmap doctor

Diagnostics for a broken setup. Checks DevMap version, Node version, provider/API key/model status, snapshot state, OS/platform. Always points to the next command to run.

devmap doctor

devmap mcp

Runs DevMap as an MCP server over stdio. Started by your agent’s client, not by hand. See Use it as an MCP server.

devmap mcp [--root <path>] [--auto-refresh] [--allow-ai]

stdout carries the JSON-RPC stream only. Logs go to stderr.

devmap config model <model-id|auto>

Override the model used for AI-powered commands, or restore automatic routing.

devmap config model llama-3.1-8b-instant
devmap config model auto
devmap config model llama-3.1-8b-instant --local

--local writes to .devmap/config.local.json in the current project instead of the global ~/.devmap/config.json. Only model can be set locally, provider and API key always stay global.

5. Generated files reference

6. Scripting & CI — --json

Every command supports --json: exactly one JSON document on stdout, no ANSI/decoration, no streaming. Runtime failures return { status, error, hint } instead of a thrown error — safe to parse in agents, scripts, or CI jobs.

7. Troubleshooting

Straight from devmap doctor’s real checks:

• API key invalid or missing → run devmap init again, or set GROQ_API_KEY / OPENROUTER_API_KEY
• Snapshot missing or corrupt → devmap analyze --fresh
• Model unavailable → devmap init or devmap config model <model-id>
• Node version unsupported → upgrade to Node.js 22.12+
• MCP client times out on start → install globally (npm install -g @flaid/devmap) and use devmap with the argument mcp instead of npx
• MCP answers say stale: true → ask the agent to call devmap_analyze, or start the server with --auto-refresh

See it in action

A small Next.js + Prisma app — a todos API route, a page, one component:

$ devmap analyze

DevMap Analyze
────────────────────────────────────────────────────────
◆ Scanning ~/sample-todo-app
Project              sample-todo-app
Framework            nextjs
Language             typescript
Files                9
Lines                117

Entry Points
────────────────────────────────────────────────────────
◆ app/api/todos/route.ts
◆ app/layout.tsx
◆ app/page.tsx
◆ app/todos/page.tsx

Routes
────────────────────────────────────────────────────────
◆ / -> app/page.tsx
◆ /api/todos -> app/api/todos/route.ts
◆ /todos -> app/todos/page.tsx

Database
────────────────────────────────────────────────────────
◆ Prisma

Features
────────────────────────────────────────────────────────
◆ Todo
◆ Todo Management

◆ Snapshot saved to .devmap/snapshot.json
◆ Agent navigation saved to .devmap/index.json and .devmap/features/
AI architecture interpretation is not configured. Run devmap init to enable it.

That produces a 15 KB snapshot.json. The routes and database sections are pulled straight from it:

{
  "framework": "nextjs",
  "routes": [
    { "path": "/", "file": "app/page.tsx", "kind": "page" },
    {
      "path": "/api/todos",
      "file": "app/api/todos/route.ts",
      "kind": "api",
      "methods": ["GET", "POST"]
    },
    { "path": "/todos", "file": "app/todos/page.tsx", "kind": "page" }
  ],
  "database": {
    "provider": "Prisma",
    "files": ["prisma/schema.prisma"]
  },
  "features": [
    {
      "name": "Todo Management",
      "purpose": "Handles create, read, update, and delete operations for Todo.",
      "files": ["app/api/todos/route.ts"],
      "confidence": "high"
    }
  ]
}

No API key was set for this run — everything above is pure static analysis. Browse the full snapshot and try it yourself.