CodeGraph CLI

Code graph visualization and analysis CLI - index codebases, query dependencies, trace data flow

What is CodeGraph?

CodeGraph analyzes your TypeScript/JavaScript codebase and builds a queryable graph of:

• Import relationships - What imports what
• Function calls - Who calls whom
• Class hierarchies - Inheritance and implementations
• Data flow - How data moves through your code
• Control flow - Program execution paths

Designed for AI coding agents - fast indexing, structured JSON output, and deterministic exit codes for automation.

Installation

Prerequisites

• Bun 1.0+ - Install Bun

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1 | iex"

Install via npm/bun

bun install -g codegraph-cli

Verify Installation

codemap --version

Quick Start

1. Index your codebase

cd your-project
codemap index .

This creates a .codegraph/ directory with the code index (SQLite database).

2. Query the graph

# Show index statistics
codemap status .

# List imports for a file
codemap query src/index.ts --imports .

# Find who imports a file
codemap query src/utils.ts --importers .

# List symbols in a file
codemap query src/api.ts --symbols .

3. Trace dependencies

# Trace what a file depends on (outgoing)
codemap trace src/main.ts --direction=out .

# Trace what depends on a file (incoming)
codemap trace src/utils.ts --direction=in .

Agent Integration

CodeGraph is optimized for AI agent workflows:

Structured JSON Output

All commands support --json for machine-readable output:

codemap query src/index.ts --imports --json . | jq '.result.imports'

Deterministic Exit Codes

| Code | Name | Meaning | |------|------|---------| | 0 | SUCCESS | Command completed successfully | | 1 | GENERAL_ERROR | Unexpected error | | 2 | INVALID_ARGUMENTS | Invalid flags/arguments | | 3 | FILE_NOT_FOUND | Requested file or symbol not found | | 4 | INDEX_NOT_FOUND | Missing index (run codemap index first) | | 5 | PARSE_ERROR | Failed to parse inputs | | 6 | INDEX_ERROR | Index completed with errors |

Schema Discovery

# Get full JSON schema for automation
codemap schema --json

Commands

Core Commands

| Command | Description | |---------|-------------| | codemap index <path> | Build or update the code index | | codemap status <path> | Show index status and statistics | | codemap query <file> <path> | Query imports, symbols, and relationships | | codemap trace <file> <path> | Trace dependency chains |

Analysis Commands

| Command | Description | |---------|-------------| | codemap analyze <path> | Run codebase analysis (fan-in/out, layers, hot files) | | codemap coupling <path> | Analyze file coupling and co-change patterns | | codemap git <path> | Analyze git history for code insights |

Advanced Commands

| Command | Description | |---------|-------------| | codemap cfg <file> | Generate control flow graph for a function | | codemap dfg <file> <path> | Generate data flow graph for a function | | codemap pdg <file> <path> | Generate program dependence graph | | codemap slice <file> <path> | Perform program slicing | | codemap export <path> | Export graph data (JSON/DOT) | | codemap schema | Show output schema for automation |

Utility Commands

| Command | Description | |--------|-------------| | codemap version | Show version | | codemap version --check | Check for updates |

Global Options

All commands support these options:

| Option | Description | |--------|-------------| | --json | Output as JSON (for automation) | | -q, --quiet | Suppress non-essential output | | -v, --verbose | Show detailed progress | | --no-color | Disable colored output |

Examples

Find all callers of a function

codemap query src/auth.ts --callers=validateToken .

Analyze what a function calls

codemap query src/api.ts --callees=handleRequest .

Get inheritance hierarchy

codemap query src/models/User.ts --heritage=UserModel .

Trace imports up to 3 levels deep

codemap trace src/index.ts --direction=out --depth=3 .

Analyze codebase architecture

codemap analyze . --all

Export dependency graph as DOT (for Graphviz)

codemap export . --format=dot > deps.dot
dot -Tpng deps.dot -o deps.png

Keeping Up to Date

Check for updates

codemap version --check

Update to latest version

bun update -g codegraph-cli

How It Works

1. Indexing: Parses your code with tree-sitter and extracts symbols, imports, and relationships
2. Storage: Stores the graph in a local SQLite database (.codegraph/codegraph.db)
3. Querying: Traverses the graph to answer questions about your code

The index is project-local, so each project has its own graph. Re-run codemap index after making changes to update the graph.

Configuration

Environment Variables

| Variable | Description | |----------|-------------| | CODEMAP_INDEX_DIR | Override index directory (default: .codegraph) |

Ignored Paths

By default, these directories are ignored during indexing:

• node_modules
• dist
• .git
• coverage
• .codegraph

Performance

CodeGraph uses Bun for optimal performance:

• Fast startup - Bun's cold start is ~4x faster than Node.js
• Native SQLite - bun:sqlite is significantly faster than better-sqlite3
• Efficient bundling - Single-file distribution with minimal overhead

Typical indexing times:

• Small project (100 files): < 1 second
• Medium project (1000 files): 2-5 seconds
• Large project (10000 files): 15-30 seconds

Troubleshooting

"Index not found" error

Run codemap index . first to create the index.

Slow indexing

Large codebases take longer on first index. Subsequent runs use caching for faster updates.

Parse errors

Some files may fail to parse (e.g., non-standard syntax). These are logged but don't stop indexing.

Uninstall

bun remove -g codegraph-cli

To remove project indexes, delete the .codegraph directory in each project.

Development

For contributors:

# Clone the repository
git clone https://github.com/your-org/codegraph-cli
cd codegraph-cli

# Install dependencies
bun install

# Build
bun run build

# Run locally
bun dist/cli/index.js index .

# Run tests
bun test

# Type check
bun run typecheck

# Lint
bun run lint

License

MIT