codemap

Codemap

Generate a compact, annotated directory tree that helps any agent quickly understand what a codebase contains and where key things live. One well-crafted codemap can replace dozens of exploratory globs and reads across a session.

When to use me

• First time entering a new repository or unfamiliar subdirectory
• The user asks "what's in this project?" or "show me the project structure"
• You need to understand the lay of the land before deciding where to search
• An agent keeps globbing the same directories — a codemap saves those tokens

How to generate

Step 1: Build the raw tree

Use the appropriate file listing for the platform:

# Windows (PowerShell)
Get-ChildItem -Recurse -Depth 3 -Name | Where-Object { $_ -notmatch 'node_modules|\.git|dist|build|\.next|coverage|__pycache__|\.venv' }

# Unix
find . -maxdepth 3 -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' | sort

Adjust the depth and exclusions based on repo size. For very large repos, start at depth 2 and expand specific directories on demand.

Step 2: Annotate the tree

After generating the raw tree, annotate key directories with one-line purpose descriptions. Only annotate directories whose purpose isn't obvious from the name.

project-root/
├── src/                       # main source
│   ├── app/                   # Next.js App Router pages + layouts
│   ├── components/            # shared React components
│   ├── lib/                   # utilities, API clients, shared logic
│   └── server/                # server-only code (DB, auth)
├── prisma/
│   └── schema.prisma          # database schema
├── public/                    # static assets
├── tests/                     # integration + e2e tests
├── package.json               # Node dependencies + scripts
└── tsconfig.json              # TypeScript config

Step 3: Add quick-reference metadata

At the bottom, add a few lines that capture the project's essence: