Metadata-Version: 2.4
Name: claude-atlas
Version: 0.3.0
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 report for deeper triage.

```bash
# Install (from GitHub — not yet on PyPI)
uv tool install git+https://github.com/grippado/claude-atlas

# 5-second health check
claude-atlas check

# Full interactive report
claude-atlas scan
```

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

## Install

**Prerequisites:** Python 3.11+ and [`uv`](https://docs.astral.sh/uv/). Install `uv` with:

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

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

Then install claude-atlas. It's **not on PyPI yet** — install directly from GitHub:

```bash
# Recommended: isolated tool install from GitHub
uv tool install git+https://github.com/grippado/claude-atlas

# Or from a local clone
git clone https://github.com/grippado/claude-atlas.git
cd claude-atlas
uv tool install .

# Or for development (editable install)
uv sync --all-extras
uv run claude-atlas --help
```

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

## 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. Click nodes to inspect, switch to the **Issues** tab to see what needs attention.

## 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 "git+https://github.com/grippado/claude-atlas[semantic]"
```

## Commands

```text
claude-atlas scan        full scan + report
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).

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

**Next up: v0.4.0 — HTML triage dashboard.** The graph view becomes a secondary tab; the primary view becomes a card-based triage dashboard with health score, side-by-side previews, and per-issue actions. Follow progress in [#1](https://github.com/grippado/claude-atlas/issues/1).

**Considering:** interactive fix-prompt export (`claude-atlas fix`), scan history diffing, pre-commit hook templates, editor status-bar plugin.

**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).
