CodeMapper (cm) uses tree-sitter AST parsing to provide instant code analysis without databases. Get project structure, find symbols, trace call graphs, and analyze dependencies in milliseconds.

Supported Languages: Python, JavaScript, TypeScript, Rust, Java, Go, C, Markdown

When to Use

Use CodeMapper when you need to:

✅ Explore unfamiliar codebases (get overview, find structure)
✅ Find symbol definitions and usages (functions, classes, methods)
✅ Understand call graphs (who calls what, call paths)
✅ Check test coverage (find untested code)
✅ Analyze git changes at symbol level (breaking changes)
✅ Pre-refactoring impact analysis (understand dependencies)

Don't use for:

❌ Full-text search (use ripgrep/grep instead)
❌ Runtime analysis (use profilers)
❌ Code execution (use interpreters/compilers)

Quick Start

# Step 1: Get overview
cm stats .

# Step 2: See file structure (ALWAYS use --format ai for LLMs)
cm map . --level 2 --format ai

# Step 3: Find specific code
cm query <symbol> --format ai

# Step 4: Deep dive into a file
cm inspect ./path/to/file --format ai

🔥 CRITICAL: Always use --format ai when analyzing code for LLM context. This is the most token-efficient format (60-80% reduction).

Essential Commands

| Project overview | cm stats .

| File structure | cm map . --level 2 --format ai

| Find symbol | cm query <name> --format ai

| Show implementation | cm query <name> --show-body --format ai

| Who calls it? | cm callers <symbol> --format ai

| What does it call? | cm callees <symbol> --format ai

| Call path A→B | cm trace <from> <to> --format ai

| Find tests | cm tests <symbol> --format ai

| Untested code | cm untested . --format ai

| Breaking changes | cm since <commit> --breaking --format ai

For complete command reference: Read references/command-reference.md

Key Workflows

Exploring Unknown Code

cm stats .
cm map . --level 2 --format ai
cm query <symbol> --format ai

Before Refactoring

cm callers <function> --format ai      # Who depends on this?
cm tests <function> --format ai        # Is it tested?
cm callees <function> --format ai      # What does it depend on?

Code Health Check

cm untested . --format ai                       # What's not tested?
cm since <last_release> --breaking --format ai  # Breaking changes?

For detailed workflows: Read references/workflows.md

Common Mistakes

❌ Forgetting `--format ai`

# Bad (verbose, token-heavy)
cm map . --level 2

# Good (compact, LLM-optimized)
cm map . --level 2 --format ai

❌ Using grep for call graphs

# Bad (misses indirect calls, false positives)
grep -r "process_payment"

# Good (accurate AST-based call graph)
cm callers process_payment --format ai

❌ Skipping stats/map

# Bad (jumping to query without context)
cm query something --format ai

# Good (understand structure first)
cm stats .
cm map . --level 2 --format ai
cm query something --format ai

For more examples: Read references/common-mistakes.md

Best Practices

Always start with overview: cm stats . then cm map . --level 2 --format ai
Always use --format ai for LLMs: Token efficiency matters
Fuzzy search first: Default fuzzy matching is more forgiving
Check before refactoring: Run cm callers and cm tests before changes
Use correct tool: CodeMapper for structure/calls, ripgrep for text search

Troubleshooting

No Symbols Found?

Check file extensions: cm stats . shows what's indexed
Try fuzzy search (default) vs --exact

Slow Queries?

First run builds cache (~10s)
Subsequent runs use cache (~0.5s)

Git Commands Fail?

Must be in a git repository for: diff, since, blame, history

For detailed troubleshooting: Read references/troubleshooting.md

Reference Documentation

references/command-reference.md - Complete command and flag reference
references/workflows.md - Detailed workflow patterns for common tasks
references/common-mistakes.md - Extended examples of what to avoid
references/troubleshooting.md - Comprehensive troubleshooting guide
references/integration-examples.md - CI/CD, documentation, code review patterns

Performance

Small repos (< 100 files): < 20ms instant
Medium repos (100-1000): ~0.5s with cache
Large repos (1000+): Fast mode auto-enabled

Cache location: .codemapper/ in project root (auto-managed)

安装