CodeXRay

AI-powered codebase analyser that detects design patterns, assesses coding standards, summarises classes, and generates improvement suggestions. Built for new-joiner developers to understand a codebase quickly.

How It Works

CodeXRay uses a hybrid architecture:

1. codexray init — runs in the terminal. Scans your project structure, detects tech stack and modules, creates configuration files. No AI needed.
2. /codexray:analyse — runs in VS Code Copilot Chat. Uses GitHub Copilot's LM to analyse each module for patterns, standards, and class summaries. No API key needed.
3. /codexray:report — runs in Copilot Chat. Generates executive summary, onboarding guide, and health scores from analysis data.
4. /codexray:suggest — runs in Copilot Chat. Generates prioritised improvement suggestions and quick wins.

Installation

Option A: Install from npm (recommended)

npm install -g codebase-xray

Then use from any project:

cd /path/to/your/project
codexray init

Option B: Clone and link

git clone [email protected]:munnik486_comcast/CodeXray.git
cd CodeXray
npm install && npm run build
npm link

Copilot Chat Commands Setup

To use /codexray:analyse, /codexray:report, and /codexray:suggest in Copilot Chat, copy these folders into your target project:

.github/prompts/codexray-analyse.prompt.md
.github/prompts/codexray-report.prompt.md
.github/prompts/codexray-suggest.prompt.md
.github/skills/codexray/

These prompt files tell Copilot Chat how to run the analysis. They're project-level, not part of the npm package.

Quick Start

1. Install

npm install
npm run build

2. Initialise

npx codexray init

This scans your project and creates:

• codexray/config.yaml — configuration (edit to adjust scope)
• codexray/overview.md — project overview
• codexray/structure.md — module map and directory tree

3. Analyse

Open VS Code Copilot Chat and run:

/codexray:analyse

This generates per-module analysis in codexray/modules/:

• summary.md — what the module does
• classes.md — per-class/function summaries
• patterns.md — design patterns found

Plus codebase-wide files:

• codexray/patterns.md — pattern inventory
• codexray/standards.md — coding conventions

4. Report (optional)

/codexray:report

Generates codexray/report/summary.md, onboarding.md, health.md.

5. Suggest (optional)

/codexray:suggest

Generates codexray/suggestions/improvements.md, quick-wins.md.

Scope to a module: /codexray:suggest auth

Configuration

Edit codexray/config.yaml:

version: 1
include:
  - src/**
exclude:
  - '**/test/**'
  - '**/node_modules/**'
depth: full          # full | summary | quick
modules: []          # auto-detected if empty
language: typescript  # auto-detected
framework: ''        # auto-detected

Depth Levels

| Depth | Module Files | Top-Level Files | |-------|-------------|-----------------| | full | summary + classes + patterns | overview + structure + patterns + standards | | summary | summary + patterns | overview + structure + patterns + standards | | quick | none | overview + structure only |

Output Structure

codexray/
├── config.yaml        # Configuration
├── .lastrun           # Last analysis state (for diff-aware reruns)
├── overview.md        # Project overview
├── structure.md       # Module map + directory tree
├── patterns.md        # Codebase-wide design patterns
├── standards.md       # Coding conventions
├── modules/
│   ├── <module>/
│   │   ├── summary.md
│   │   ├── classes.md
│   │   └── patterns.md
│   └── ...
├── report/            # Generated by /codexray:report
│   ├── summary.md
│   ├── onboarding.md
│   └── health.md
└── suggestions/       # Generated by /codexray:suggest
    ├── improvements.md
    └── quick-wins.md

Supported Languages

JavaScript/TypeScript, Java, Kotlin, Go, Rust, Python, PHP, Ruby, Elixir, C#, C/C++, Swift, Dart, Lua, R, Scala, Vue, Svelte.

CLI Alternative

If you have a GitHub PAT or OpenAI API key, you can add an ai section to config.yaml and use the CLI directly:

ai:
  type: github-copilot   # or: openai, ollama
  model: openai/gpt-4.1
  apiKey: ''              # or set GITHUB_TOKEN env var

Then run codexray analyse, codexray report, codexray suggest in the terminal.

Requirements

• Node.js 18+
• VS Code with GitHub Copilot (for Copilot Chat commands)