Devmap

io.github.itsflaidPublished by GitHub account itsflaidv0.9.0Updated Nov 7, 2026

Query a codebase map (routes, features, flows, impact) built by static analysis.

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

DevMap serves a precomputed static-analysis map of a codebase, letting an assistant query features, routes, flows, dependencies and change impact.

What you can do
  • Get a project overview: framework, stats, entry points, critical files, features and route counts
  • Map dependencies for the whole project, one feature or one file, and find code by keyword
  • Trace how a feature or API request works end to end, and list page and API routes with handlers and methods
  • Assess impact of changing a file, including direct and transitive dependents and affected features
  • Re-analyze the project to refresh the snapshot, writing only inside the .devmap directory
When to use it
Useful when an assistant works on an existing codebase and should orient itself before reading many files, or check what a shared file change affects before editing. It suits projects on the supported frontend and backend stacks, with deepest analysis for Next.js and Express.
Requirements
Runs locally over stdio via npx from the npm package @flaid/devmap, so Node.js 22.12 or newer is needed. A snapshot must be built first (for example with devmap analyze). No API key is required for the MCP server unless AI interpretation is enabled.
Before you install
The server is read-only and static by default, but devmap_analyze writes inside .devmap/ and can be triggered by the assistant; starting with --auto-refresh or --allow-ai changes that behavior. Results can be stale when the snapshot is outdated. The CLI's optional AI setup stores a provider API key locally in the user's config file and sends requests to that provider, though full repository source is not sent.

Installation

In SourceWeft

  1. Open Devmap in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

DevMap

[npm version] [license] [node]

Analyze once. Reuse context everywhere. A CLI that maps your codebase for developers and AI agents: entry points, critical files, features and routes.

Documentation · Website · GitHub

Every new AI chat about your code starts from zero — you re-explain the same codebase every time. DevMap fixes that.

It's a CLI that combines static analysis with optional AI interpretation to build a structured, reusable understanding layer of your project — once. That layer (.devmap/index.json, feature maps, DEVMAP.md) is what you and any AI agent read afterward, instead of re-scanning or re-pasting the whole repo. Full repo source stays local — nothing gets sent wholesale to the AI model.

Install

bash
npm install --global @flaid/devmap

Or run without a global install:

bash
npx @flaid/devmap --help

Requirements

  • Node.js 22.12 or newer
  • An API key for an AI provider: Groq, OpenRouter, or any custom OpenAI-compatible endpoint

Static analysis still works when AI is not configured.

Quick Start

Run these commands from the root of the project you want to understand:

bash
devmap initdevmap analyzedevmap onboardingdevmap doctor

devmap init selects a provider, validates its key, stores configuration locally, prepares .devmap/, generates DEVMAP.md, and integrates with AGENTS.md safely.

AI Provider Setup

Choose Groq, OpenRouter, or a custom OpenAI-compatible endpoint with the arrow keys during:

bash
devmap init

Groq keys are available at https://console.groq.com/keys. OpenRouter keys are available at https://openrouter.ai/keys.

