Metadata-Version: 2.4
Name: claude-atlas
Version: 0.5.2
Summary: Scan, map, and visualize your Claude Code setup: agents, skills, slash commands, and memory files.
Project-URL: Homepage, https://github.com/grippado/claude-atlas
Project-URL: Repository, https://github.com/grippado/claude-atlas
Project-URL: Issues, https://github.com/grippado/claude-atlas/issues
Author: Gabriel Gripp
License: MIT
License-File: LICENSE
Keywords: anthropic,claude-code,cli,developer-tools,graph-visualization
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: chevron>=0.14
Requires-Dist: networkx>=3.2
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-chevron; extra == 'dev'
Provides-Extra: semantic
Requires-Dist: anthropic>=0.40; extra == 'semantic'
Description-Content-Type: text/markdown

# 🗺️ Claude Atlas

> Audit your Claude Code setup. Find duplicate agents, conflicting triggers, and orphaned memory files before they silently break your workflow.

**Languages:** [English](README.md) · [Português 🇧🇷](README.pt-BR.md)

<p align="center">
  <img src="https://raw.githubusercontent.com/grippado/claude-atlas/main/docs/screenshots/atlas.png" width="300" alt="Claude Atlas logo" />
</p>

---

If you've been building out `~/.claude/` for a while, you probably have:

- Two agents that do nearly the same thing, competing for the same triggers.
- A `CLAUDE.md` you wrote for a project you abandoned months ago.
- A global skill quietly shadowed by a project-scoped version in one of your repos.
- No clear picture of how many artifacts you've accumulated total.

**Claude Atlas scans your setup and surfaces these in seconds.** Run it in your terminal for a quick health check, or generate an interactive HTML triage dashboard for deeper work.

```bash
# Install
uv tool install claude-atlas

# 5-second health check (with a 0-100 health score)
claude-atlas check

# Full triage dashboard
claude-atlas scan
```

You get:

- A **health score** (0-100) so you can tell at a glance whether your setup is getting better or worse over time.
- A **triage dashboard** with side-by-side previews of each conflicting pair, one-click "Copy fix prompt for Claude Code", and a "Show diff" toggle.
- A **`fix` command** that hands you a ready-to-paste prompt for Claude Code — without ever touching your files itself.
- A **`check --since`** flag that diffs against a previous run so you can prove a refactor actually helped.
- A **pre-commit hook** to keep new conflicts from sneaking in.

Offline by default. No telemetry. MIT licensed. Docs in EN + PT-BR.

## Install

