Metadata-Version: 2.5
Name: paranoid-atlas-cli
Version: 0.13.0
Summary: The Atlas method made executable: create and keep Atlases in order
Project-URL: Homepage, https://atlas.paranoid.software
Project-URL: Repository, https://github.com/paranoid-software/atlas-cli
Project-URL: Issues, https://github.com/paranoid-software/atlas-cli/issues
Author: Paranoid Software
License-Expression: MIT
Keywords: agents,atlas,claude,cli,spec-driven
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# atlas-cli

The [Atlas](https://atlas.paranoid.software) method made executable: create an Atlas and keep
it in order while several people and agents work in it.

> **What Atlas is:** a Claude-anchored, spec-driven way to keep the context of real software
> projects — one folder per project, its sources linked by symlink, so any agent opens it cold
> and knows what it is, where each source lives, where the work stands and how it gets closed.

## 1. Prerequisites (macOS + Windows)

> **Windows users:** run everything below in **Git Bash** (installed with Git for Windows), not
> PowerShell or cmd: the Atlas hooks are bash scripts, and Claude Code runs them through Git
> Bash. Install tools with `winget` in PowerShell, then **reopen Git Bash**.

| Tool | What it's for | macOS | Windows (PowerShell, then reopen Git Bash) |
|---|---|---|---|
| **Git** (+ Git Bash) | Sources and shared Atlases are git repos; on Windows, Git Bash runs the hooks. | `brew install git` | `winget install Git.Git` |
| **jq** | The hooks read and write JSON with it. Without it, they stay silent and the coding-rules gate lets every edit through. | `brew install jq` | `winget install jqlang.jq` |
| **uv** | Installs the `atlas` CLI with its own Python. | `brew install uv` | `winget install astral-sh.uv` |
| **Claude Code** | The anchor agent. | see claude.com/claude-code | see claude.com/claude-code |

**Windows only — allow symlinks:** Settings → *Privacy & security* → *For developers* → turn
**Developer Mode ON**, so `atlas link` can create symlinks without admin rights.

Check:

```bash
git --version && jq --version && uv --version && claude --version
```

## 2. Install

```bash
uv tool install paranoid-atlas-cli
```

The command is `atlas`; `atlas --version` confirms it. If the shell can't find it, run
`uv tool update-shell` and open a new terminal. Upgrade later with
`uv tool install --reinstall paranoid-atlas-cli`.

## 3. Install the machinery for Claude Code

```bash
atlas setup claude
```

It installs the hooks, the `/atlas-init` and `/atlas-sync` commands and the `workspace-baseline`
skill into `~/.claude` (or `CLAUDE_CONFIG_DIR` when set), wires the hooks into `settings.json`
after any hook already there, without touching anything else, and creates `atlas-source` pointing at the
official site when there is none. Run it again after every upgrade; it only changes what
differs.

**Where the framework comes from:** `atlas-source` holds one line — a URL (the official site, or
a local copy of it served on `http://localhost:8088`) or the path of a local clone of the
framework repo. A clone serves the `method/*.md` pages only — its index is `method/README.md`;
the `llms.txt` index the agent starts from is generated by the site. To change it:

```bash
printf '%s\n' "http://localhost:8088" > "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/atlas-source"
```

With `CLAUDE_CONFIG_DIR` set, every `~/.claude/…` path in the machinery lives under that folder
instead.

**Cursor** reads Claude Code's configuration from `~/.claude`: once this step is done, it gets
the hooks, the commands and the skill — don't copy them into `~/.cursor/`. The one thing to add
on Cursor's side is the MCP server behind an Atlas's `coding-rules` plugin, if it has one, in
`~/.cursor/mcp.json`.

**The coding-rules gate.** In an Atlas that declares the `coding-rules` plugin, a hook blocks
the first code edit of each Claude Code session until the declared source has been consulted.
If the source can't be reached, start Claude Code with `ATLAS_CODING_RULES_GATE=off` to let
edits through.

## 4. Use it

- **Create an Atlas:** in a new folder, `atlas init`, then `atlas link <name> <path>` for each
  source and `atlas doctor` to check them — or `/atlas-init` in Claude Code, which does the
  same with you.
- **Join a shared Atlas:** clone it, run `atlas doctor` inside it and follow what it says.
- **Older Atlas:** `atlas migrate` shows the plan to bring it to the current model;
  `atlas migrate --apply` applies it.
- **Day to day:** `atlas status` says where things stand; `/atlas-sync` is the checkpoint;
  `atlas unlink <name>` drops a source the Atlas no longer uses.

How an Atlas works — its files, SPECs, cadence and sharing — is the method:
[creating an Atlas](https://atlas.paranoid.software/method/06-bootstrap) and
[sharing one](https://atlas.paranoid.software/method/07-sharing-an-atlas). `atlas --help` lists
every command.

## Troubleshooting

| Symptom | Fix |
|---|---|
| `atlas: command not found` | `uv tool update-shell`, then a new terminal. |
| `atlas-fetch: configure …/atlas-source` | Re-run `atlas setup claude`, or write a URL or clone path into that file. |
| `jq: command not found` | Install jq (step 1); on Windows, reopen Git Bash afterwards. |
| Hooks do nothing on Windows | Not in Git Bash, or Git for Windows isn't installed (step 1). |
| `atlas link` can't create the symlink (Windows) | Turn Developer Mode on (step 1). |
| The site doesn't answer | Serve the framework locally and point `atlas-source` at it (step 3). |

## Develop

```bash
uv sync
uv run atlas --version
uv run pytest
```

## Release

Bump `version` in `pyproject.toml`, commit, then push a matching tag (`v0.1.1` for `0.1.1`):
the `Publish paranoid-atlas-cli to PyPI` workflow builds and publishes it. A tag that doesn't match the
version fails the workflow.
