claude-atlas

0.5.0 verified Fri May 01 auth: no javascript

CLI and VS Code extension to visualize, lint, and refactor your Claude Code agent configurations. v0.5.0 released Mar 2025. Reads agents/, commands/, .mcp.json, and settings.json to build a dependency graph, detects dead agents, delegation cycles, missing references, and unused tool grants. Provides safe rename and permission blast-radius queries. No LLM calls, no telemetry, open source (MIT). Node 20+ required.

Common errors

error Error: Cannot find module 'claude-atlas' ↓

cause Package not installed globally or locally.

fix

Install with npm install -g claude-atlas or use npx claude-atlas.

error SyntaxError: Unexpected token '??' ↓

cause Node version below 20 does not support nullish coalescing.

fix

Upgrade Node to >=20.

error Error: EACCES: permission denied, open '.claude/settings.json' ↓

cause Rename command requires write access to .claude/ files.

fix

Run with appropriate permissions or use --dry-run to preview.

error Error: Unable to parse .mcp.json ↓

cause Invalid JSON in .mcp.json file.

fix

Validate with npx claude-atlas scan .claude --json to see parsing errors.

Warnings

breaking v0.5.0 introduces VS Code extension; CLI users are unaffected but extension auto-detects .claude/ folder. ↓

fix None needed; extension is additive.

breaking v0.4.0 added invokesOrdered array; invokes string array remains but new code should prefer invokesOrdered. ↓

fix Update consumers to handle both invokes and invokesOrdered.

breaking v0.3.0 introduced permission blast-radius via `who-can` subcommand. ↓

fix None.

breaking v0.2.0 added rename subcommand; writing to config files may require file system permissions. ↓

fix Run with appropriate node --experimental-wasm-modules if needed.

gotcha Dead agent detection triggers false positives for agents invoked via dynamic references (e.g., environment variables). ↓

fix Suppress with // atlas-ignore-line or // atlas-ignore-next-line.

Install

npm install claude-atlas

yarn add claude-atlas

pnpm add claude-atlas

Imports

default

wrong

const atlas = require('claude-atlas')

correct

import atlas from 'claude-atlas'

ESM-only since v0.1.0

scan
```
import { scan } from 'claude-atlas'
```
Named export for programmatic scanning
lint
```
import { lint } from 'claude-atlas'
```
Named export for programmatic linting

Quickstart

Launch the interactive graph viewer on port 4000 from a .claude directory.

npx claude-atlas serve .claude -p 4000