CodeXray CLI

Scan your codebase and visualize it as an interactive dependency graph. CodeXray helps you understand complex codebases by creating a visual atlas of your code structure, imports, and relationships.

Features

• 📊 Interactive Visualization - See your code as a graph with files as nodes and imports as edges
• 🔍 Dependency Analysis - Automatically detects imports and relationships between files
• 🗂️ Folder Grouping - Visual organization by directory structure
• 🚀 Language Support - TypeScript, JavaScript, Python, Rust, Go, and more
• ⚡ Fast Scanning - Efficient chunked streaming for large codebases
• 🌐 Browser-based Atlas - Automatic browser opening after scan

Installation

npm install -g codexray-cli

Or use directly with npx:

npx codexray-cli scan .

Usage

Basic Scan

Scan your current directory:

codexray scan

Scan a specific directory:

codexray scan /path/to/project

Initialize Ignore File

Create a .codexrayignore file with common patterns:

codexray init

Connect to Remote Server

By default, CodeXray expects a local server at http://localhost:3000. To use a different server:

codexray scan . --api-base https://your-codexray-server.com

Or set an environment variable:

export CODEXRAY_API_BASE=https://your-codexray-server.com
codexray scan .

Options

Options:
  -u, --api-base <url>         CodeXray server URL (default: http://localhost:3000)
  -s, --session-id <id>        Session ID (auto-generated if not provided)
  --max-chunk <bytes>          Max bytes per chunk (default: 20480)
  --no-open                    Don't open browser after scan
  -i, --ignore <patterns...>   Additional patterns to ignore
  --show-ignored               Show which files are being ignored
  --no-default-ignore          Disable default ignore patterns
  -h, --help                   Display help
  -V, --version               Display version

Examples

Scan with custom server:

codexray scan . --api-base https://codexray.example.com

Scan without opening browser:

codexray scan . --no-open

Use specific session ID:

codexray scan . --session-id my-project-session

Self-Hosted Server

To run your own CodeXray server:

1. Clone the repository:

git clone https://github.com/yourusername/codexray.git
cd codexray

2. Install dependencies:

pnpm install

3. Start the server:

pnpm dev:web

4. Use the CLI with your local server:

codexray scan . --api-base http://localhost:3000

Supported Languages

CodeXray automatically detects programming languages by file extension:

• JavaScript/TypeScript: .js, .jsx, .ts, .tsx
• Python: .py
• Rust: .rs
• Go: .go
• Java: .java
• C#: .cs
• C/C++: .c, .cpp, .h
• Web: .html, .css, .svelte, .vue
• Config: .json, .yaml, .yml
• Documentation: .md

Ignored Paths

The following are automatically excluded from scans:

• node_modules/
• .git/
• dist/
• .next/
• Build and cache directories

Troubleshooting

Connection Issues

If you get a "failed to create session" error:

• Ensure the CodeXray server is running
• Check the server URL with --api-base
• Verify network connectivity

Large Codebases

For very large projects, you may want to:

• Increase chunk size: --max-chunk 50000
• Scan specific subdirectories instead of the entire project

License

MIT

Contributing

Contributions are welcome! Please check the main repository for guidelines.

Links

• GitHub Repository
• Documentation
• Issues