**Prerequisites:** Python 3.11+ and [`uv`](https://docs.astral.sh/uv/) (or `pipx` / `pip`).

If you don't have `uv` yet:

```bash
# macOS (Homebrew)
brew install uv

# macOS / Linux (official installer)
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Then install claude-atlas:

```bash
# Recommended: isolated tool install (from PyPI)
uv tool install claude-atlas

# Or with pipx
pipx install claude-atlas

# Or plain pip
pip install claude-atlas
```

To upgrade: `uv tool upgrade claude-atlas`.

### From source

```bash
git clone https://github.com/grippado/claude-atlas.git
cd claude-atlas
uv sync --all-extras
uv run claude-atlas --help
```

## Quick start

```bash
# Scan ~/.claude + current dir, output to ./claude-atlas.html
claude-atlas scan

# Scan specific trees
claude-atlas scan --paths ~/work/arco --paths ~/work/flagbridge -o /tmp/atlas.html

# Auto-discover nested .claude/ dirs under several trees
claude-atlas scan --auto-discover ~/work --auto-discover ~/personal

# Refine duplicate candidates with Claude (needs ANTHROPIC_API_KEY)
claude-atlas scan --semantic
```

Open the resulting HTML in a browser. The report opens on the **Triage** view:

- Issues grouped by severity (high / medium / low), each rendered as a card with the two artifacts' frontmatter and body excerpts side by side.
- Per-card actions: **Open source / target** in your editor, **Show diff**, **Copy fix prompt** (with or without the diff), **Skip** to dismiss false-positives — skip state persists in your browser via `localStorage`.
- A small **concentration treemap** at the top shows where the problems cluster (by scope × kind); click a cell to filter the cards.
- The **Graph** tab is still available for relationship exploration — lazy-loaded so the report stays light if you stick to triage.

## What it detects

| Edge kind             | Meaning                                                                 |
|-----------------------|-------------------------------------------------------------------------|
| `duplicate_exact`     | Identical SHA-256 body hash — one is a literal copy of the other.       |
| `duplicate_semantic`  | Jaccard similarity ≥ 0.60 (suspicious) / ≥ 0.85 (probable).             |
| `overrides`           | Project artifact shadows a same-named global one.                        |
| `trigger_collision`   | Two artifacts share ≥ 2 distinctive trigger tokens.                      |
| `references`          | One artifact's body mentions another's name.                             |
| `contains`            | Memory file groups artifacts in the same `.claude/` root (UI only).      |

Thresholds live in `src/claude_atlas/analysis/graph.py` if you want to tune them.

## Optional: LLM-as-judge

With `--semantic`, pairs flagged by Jaccard are sent to the Anthropic API for a structured verdict (`duplicate` / `overlap` / `distinct`). Pairs the model calls "distinct" are dropped from the graph; the rest get the model's reasoning attached to the edge detail.

Requires `ANTHROPIC_API_KEY`. Reinstall with the `semantic` extra to pull the `anthropic` SDK:

```bash
uv tool install "claude-atlas[semantic]"
```

## Commands

```text
claude-atlas scan        full scan + report
claude-atlas check       lint-style health check (CI-friendly)
claude-atlas fix         generate a Claude Code prompt for selected issues
claude-atlas report      alias for scan with default flags
claude-atlas version     print version
```

Run any command with `--help` for full flags.

## CI / pre-commit usage

Use `claude-atlas check` for lint-style health checks in scripts and CI:

```bash
# Default: fail on any HIGH-severity issue
claude-atlas check

# Pre-commit hook: only fail on duplicates and overrides
claude-atlas check --max-severity high --quiet

# CI with GitHub Actions annotations
claude-atlas check --format github

# Get everything as JSON for custom tooling
claude-atlas check --top 0 --format json
```

Exit codes: `0` (clean), `1` (issues found at threshold), `2` (error).

### Track health over time

`--since` diffs the current scan against a previous snapshot you wrote yourself — no state directory, no telemetry, just two JSON files:

```bash
# Today: save a snapshot
claude-atlas check --top 0 --format json > /tmp/atlas-snap.json

# Tomorrow (after some refactoring): see what changed
claude-atlas check --since /tmp/atlas-snap.json
# → Found 9 issues (...) in 93 artifacts. Health: 82/100 (B).
#   Since snapshot: +1 new, -4 resolved. Health 75→82 (+7).
```

Useful before/after big refactors to confirm you actually moved the needle.

### Generate a fix prompt for Claude Code

`claude-atlas fix` turns detected issues into a markdown prompt you paste into Claude Code. The tool itself never edits files — it just hands you the prompt.

```bash
claude-atlas fix                          # interactive picker
claude-atlas fix --all                    # include every issue, no prompt
claude-atlas fix --severity high --all    # all HIGH-severity issues
claude-atlas fix | pbcopy                 # copy prompt to clipboard (macOS)
```

The interactive picker accepts comma/range syntax: `1,3,5-7` picks issues 1, 3, 5, 6, 7. Pass `all` (or just press Enter) to take everything, `q` to cancel.

If you'd rather pick visually, open the HTML report and use **Copy fix prompt** (or **Copy prompt + diff**) on individual cards — same output, one issue at a time.

### As a [pre-commit](https://pre-commit.com) hook

Add to your `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: https://github.com/grippado/claude-atlas
    rev: v0.5.2  # or any tag from https://github.com/grippado/claude-atlas/releases
    hooks:
      - id: claude-atlas           # fails only on HIGH severity
      # - id: claude-atlas-strict  # fails on MEDIUM and HIGH
```

Both hooks run `claude-atlas check --quiet` against your repo's `.claude/` directory on every commit.

## Project layout

```
src/claude_atlas/
├── cli.py                 # typer CLI
├── models.py              # dataclasses + enums
├── scanner/
│   ├── discovery.py       # find .claude/ dirs and CLAUDE.md files
│   └── parsers.py         # frontmatter → Artifact
├── analysis/
│   ├── graph.py           # heuristics → Edge list
│   └── llm_judge.py       # optional Anthropic refinement
└── report/
    ├── renderer.py        # ScanResult → HTML
    └── templates/report.mustache
```

## Roadmap

Claude-atlas is in active evolution. See the full [ROADMAP.md](ROADMAP.md) for principles, released versions, and what's planned. Live tracker: [GitHub Milestones](https://github.com/grippado/claude-atlas/milestones).

**Shipped recently:**
- **v0.5.2** — Scanner dedupes artifacts by real path, eliminating false-positive `duplicate_exact` edges from symlinked commands/agents/skills.
- **v0.5.1** — `Show diff` per issue + `Copy prompt + diff` for sharper Claude Code fixes.
- **v0.5.0** — HTML triage dashboard: triage view as default, side-by-side previews, per-issue actions, concentration treemap, graph as a lazy-loaded secondary tab.
- **v0.4.0** — Backend foundation: health score, `check --since` diff, `fix` command, pre-commit hook templates.

**Considering:** editor status-bar plugin (VS Code) for ambient health-score awareness.

**Won't do:** automatic editing/deletion of artifacts, cloud sync, accounts, or support for non-Claude-Code AI tools. See the [anti-roadmap](ROADMAP.md#anti-roadmap-wont-do) for why.

## Contributing

PRs welcome. Before opening one:

```bash
uv sync --all-extras
uv run pytest
uv run ruff check .
uv run mypy
```

## License

MIT — see [LICENSE](LICENSE).