For custom endpoints, DevMap asks for the base URL (prefilled with http://localhost:20128/v1) and lists the models your server exposes, so any OpenAI-compatible self-hosted gateway works out of the box.

For OpenRouter, DevMap prompts:

txt
OpenRouter model [openrouter/free]:

Press Enter to use the free router, or type any free or paid OpenRouter model ID. The selected model is saved and used as the primary choice.

For non-interactive Groq setup:

bash
GROQ_API_KEY="your-key" devmap init

On PowerShell:

powershell
$env:GROQ_API_KEY="your-key"devmap initRemove-Item Env:GROQ_API_KEY

For non-interactive OpenRouter setup:

bash
OPENROUTER_API_KEY="your-key" devmap init

The key is stored locally in ~/.devmap/config.json. Requests go directly from your machine to the selected provider. DevMap does not send the key to a DevMap-owned server.

Commands

bash
devmap initdevmap analyzedevmap analyze --freshdevmap map                    # full project mapdevmap map <feature-or-file>  # scoped to one feature or filedevmap flow                   # curated top flowsdevmap flow <feature-or-route>devmap explain <target>       # file, feature, or functiondevmap onboarding --writedevmap onboarding --write --language iddevmap doctordevmap config model autodevmap mcp                    # run as an MCP server

Groq and OpenRouter use the model selected during init. Change either provider's model with:

bash
devmap config model <model-id>devmap config model auto

MCP Server

devmap mcp runs DevMap as a Model Context Protocol server over stdio. An AI agent asks the project map questions with tool calls and gets structured JSON back, instead of reading a whole context file up front.

bash
devmap analyzeclaude mcp add devmap -- npx -y @flaid/devmap mcp

Other clients launch the same command (npx -y @flaid/devmap mcp) as a stdio server:

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

Tools: devmap_overview, devmap_map, devmap_flow, devmap_routes, devmap_impact, devmap_find, devmap_analyze and, only with --allow-ai, devmap_explain.

The server is read-only and static by default: no AI provider is contacted unless you start it with --allow-ai, and it only writes inside .devmap/ when the agent calls devmap_analyze or you start it with --auto-refresh. Every answer reports whether the snapshot is stale. See the MCP guide for client setup and tool inputs.

Generated Context

DevMap generates:

  • .devmap/index.json for lightweight AI-agent navigation
  • .devmap/features/*.json for focused feature maps and source priority
  • .devmap/snapshot.json for the full structured project analysis archive
  • DEVMAP.md for human and AI-agent usage guidance
  • a small DevMap block in AGENTS.md only after confirmation when the file already exists

Existing AGENTS.md and DEVMAP.md files are never overwritten.

For AI Agents

Read .devmap/index.json first, open the relevant feature map, and inspect its sourcePriority files. Use .devmap/snapshot.json only when the lightweight navigation layer is insufficient.

Use --json for scripts, editors, CI, or AI agents:

bash
devmap analyze --jsondevmap onboarding --jsondevmap doctor --json

JSON mode writes one parseable JSON document to stdout without ANSI colors, terminal decoration, or streamed partial output.

Supported Stacks

  • Frontend: Next.js, Astro, SvelteKit, Nuxt, Remix, React Router v7, TanStack Router/Start, Expo Router, SolidStart, Qwik City, Angular, React, Vue, Svelte
  • Backend: Express, NestJS, Fastify, Hono, Elysia, Koa, AdonisJS

Detection covers the full list above; Next.js and Express receive the deepest analysis. Multi-package workspaces are classified per project type, so a monorepo containing a CLI and a web app is reported as both.

Privacy

  • Project analysis runs locally before AI interpretation.
  • Full repository source is not sent to the selected provider.
  • .env files and common generated directories are ignored.
  • API keys are stored locally and should never be committed.

Links

License

MIT

Source: packages/cli/README.md at commit 2c9a5e8

Tools

7

devmap_overview

Project overview

Entry point for understanding the project: framework, stats, entry points, most critical files, detected features, flows and route counts. Call this first.

Takes no parameters.

devmap_map

Dependency map

Dependency map for the whole project (omit target), one feature (feature name) or one file (project-relative path): what it imports, what imports it, and related files. Use it to find where to look before reading code.

ParametersdepthtargetincludeMermaid

devmap_flow

Trace a flow

Trace how a feature or API request works end to end (ordered steps with file paths). Omit target to list the curated top flows. Static analysis only, no AI.

Parametersalltarget

devmap_routes

List routes

List detected page and API routes with their handler file and HTTP methods. Filter by kind, path prefix or method.

Parameterskindlimitmethodprefix

devmap_impact

Change impact

What is affected if a file changes: direct and transitive dependents (follow imports up to `depth` hops), affected features, critical dependents, areas likely impacted, and what it imports. Call this before editing a shared file.

Parametersfilerequireddepthlimit

devmap_find

Find code

Locate features, files and routes by keyword using DevMap's index (paths, exported symbols, function names, search terms, purposes). Faster and more precise than grepping the whole repo for a concept.

Parameterslimitqueryrequired

devmap_analyze

Refresh the project map

Re-analyze the project and refresh the DevMap snapshot (writes only inside .devmap/). Call it when a result reports snapshot.stale = true, or when no snapshot exists. Returns status "unchanged" without re-analyzing if no file changed (pass fresh: true to force a full rebuild). Static analysis only: no AI is used, so AI-derived data (domain, architecture) is not regenerated and aiDataDropped is reported when it is lost. If it takes longer than timeoutSeconds it keeps running in the background and status is "running"; call again to wait for it.

ParametersfreshtimeoutSeconds

Version history

1
  1. v0.9.0LatestOct 31, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts