whobreaks

Find out what breaks before you touch a file.

whobreaks builds a real-time dependency graph of your codebase and tells you the blast radius of any change — before you make it. Works as a CLI, HTTP API, and MCP server for AI coding tools.

# Without whobreaks:
AI edits UserService.ts → breaks 14 files → you spend 2 hours fixing

# With whobreaks:
AI queries whobreaks first → knows 14 files depend on UserService → makes safe changes

Quick start

npx whobreaks .

  ╭──────────────────────────────────────╮
  │  💥 whobreaks v0.1.0                 │
  │  Scanning your codebase...           │
  ╰──────────────────────────────────────╯

  📁 Found 247 files
  ⏱️  Analyzed in 1.2s

  ┌─ Summary ──────────────────────────────┐
  │                                        │
  │  Files:              247               │
  │  Edges:            1,847               │
  │  Avg depth:          4.2               │
  │  Max depth:           11               │
  │                                        │
  └────────────────────────────────────────┘

  ⚠️  Issues Found:

  🔄 Circular Dependencies (3)
     src/services/auth.ts ↔ src/services/user.ts
     src/models/order.ts → src/models/product.ts → src/models/order.ts

  🏝️  Orphan Files — imported by nothing (12)
     src/utils/old-helpers.ts
     src/components/DeprecatedButton.tsx

  🕸️  God Modules — imported by 20+ files (2)
     src/utils/helpers.ts        → 89 dependents
     src/lib/api-client.ts       → 47 dependents

  💣 High-Impact Files — editing these affects the most files
     src/types/index.ts          → 142 files affected
     src/utils/helpers.ts        → 89 files affected

  📁 Output: .whobreaks/graph.json

MCP setup

whobreaks runs as an MCP server so AI tools (Claude Code, Cursor, Windsurf) can query it before editing files. Set it up once; the AI uses it automatically.

Claude Code

claude mcp add whobreaks npx whobreaks mcp

That's it. Verify:

claude mcp list
# whobreaks: npx whobreaks mcp

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "whobreaks": {
      "command": "npx",
      "args": ["whobreaks", "mcp"]
    }
  }
}

VS Code (Copilot / GitHub Copilot Chat)

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "whobreaks": {
      "type": "stdio",
      "command": "npx",
      "args": ["whobreaks", "mcp"]
    }
  }
}

Windsurf

Create .windsurf/mcp_config.json in your project root:

{
  "mcpServers": {
    "whobreaks": {
      "command": "npx",
      "args": ["whobreaks", "mcp"]
    }
  }
}

Tell the AI to use it (CLAUDE.md / .cursorrules)

Drop this in your CLAUDE.md or .cursorrules:

## Architectural awareness

This project has whobreaks running as an MCP server.

Before editing any file, call:
- `get_impact` — see how many files depend on it and which exports are critical
- `get_context` — understand what it imports/exports and its risk level

Before creating a new file or moving an export, call:
- `find_related` — check if similar functionality already exists

Files with 20+ dependents are god modules — treat export changes as breaking changes.
Files in circular dependencies require extra care — changes propagate in both directions.

Available MCP tools

Tool	When to use
`get_impact`	Before editing any file — see direct + transitive dependents and critical exports
`get_context`	Before editing — full picture: imports, exports, risk level, line count
`find_related`	Before creating something new — check if it already exists

get_impact("src/services/user.ts")
→ Editing this file will affect 14 files:
  Direct dependents (3): auth.ts, dashboard.ts, settings.ts
  Transitive (11): app.tsx, router.ts, ... +9 more
  High-usage exports: getUserById, UserSchema

get_context("src/services/user.ts")
→ ## src/services/user.ts
  Imports from (2): db/client.ts, utils/crypto.ts
  Imported by (3): auth.ts, dashboard.ts, settings.ts
  Exports: getUserById (function), UserSchema (type), updateUser (function)
  Risk level: MEDIUM (3 dependents)
  Lines: 187

Watch mode + live dashboard

npx whobreaks watch . --port 3001

Starts a file watcher and HTTP server. Open http://localhost:3001 for the interactive dependency graph dashboard.

The dashboard auto-reloads when files change. Every node is sized by dependent count, colored by risk, and clickable for a full impact analysis panel.

HTTP API

Available when running whobreaks watch or whobreaks . --port <n>.

