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

$3

- Bun 1.0+ - Install Bun

``bash


macOS/Linux

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

Windows

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

$3

`bash
bun install -g codegraph-cli
`

$3

`bash
codemap --version
`

Quick Start

$3

`bash
cd your-project
codemap index .
`

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

$3

`bash


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

`bash


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:

$3

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

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

$3

| 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 |

$3

`bash


Get full JSON schema for automation


codemap schema --json
`

Commands

$3

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

$3

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

$3

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

$3

| 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

$3

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

$3

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

$3

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

$3

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

$3

`bash
codemap analyze . --all
`

$3

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

Keeping Up to Date

$3

`bash
codemap version --check
`

$3

`bash
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

$3

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

$3

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

$3

Run codemap index . first to create the index.

$3

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

$3

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

Uninstall

`bash
bun remove -g codegraph-cli
`

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

Development

For contributors:

`bash


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