atlas-cli

The Atlas 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.

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

Check:

git --version && jq --version && uv --version && claude --version

2. Install

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

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:

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.
• A SPEC's life: atlas spec new <SLUG> creates it and indexes it in the backlog; atlas spec start <name> stamps it, enters it in STATUS → Active and prints the branch commands; atlas spec pause|resume|review <name> keep its Active block; atlas spec close <name> stamps it, archives it with its findings and lists it as recently closed, refusing while its branch is unmerged; atlas spec lint reports what a SPEC carries that it should not. The Done / Next / Blocked lines are yours or the agent's.
• Day to day: atlas status says where things stand; atlas orient prints what an agent needs at session start — stores, cadence, coding rules, state — and is the entry point for any workbench or editor (Claude Code's session hook just calls it); /atlas-sync is the checkpoint; atlas unlink <name> drops a source the Atlas no longer uses; atlas ui opens a local, read-only page on the Atlas — doctor made plain, the SPECs with search, stats, rules and machinery.

How an Atlas works — its files, SPECs, cadence and sharing — is the method: creating an Atlas and sharing one. atlas --help lists every command.

Troubleshooting

Develop

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.