Endpoint	Description
`GET /`	Interactive dashboard
`GET /health`	Status, file count, edge count, last update
`GET /graph`	Full dependency graph (JSON)
`GET /summary`	Architecture summary (circulars, orphans, god modules)
`GET /impact?file=src/foo.ts`	Impact analysis — what breaks if this changes
`GET /dependents?file=src/foo.ts`	Files that import this file
`GET /dependencies?file=src/foo.ts`	Files this file imports
`GET /node?file=src/foo.ts`	Full node record with export list

Output files

Every scan writes to .whobreaks/ in your project root:

File	Contents
`graph.json`	Full dependency graph, machine-readable
`summary.md`	Human-readable architecture overview

Add .whobreaks/ to .gitignore or commit summary.md as living documentation.

Commands

npx whobreaks [path]              # One-shot scan (default: current directory)
npx whobreaks watch [path]        # Watch mode + HTTP API + dashboard
npx whobreaks mcp                 # MCP server (uses current directory)

Options:

Flag	Default	Description
`--port <n>`	3001	HTTP server port (watch mode)
`--max-files <n>`	unlimited	Cap files scanned (useful for huge monorepos)
`--help`		Show help

How it works

┌─────────────────────────────────────────────────┐
│                  whobreaks                       │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
│  │  Watcher  │→│ Analyzer  │→│  Graph Store  │  │
│  │(chokidar) │ │ (regex)   │ │ (in-memory)   │  │
│  └──────────┘  └──────────┘  └──────────────┘  │
│                                     │           │
│                          ┌──────────┴────┐      │
│                          │               │      │
│                    ┌─────▼──┐    ┌───────▼──┐   │
│                    │  CLI   │    │ MCP/HTTP  │   │
│                    │ Output │    │  Server   │   │
│                    └────────┘    └──────────┘   │
│                                                  │
│              ┌──────────────────┐                │
│              │  Web Dashboard   │                │
│              │ (D3 force graph) │                │
│              └──────────────────┘                │
└─────────────────────────────────────────────────┘

Watcher — chokidar watches **/*.{ts,tsx,js,jsx}, debounces rapid changes
Analyzer — regex-based import/export extraction on raw source text. Strips comments, extracts import/export statements, resolves specifiers via tsconfig.json paths, workspace package names, and filesystem probing. No compiler overhead — scans 2,500 files in ~2.5s.
Graph Store — in-memory Map<string, FileNode> with forward and reverse indexes. Incremental updates on file change.
MCP Server — @modelcontextprotocol/sdk exposes the graph to Claude Code, Cursor, Windsurf, and any MCP-compatible client.
Dashboard — single HTML file, D3 force-directed graph, served by the built-in HTTP server. No build step.

Compared to alternatives

Tool	Weakness vs whobreaks
`code-graph-context`	Requires Docker + Neo4j + OpenAI key
`typescript-graph`	One-shot only, no watch mode, no AI integration
`madge`	Only detects circular deps, no impact analysis
`ts-codebase-analyzer`	Library only — no CLI, no watch, no MCP

whobreaks: npx whobreaks . — no Docker, no API keys, no database. Zero config.

Development

git clone https://github.com/f1729/whobreaks
cd whobreaks
npm install
npm run build
node dist/index.js .

npm run dev    # tsc --watch

License

MIT

whobreaks
Release 0.1.0

Release 0.1.0

0.1.0

Documentation

whobreaks

Quick start

MCP setup

Claude Code

Cursor

VS Code (Copilot / GitHub Copilot Chat)

Windsurf

Tell the AI to use it (CLAUDE.md / .cursorrules)

Available MCP tools

Watch mode + live dashboard

HTTP API

Output files

Commands

How it works

Compared to alternatives

Development

License

Stats

Releases

Contributors

whobreaks Release 0.1.0

Release 0.1.0 Toggle Dropdown 0.1.0

Documentation

whobreaks

Quick start

MCP setup

Claude Code

Cursor

VS Code (Copilot / GitHub Copilot Chat)

Windsurf

Tell the AI to use it (CLAUDE.md / .cursorrules)

Available MCP tools

Watch mode + live dashboard

HTTP API

Output files

Commands

How it works

Compared to alternatives

Development

License

Stats

Releases

Contributors

whobreaks
Release 0.1.0

Release 0.1.0

0.1.0