Install

npm install -g @aziron/atlas

That's the whole install — no token, no registry configuration. The package downloads the matching native atlas binary for your platform during postinstall and verifies its SHA-256 checksum before extracting.

One-off use without a global install:

npx @aziron/atlas version

Quickstart

cd /path/to/repository
atlas index .
atlas bootstrap --dry-run   # preview assistant config changes
atlas bootstrap             # register MCP integrations
atlas status

Atlas can now answer questions like:

atlas search "checkout flow" --format plain   # where is it implemented?
atlas symbol CreateOrder                       # definition + callers + callees
atlas callers CreateOrder --limit 25           # who calls it?
atlas impact --paths services/cart.go          # what breaks if this changes?

The same answers are available to Claude, Codex, Cursor, Gemini, and GitHub Copilot through Atlas's MCP tools — with file:line citations on every result. Everything runs locally and is deterministic: no LLM in the loop, so the tool itself spends zero tokens.

The numbers

Measured on a public benchmark — 222 cells, 666 real LLM-scored model calls, across 37 languages. Full methodology and raw artifacts are published and reproducible.

| Approach | Answer accuracy (F1) | Context tokens / query | | --- | --- | --- | | Read the whole file (accuracy ceiling) | 1.00 | 157 | | Graph tool | 0.54 | 97 | | Atlas | 0.76 — and 1.00 on 28 languages | 21 |

+40% answer accuracy · 36× fewer query tokens · 17× faster queries · ~7 ms median who-calls answers.

In a real agent loop (sirupsen/logrus, 19 questions, Claude): 144k → 62k total tokens, F1 0.57 → 0.88, 19.9 s → 8.3 s versus grep-and-read.

Supported platforms

| OS | Architectures | |----|---------------| | macOS | x64, arm64 | | Linux | x64, arm64 | | Windows | x64 (arm64 is not built — the CGO cross-toolchain cannot target it) |

How the install works

postinstall downloads the matching GitHub Release archive and exposes it as the atlas binary. The npm tarball embeds the release-generated checksums.txt; before extracting, the installer computes the archive's SHA-256 digest and requires an exact match — a missing, malformed, duplicate, or mismatched checksum fails the installation. This verifies the archive against a manifest protected by npm's package integrity; it is checksum verification, not an independent signature.

Useful environment variables:

| Variable | Effect | | --- | --- | | ATLAS_BINARY=/path/to/atlas | Use an existing binary instead of downloading | | ATLAS_SKIP_DOWNLOAD=1 | Skip the download when packaging offline | | ATLAS_SKIP_BOOTSTRAP=1 | Skip assistant registration in automation | | ATLAS_NO_ANALYTICS=1 | Hard-deny the (already opt-in) usage telemetry, even over recorded consent (DO_NOT_TRACK=1 also honored) | | GITHUB_TOKEN / GH_TOKEN | Release-asset read access if the release repository is private |

Install analytics — opt-in only: Atlas sends nothing off your machine by default. On an interactive install (a real TTY, not CI and not npm install --yes), postinstall asks once:

May Atlas send anonymous usage telemetry (install + runtime pings to Google Analytics)? [y/N]

The default is No. Non-interactive installs never prompt and never send. Only after a recorded yes does the installer send one anonymous event — channel (npm), package and binary version, OS, arch, Node major version, and success/failure; no PII, no machine identifier (the client_id is a throwaway random UUID) — and the same recorded answer governs the atlas binary's runtime usage pings. Your decision is stored in ~/.atlas/telemetry-consent.json; change it anytime with atlas telemetry grant / atlas telemetry revoke. ATLAS_NO_ANALYTICS=1 and the standard DO_NOT_TRACK=1 deny absolutely, even over recorded consent. The ping is best-effort (3-second cap) and can never fail or slow your install.

Alternative: GitHub Packages coordinate

The same package is also published to GitHub Packages as @aziron-ai/atlas. Unlike this public npm package, GitHub Packages requires authentication even for public packages — create a GitHub token with the read:packages scope, then configure npm once:

# ~/.npmrc
@aziron-ai:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

npm install -g @aziron-ai/atlas

npm error 403 Forbidden - GET https://npm.pkg.github.com/@aziron-ai%2fatlas
npm error 403 permission_denied: read_package

This means the registry accepted your token (npm whoami --registry=https://npm.pkg.github.com succeeds) but your account is not authorized to read this specific package — it is never a client-side .npmrc problem. Work through, in order:

1. Authorize the token for SSO. If the aziron-ai organization enforces SAML SSO, a valid read:packages token is still rejected until it is authorized for the org: GitHub → Settings → Developer settings → Personal access tokens → your token → Configure SSO → Authorize for aziron-ai. This is the most common cause when whoami works but read_package is denied.
2. Confirm org membership / package access. You must be a member of aziron-ai (or a team) with read access to the package. An owner can check on the package page → Package settings → Manage access.
3. Package visibility. A GitHub Packages package is private by default (the publishConfig.access: "public" field is honored by npmjs.org but ignored by GitHub Packages). An owner makes it public at github.com/orgs/aziron-ai/packages → atlas → Package settings → Change visibility → Public. Note: even a public GitHub Packages package still requires a read:packages token to install — that is a GitHub Packages limitation, not an Atlas one.

Classic and fine-grained PATs both work as long as they carry read:packages and (for a private package) are SSO-authorized. write:packages is not needed to install.

None of this applies to the public @aziron/atlas package on npmjs.org, which installs with no authentication at all.

Documentation

Getting Started · Installation · CLI Reference · AI Assistant Setup · MCP Tools · Configuration · Privacy · Troubleshooting

License

Atlas is distributed under the Apache License 2.0.