DevMap

The first command you run after git clone.

Analyze once. Reuse context everywhere. Structured project intelligence for developers and AI agents.

Built by Muhammad Fadil (@itsflaid) · www.flaid.my.id

---

The Problem

Before doing real work, developers and AI agents need context.

They open files, trace dependencies, follow feature flows, and rebuild understanding of the project.

The process repeats every time you:

• start a new session
• switch AI tools
• bring in a new agent
• revisit a project weeks later

The code stays the same.

The context gets rebuilt again and again.

---

The Solution

DevMap turns project knowledge into reusable context.

It analyzes your codebase and generates structured project intelligence that can be reused across developers, sessions, and AI agents.

Instead of rediscovering the codebase every time, agents and developers start with:

• Project overview
• Entry points
• Feature maps
• Critical files
• Architecture summaries
• Navigation paths
• Onboarding guidance

Analyze once.

Reuse everywhere.

Without DevMap:

Repository
   ↓
Claude explores files
   ↓
Context rebuilt

Repository
   ↓
Codex explores files
   ↓
Context rebuilt

Repository
   ↓
New session
   ↓
Context rebuilt

With DevMap:

Repository
   ↓
devmap analyze
   ↓
Shared Project Context
   ├─ Claude Code
   ├─ OpenAI Codex
   ├─ Gemini CLI
   ├─ Cursor
   ├─ Windsurf
   └─ Future Agents

---

How It Works

devmap init
  → configures provider
  → generates DEVMAP.md
  → prepares project

devmap analyze
  → runs static analysis
  → builds project intelligence
  → generates navigation files
  → generates reusable context

Generated Context
  → reusable across sessions
  → reusable across agents
  → reusable across developers

---

Generated Files

File	Role
DEVMAP.md	DevMap project documentation
AGENTS.md	Agent instructions
.devmap/index.json	Agent entry point
.devmap/features/*.json	Feature-level navigation
.devmap/snapshot.json	Complete project intelligence

Recommended navigation order for agents:

index.json
   ↓
feature map
   ↓
relevant source files
   ↓
snapshot.json (last resort)

The snapshot remains the complete project context and can also be copied into web-based AI tools when needed.

---

For AI Agents

DevMap provides reusable project context that works across tools.

Instead of exploring a repository from scratch, agents start with generated project intelligence.

Supported workflows include:

• Claude Code
• OpenAI Codex
• Gemini CLI
• Cursor
• GitHub Copilot
• etc.

Without DevMap:

Agent
   ↓
Explore repository
   ↓
Trace dependencies
   ↓
Guess architecture
   ↓
Start task

With DevMap:

Agent
   ↓
index.json
   ↓
feature map
   ↓
relevant files
   ↓
Start task

One analysis.

Reusable across sessions, tools, and agents.

---

Vision

DevMap is not an AI coding assistant.

AI coding assistants help write code.

DevMap helps developers and AI agents understand how codebases are organized, how features connect, and where work should begin.

Use DevMap to understand the project.

Use your preferred AI tool to change it.

DevMap is a shared project context layer for developers and AI agents.

---

Supported Stacks

Full support — framework detection + route mapping

• Next.js (App Router and Pages Router)
• Astro
• Nuxt
• SvelteKit
• Express
• Fastify
• NestJS

SPA client-side routing — routes read from the client router

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

Databases

• Prisma — full field + relation extraction
• Raw SQL (pg, mysql2, better-sqlite3) — table names only
• Drizzle, Mongoose, Supabase, TypeORM — detected as dependency only

Planned

• PHP (Laravel)
• Python, Go, Java, Rust, Dart, C# — see docs/roadmap.md Phase 6

---

AI Provider Setup

DevMap is free and open source.

AI features require a provider API key. DevMap uses Groq by default — analysis runs on free-tier infrastructure.

Provider	Status
Groq	MVP
OpenRouter	MVP
Custom (any OpenAI-compatible)	MVP
OpenAI (official, hosted)	Planned
Gemini	Planned

devmap init lets you choose Groq, OpenRouter, or a custom OpenAI-compatible endpoint with the arrow keys. Groq shows the available model list and stores the selected model. For OpenRouter, pressing Enter at OpenRouter model [openrouter/free]: keeps the free router; typing another model ID uses that free or paid model instead. Change it later with devmap config model <model-id>.

API keys are stored locally:

~/.devmap/config.json

DevMap does not require a backend server.

Requests go directly from your machine to the selected provider.

---

Installation

# npm
npm install -g @flaid/devmap

# pnpm
pnpm add -g @flaid/devmap

# run without installing
npx @flaid/devmap analyze

Requirements:

Node.js 22.12+

---

Roadmap

Shipped

• devmap init
• devmap analyze
• devmap doctor
• devmap onboarding
• devmap map
• devmap explain
• devmap flow
• Custom OpenAI-compatible provider

Next (Phase 3)

• Frontend SPA store extraction (Zustand, Redux Toolkit, Pinia)
• Better SPA feature/entry-point detection

Later

• OpenAI provider
• Gemini provider
• Local/Ollama AI mode

See docs/roadmap.md for details.

---

Documentation

• docs/commands.md
• docs/architecture.md
• docs/generated-files.md
• docs/design.md
• docs/benchmarking.md
• docs/roadmap.md
• docs/releasing.md
• CHANGELOG.md
• CONTRIBUTING.md

---

Contributing

DevMap is open source and welcomes contributions.

git clone https://github.com/itsflaid/devmap
cd devmap

pnpm install
pnpm link --global

devmap analyze

Before contributing:

1. Read docs/architecture.md
2. Read CONTRIBUTING.md

---

License

MIT License — use it, fork it, improve it, build on top of it.