Project Understanding Tool

Codebase Mapper

Generate dependency graphs, module maps, and architecture diagrams to understand how your codebase fits together.

Install

Get the CLI Tool

Run the codebase mapper locally as an MCP server, or try it online below.

npx @clinetools/codebase-mapper
Requires Node.js 18+
  • Mermaid, DOT, and JSON output formats
  • Circular dependency detection
  • Layer analysis (components, services, utils, models)
  • Multi-language support (JS/TS, Python)
  • Zero config — just run with npx
Tutorial

How to Use It

Three ways to map your codebase — pick the one that fits your workflow.

1

Try Online

Use the interactive demo below to paste files and generate a dependency map — no install needed.

↓ Jump to interactive demo
2

Use via CLI

Run as a local MCP server and connect any MCP-compatible client.

npx @clinetools/codebase-mapper
3

Add to Cline / Claude Code

Add the tool to your MCP settings for instant access from your AI assistant.

"codebase-mapper": { "command": "npx", "args": ["@clinetools/codebase-mapper"] }

MCP Client Configuration (Cline) 

{
  "mcpServers": {
    "codebase-mapper": {
      "command": "npx",
      "args": ["@clinetools/codebase-mapper"]
    }
  }
}

Claude Code Configuration 

# In your project's .mcp.json:
{
  "mcpServers": {
    "codebase-mapper": {
      "command": "npx",
      "args": ["@clinetools/codebase-mapper"]
    }
  }
}

Example Prompt: Map Architecture 

// Prompt to your AI agent:
"Map the architecture of this project"

// The agent calls:
map_codebase({
  path: "src/",
  format: "mermaid"
})

Example Prompt: Find Circular Dependencies 

// Prompt to your AI agent:
"Find all circular dependencies"

// The agent calls:
map_codebase({
  path: ".",
  detect_cycles: true
})
// Then reports the dependency cycles and suggests how to break them
Live Demo

Try It Online

Paste multi-file source code below and map its dependency graph instantly.

Paste Files to Map

Use // --- file: path --- markers to separate files

Try a demo:

Paste files and click Map to generate a dependency graph.

Mermaid Diagram


                        

                        

                        

                    

                

            

        

    


    

        

            

                Reference
                
Understanding Dependency Mapping

                
What each concept means and why it matters for architecture quality.

            

            

                

                    
                    
Dependency Graphs

                    
A directed graph where nodes are files or modules and edges represent import or require statements. Reveals the backbone of your architecture and shows which modules are most coupled.

                

                

                    
                    
Circular Dependencies

                    
When module A imports B, B imports C, and C imports A, you have a cycle. Circular dependencies cause bundler issues, make testing harder, and indicate tightly coupled design. Break them with dependency inversion.

                

                

                    
                    
Layer Architecture

                    
Organizing code into layers — controllers, services, utils, models — enforces dependency direction. Upper layers depend on lower layers, never the reverse. Violations signal architecture drift.

                

                

                    
                    
Orphan Files

                    
Files that are never imported by any other file. They might be entry points, dead code, or forgotten utilities. Identifying orphans helps you clean up unused code and reduce bundle size.

                

            

        

    


    

        

            
Need Automated Architecture Checks?

            
Our Pro plan includes CI/CD dependency checks that block merges when circular dependencies are introduced.

            View Plans