A lightweight TypeScript/JavaScript code indexer that generates comprehensive project maps for LLMs
npm install codebase-mapA lightweight TypeScript/JavaScript code indexer that generates comprehensive project maps optimized for LLMs like Claude.
- AST-based analysis - Accurate extraction of functions, classes, and constants
- Dependency resolution - Tracks imports/exports and builds a complete dependency graph
- Multiple output formats - Optimized for different project sizes and use cases
- LLM-optimized - Formats designed to minimize token usage while preserving structure
- Fast incremental updates - Update individual files without full re-scan
- Works from any directory - Automatically finds project root
- Flexible file filtering - Include/exclude patterns using glob syntax for precise control
- Performance optimized - Built-in pattern caching and analysis tools
``bash`
npm install -g codebase-map
Or add to your project:
`bash`
npm install --save-dev codebase-map
`bashGenerate index for your project
codebase-map scan
Commands
$3
Analyzes your codebase and generates a .codebasemap file.`bash
codebase-map scan [options]Options:
-r, --root Root directory to scan (default: auto-detect)
-o, --output Output file path (default: .codebasemap)
-v, --verbose Show detailed progress
--include Include file patterns (glob syntax)
--exclude Exclude file patterns (glob syntax)
`$3
Formats the index for LLM consumption (outputs to stdout).`bash
codebase-map format [options]Options:
-f, --format Output format: auto|json|dsl|graph|markdown|tree
-s, --stats Show statistics to stderr
--include Include file patterns (glob syntax)
--exclude Exclude file patterns (glob syntax)
`$3
Updates the index for a specific file.`bash
codebase-map update [options]Options:
-r, --root Root directory
`$3
Lists files in the index with various filters.`bash
codebase-map list [options]Options:
-d, --deps Show files with most dependencies
-e, --entries Show entry point files
-l, --leaves Show leaf files (no dependencies)
`Pattern Support
Control which files are analyzed using powerful glob patterns:
$3
`bash
Include only specific directories
codebase-map scan --include "src/" --include "lib/"Exclude test files and documentation
codebase-map scan --exclude "/.test.ts" --exclude "/.spec.ts" --exclude "docs/**"Combine include and exclude patterns
codebase-map scan --include "src/" --exclude "/*.test.ts"
`$3
`bash
Focus on specific packages in a monorepo
codebase-map scan --include "packages//src/" --exclude "/.test.ts"Analyze only TypeScript files, exclude build outputs
codebase-map scan --include "/.ts" --include "/.tsx" --exclude "dist/" --exclude "build/"Complex filtering with multiple criteria
codebase-map scan \
--include "src/**" \
--include "lib/**" \
--exclude "*/.test.ts" \
--exclude "*/.spec.ts" \
--exclude "/fixtures/" \
--exclude "/mocks/"
`$3
| Pattern | Description | Example |
|---------|-------------|---------|
|
| Match any number of directories | src/ matches all files in src and subdirectories |
| | Match any characters except / | .ts matches all TypeScript files |
| ? | Match single character | test?.ts matches test1.ts, testa.ts |
| [abc] | Match any character in brackets | test[123].ts matches test1.ts, test2.ts, test3.ts |
| {a,b} | Match any of the alternatives | */.{ts,js} matches all TypeScript and JavaScript files |$3
#### Monorepo Analysis
`bash
Analyze specific packages
codebase-map scan --include "packages/core/" --include "packages/utils/"Exclude all test files across packages
codebase-map scan --include "packages//src/" --exclude "/.{test,spec}.{ts,js}"
`#### Test File Filtering
`bash
Exclude all test-related files
codebase-map scan --exclude "/.{test,spec}.{ts,tsx,js,jsx}" --exclude "/tests/" --exclude "/__tests__/*"Include only test files for test coverage analysis
codebase-map scan --include "*/.{test,spec}.{ts,tsx,js,jsx}"
`#### Library Development
`bash
Focus on source code, exclude examples and documentation
codebase-map scan --include "src/" --exclude "examples/" --exclude "docs/**"Include only public API files
codebase-map scan --include "src/public/**" --include "src/index.ts"
`$3
- Use specific patterns:
src//.ts is faster than /.ts for large codebases
- Order matters: Place more restrictive include patterns first
- Avoid overly broad excludes: Specific exclusions perform better than */
- Cache benefits: Repeated pattern usage is automatically optimized$3
Use
--verbose mode to see pattern effectiveness:`bash
codebase-map scan --include "src/" --exclude "/*.test.ts" --verbose
`Output includes:
- Pattern match statistics
- Performance metrics
- Warnings for ineffective patterns
- Suggestions for optimization
Output Formats
The tool automatically selects the best format based on project size, or you can specify one:
| Format | Description | Best For | Token Reduction |
|--------|-------------|----------|-----------------|
|
tree | ASCII art directory structure | Structure visualization (any size) | ~97% |
| dsl | Domain-specific language | Most projects (≤5000 files) | ~90% |
| graph | Dependency graph with signatures | Very large projects (>5000 files) | ~92% |
| markdown | Human-readable markdown | Documentation | ~93% |
| json | Compact JSON | Baseline | 0% |$3
Choose the right format for your use case:
#### Tree Format (
tree)
Best for: Visualizing project structure, understanding file organization
- Token reduction: 97% (most efficient for structure)
- Readability: Excellent visual hierarchy
- Use cases: Understanding project layout, presenting structure to stakeholders, exploring unfamiliar codebases
- Selection: Manual only - complements other formats by showing structure rather than code content`bash
Ideal for understanding project structure, exploring new codebases
codebase-map format --format tree
`#### DSL Format (
dsl)
Best for: Most development workflows, AI context
- Token reduction: 90% (excellent balance)
- Readability: High - shows functions, classes, dependencies clearly
- Use cases: Code analysis, AI assistance, dependency tracking
- Automatic selection: Projects with ≤5000 files (default choice)`bash
Perfect for typical applications and libraries
codebase-map format --format dsl
`#### Graph Format (
graph)
Best for: Large codebases, dependency analysis
- Token reduction: 92% (maximum compression for content)
- Readability: Good - focuses on relationships
- Use cases: Large projects, dependency debugging, architecture analysis
- Automatic selection: Projects with >5000 files`bash
Essential for large monorepos and enterprise applications
codebase-map format --format graph
`#### Markdown Format (
markdown)
Best for: Documentation, reports, human reading
- Token reduction: 93% (great for docs)
- Readability: Excellent - formatted for humans
- Use cases: Project documentation, README generation, reports
- Manual selection only`bash
Great for generating project documentation
codebase-map format --format markdown > PROJECT_STRUCTURE.md
`$3
`bash
Understanding any project's structure
codebase-map format --format tree
└── Shows clear visual hierarchy
Typical web application (100-500 files)
codebase-map format --format dsl
└── Shows functions, dependencies, classes compactly
Large enterprise application (1000-5000 files)
codebase-map format --format dsl --stats
└── Monitor token usage with --stats
Massive monorepo (>5000 files)
codebase-map format --format graph
└── Maximum compression for context limits
`$3
Recommended token allocations for AI context:
- Small projects (<100 files): DSL format, ~2,100 tokens
- Medium projects (100-1000 files): DSL format, ~2,100-21,000 tokens
- Large projects (1000-2000 files): DSL format, ~21,000-42,000 tokens ⚠️
- Very large projects (2000-5000 files): DSL format, approaching context limits
- Enterprise projects (>5000 files): Graph format, auto-switches for maximum efficiency
- Structure visualization (any size): Tree format, manual choice for exploring layout
Context window usage guidelines:
- Keep project structure under 25% of available context
- Use
--stats flag to monitor token usage
- Consider using pattern filtering for large projectsFiltering on Format
The
format command supports filtering the already-generated index without needing to re-scan. This enables powerful workflows:$3
`bash
Generate index once
codebase-map scanFormat different views without re-scanning
codebase-map format --include "src/" --exclude "/*.test.ts"
codebase-map format --include "docs/**" --format markdown
codebase-map format --include "packages/core/**" --format dsl
`$3
Scan once, format many times:
- Generate comprehensive index:
codebase-map scan
- Create focused views: codebase-map format --include "src/components/**"
- Exclude test files: codebase-map format --exclude "*/.{test,spec}.ts"
- Focus on specific packages: codebase-map format --include "packages/utils/**"Performance advantages:
- No file system scanning on format (instant filtering)
- Apply different filters to same index data
- Combine with any output format (
--format dsl, --format tree, etc.)$3
#### Focus on Source Code
`bash
Show only source files, exclude tests and build outputs
codebase-map format --include "src/" --exclude "/.test.ts" --exclude "dist/*"
`#### Monorepo Package Analysis
`bash
Focus on specific packages
codebase-map format --include "packages/core/" --include "packages/utils/"Analyze one package in detail
codebase-map format --include "packages/ui/src/**" --format dsl
`#### Documentation Focus
`bash
Extract documentation structure
codebase-map format --include "docs/*" --include ".md" --format treeGet markdown files in readable format
codebase-map format --include "*/.md" --format markdown
`#### Component Analysis
`bash
Focus on React components
codebase-map format --include "/.{tsx,jsx}" --exclude "/.test.*"Analyze utility functions
codebase-map format --include "/utils/" --include "/helpers/"
`$3
The format command shows filtering impact to stderr (doesn't affect stdout):
`bash
codebase-map format --include "src/" --exclude "/*.test.ts" --statsOutput to stderr:
--- Filtering Applied ---
Files: 456 of 1,234
Dependencies: 980 of 2,100
Include patterns: src/**
Exclude patterns: */.test.ts
#
--- Statistics (dsl format) ---
Size: 45.2 KB (89% reduction)
Tokens: ~12,450 (27 per file)
Files: 456
`$3
`bash
Complex monorepo filtering
codebase-map format \
--include "packages//src/*" \
--include "shared/**" \
--exclude "*/.{test,spec,mock}.{ts,tsx,js,jsx}" \
--exclude "/fixtures/" \
--exclude "/__tests__/"TypeScript-only analysis
codebase-map format \
--include "*/.{ts,tsx}" \
--exclude "*/.d.ts" \
--exclude "node_modules/**"API-focused view
codebase-map format \
--include "src/api/**" \
--include "src/routes/**" \
--include "src/middleware/**" \
--format graph
`Integration with Claude
$3
Configure hooks in
.claude/settings.json to automatically include project structure when starting a session:`json
{
"hooks": {
"SessionStart": [
{
"hooks": [
{"type": "command", "command": "codebase-map format"}
]
}
]
}
}
`$3
`bash
Generate and copy structure to clipboard
codebase-map format | pbcopy
Then paste into Claude conversation
`Example Output
$3
`
project/
├── src/
│ ├── components/
│ │ ├── Button.tsx
│ │ └── Input.tsx
│ ├── utils/
│ │ └── helpers.ts
│ ├── index.ts
│ └── types.ts
├── tests/
│ └── setup.ts
└── package.json
`$3
`
src/core/dependency-resolver.ts > types/index.ts
cl DependencyResolver(9m,2p)
src/core/index-formatter.ts > types/index.ts
fn toMinifiedJSON(index:ProjectIndex):string
fn toDSL(index:ProjectIndex):string
fn toGraph(index:ProjectIndex):string
fn formatAuto(index:ProjectIndex):{ format: FormatType; content: string }
src/utils/find-project-root.ts >
fn findProjectRoot(startDir:string):string | null
fn findIndexFile(startDir:string):string | null
``- Processes ~400 files/second
- Generates ~3 tokens/file in tree format (97% reduction)
- Generates ~29 tokens/file in DSL format (90% reduction)
- Generates ~24 tokens/file in graph format (92% reduction)
- Generates ~23 tokens/file in markdown format (93% reduction)
- 90-97% token reduction vs compact JSON
- Node.js ≥ 18.0.0
- TypeScript/JavaScript project
MIT
Contributions are welcome! Please feel free to submit a Pull Request.