claude-atlas

library0.5.0jsnpmunverified

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.

devops observability

npm install claude-atlas

github ↗package ↗

INSTALL

IMPORT

SIG · CLAUDE-ATLAS

claude-atlas

devopsjavascriptv0.5.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import atlas from 'claude-atlas'

✗ const atlas = require('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

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

npx claude-atlas serve .claude -p 4000

claude-atlas --version

Debug

Known issues

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

fix

None needed; extension is additive.

affects: >=0.5.0

breakingv0.4.0 added invokesOrdered array; invokes string array remains but new code should prefer invokesOrdered.

fix

Update consumers to handle both invokes and invokesOrdered.

affects: >=0.4.0

breakingv0.3.0 introduced permission blast-radius via `who-can` subcommand.

fix

None.

affects: >=0.3.0

breakingv0.2.0 added rename subcommand; writing to config files may require file system permissions.

fix

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

affects: >=0.2.0

gotchaDead 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.

affects: all

Errors

Common errors & fixes

Error: Cannot find module 'claude-atlas'

Package not installed globally or locally.

fix

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

SyntaxError: Unexpected token '??'

Node version below 20 does not support nullish coalescing.

fix

Upgrade Node to >=20.

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

Rename command requires write access to .claude/ files.

fix

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

Error: Unable to parse .mcp.json

Invalid JSON in .mcp.json file.

fix

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

Upgrade

Version history

0.5.0latest on npm

Audit

Dependencies

noderequiredRequires Node >= 20

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bernabranco/claude-atlas ↗

packagehttps://www.npmjs.com/package/claude-atlas ↗