Code graph visualization and analysis CLI - index codebases, query dependencies, trace data flow
npm install codegraph-cli> Code graph visualization and analysis CLI - index codebases, query dependencies, trace data flow




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.
- Bun 1.0+ - Install Bun
``bashmacOS/Linux
curl -fsSL https://bun.sh/install | bash
$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 codeThe 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
- .codegraphPerformance
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 overheadTypical 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-cliInstall dependencies
bun installBuild
bun run buildRun locally
bun dist/cli/index.js index .Run tests
bun testType check
bun run typecheckLint
bun run lint
``MIT