Atlas

Every other coding agent's marginal cost is flat and its memory resets. Atlas gets cheaper, warier, and more trusted every week you use it.

Atlas is an open-source, model-agnostic, terminal-first coding agent with a persistent per-repo intelligence layer, a verification suite that attaches machine-checked receipts to every change, a learning pipeline that compiles repeated LLM work into deterministic zero-token codemods, and an orchestrator UI for running parallel tasks in isolated git worktrees.

That one-sentence thesis is the architectural organizing principle, not a tagline. Every major component exists to move one of three curves in the right direction over time, per repository.

The three pillars

1. Cheaper — Muscle Memory. When Atlas performs the same category of edit three times, it spends tokens once to compile that pattern into a deterministic AST codemod, verifies it by replaying the recorded before/after pairs from past sessions, and promotes it to a zero-token, sub-second command. The agent automates itself out of the loop.

2. Warier — Scar Tissue, Sentinel, Polygraph. Atlas mines reverts, hotfixes, and rejected diffs into a landmine map; warns when a staged change reverses something a teammate shipped recently (with author and PR link); and refuses to trust a weak test suite as its verification oracle — proving the weakness by planting mutants the suite fails to catch.

3. Trusted — Receipts + Trust Ladder. Every change ships with machine-checked claims (API surface unchanged, call-site behavior preserved, mutation score, perf within budget), and autonomy is earned per path from a verified ledger rather than configured by hand — rendered as a trust heatmap of the repo.

Status

Early development — P2 (Verification & Review) shipped on top of P1's repo intelligence. Atlas now verifies its work instead of vibing about it. Polygraph (atlas polygraph, spec §5.9): a builtin tree-sitter mutation engine (Stryker/mutmut adapters ride along opportunistically) plants bugs in the blast radius of a change, runs the repo's own suite against each, and renders an honest verdict with every surviving mutant as a concrete diff — the planted weak suite in the standard fixture comes out UNTRUSTED (0/11 mutants caught) and a strong suite comes out trusted; the gate runs in CI. Receipts (atlas receipts, spec §5.10/Appendix A): the full claim catalog over a base→worktree change set — api_surface, tests_added, lint_type_build, mutation_touched, callsite_behavior, perf_smoke, context_provenance — ed25519-signed, schema-validated, written to .atlas/receipts/<diff-hash>.json, attached to a trust-ledger row, and rendered in the TUI's receipts tab when the artifact's diff hash matches the selected task's diff. Claims whose engine is unavailable are skipped with a reason, never dropped, and an UNTRUSTED polygraph downgrades test-based claims to oracle-weak. Atlas's own repo runs receipts on its HEAD~1→HEAD diff in CI (the P2 exit criterion; the mutation engine is skipped loudly there — recorded in the artifact). Review (atlas review <pr>, spec §5.11): dual-mode PR thread addressing — Mode B's staged stepper ([a]pply+commit / edited-patch commit / [s]kip with a courteous reply / [d]iscuss) is the default; Mode A (autonomous plan→patch→verify→commit→reply→resolve per thread, real agent loop bound) sits behind the tier ≥ T2 policy gate; review comments are quarantined external data (§6.3) — the 8-thread fixture incl. a planted injection thread passes both modes in CI. Decision Blame (atlas why <file>:<line>, feature spec §6): every write/edit the loop applies records a provenance row (session, event, manifest hash, skill, model alias + fingerprint, clamped reasoning excerpt) — 200 planted hunks across rebases, squashes, and partial human rewrites resolve at 100% with zero misattributions in the CI gate, and human lines always answer "no agent provenance". CC4 model fingerprinting is stamped from day one: editor/planner fingerprints resolve at session start (static-evidence without keys; canonical-probe when a key is bound, cached 24h) into every receipt's workspace block and every provenance row — an evidence-grade heuristic, not proof. Observe-only in P2: the trust ledger (atlas trust) records agent commits, receipts, oracle-weak overrides, and reverts-of-agent-commits within 14 days per path scope — but no tier is ever promoted or demoted; tiers stay at the policy default until P3's promotion policy. Careful mode (minimal): commits touching ⚠⚠+ landmine paths require a Polygraph run on the touched scope (atlas g commit), with --no-polygraph as the escape hatch that records an oracle-weak ledger note. Known v1 boundaries, stated plainly: callsite_behavior is a partial harness (linked-test execution, not generated property tests) and skips honestly when unwired; perf_smoke needs a declared .atlas/perf.yaml; per-hunk cost attribution records 0 (a placeholder, not a guess); review Mode A's loop binding is bounded (12 turns / $0.50 per thread) and untested against live models. P1.5 (embeddings + summaries) has now shipped: the embedding subsystem (spec §5.4.4) defaults to a builtin deterministic lexical embedder (“builtin-v1”, 256-dim, zero keys/network — what CI uses; rebind the embedder role to any openai-compat /embeddings endpoint to upgrade), populated lazily by syncd's derived jobs and never blocking a sync. The store's hybrid retrieval is complete — lexical → structural → semantic (embeddings as a tiebreaker that appends and annotates, never outranking exact hits) — and complements()'s γ·embedding-sim term is live (0 when either vector is absent, never fabricated). Weak-role summaries (§5.4.5: symbol ≤ 40 / file ≤ 120 / module ≤ 250 tokens, hash-keyed, provenance-stamped, confidence-scored) generate lazily when a weak-role key resolves; without a key the rows stay absent and context manifests stay honestly pending. The AC-E1/E2/E3 gates run in CI (evals/p15): stride-rule pair mining (k ∈ [2,8], formatting-only commits excluded), hand-rolled deterministic logistic probes beating the majority baseline by ≥ 20 points on the fixture repos (module membership +71/+38/+65; co-change top-3 +31/+53/+47; landmine high/low +50 where planted, honestly repo-skipped where a fixture plants too few events), and the collapse monitor (participation-ratio effective rank + top-component share) — healthy on the fixtures, tripped by planted collapse, surfaced via atlas doctor --index. Known boundary, stated plainly: the builtin embedder is lexical — paraphrase recall works through shared identifier/path subtokens (the fixture gate: “http retry wait time” → the planted retry/backoff helper), not true synonyms; see packages/embed/README.md.

P3 (Learning Systems) has now shipped — the three curves have their machinery. Muscle Memory (atlas do <name> [paths] / atlas compile, spec §5.7): every completed edit is captured with pre/post hashes and a normalized AST-shape signature; the nightly job clusters ≥ 3 kept exemplars across ≥ 2 sessions (reverted work and ⚠⚠+ landmine paths vetoed), the planner role synthesizes one reviewable ast-grep YAML rule (@ast-grep/napi, exact-pinned; ts/tsx/js/jsx — python candidates park honestly as engine_unsupported), and the DP2 verification gate decides: byte-exact REPLAY over every exemplar (one miss → reject), a deterministic precision sweep with judge-or-user review of every outside match, post-condition hooks — only then does the skill go active in skills_compiled. Applying is zero-token and sub-second; the run-path matcher proposes matching skills below T2 and auto-applies at ≥ T2 within the skill's path scope (checkpoint first); a revert of a skill-applied change auto-suspends the skill pending review. The CI gate plants exemplar sessions, promotes the right rule, REJECTS a plausible-but-wrong rule at replay, applies via the real CLI with zero provider calls, and suspends on a simulated revert. Trust Ladder, ACTIVE (atlas trust [--evaluate], spec §5.13): tiers are now EARNED per path scope from the verified ledger — T1→T2 at ≥ 20 changes / ≥ 90% merged-unedited / 0 reverts in 30d; any reverted_within_14d demotes one tier immediately and engages a 14-day careful window; ⚠⚠+ landmine nodes impose a T1 ceiling (an overlay — the earned record survives, the cap lifts by decay); T3 is never reachable by track record alone (org opt-in + fully-verified receipts required). The executor resolves every path-bearing tool call at THAT path's effective tier, Mode A's gate uses the real min-tier over touched paths, and the heatmap (CLI + TUI, with the † ceiling marker now live) shows each scope's evidence and its open promotion case ("src/api/ is 2 clean merges from T2"). T0→T1 is configured, never auto-promoted (DP5: only autonomy above T1 is earned). Per-repo benchmark + Router v1 (atlas bench mine|run|leaderboard|apply, spec §5.12): merged PRs linked to issues with source+test changes and a reconstructable base become private bench tasks (squash/rebase merges aren't detected in v1; contamination honesty via per-model post_cutoff flags — no cutoff table means possibly contaminated, never clean); bench run is budget-HARD-capped, worktree-isolated, sandbox-oracled, and spends real money loudly; the leaderboard shows both contamination views and the ≥ 30-task recommendation table — applied only via explicit bench apply approval; escalate-on-failure retries a failed verification exactly once at the next ladder tier (no bandits, no ML routing — §2.2 rejections honored). Scar Tissue, behavioral (spec §5.8): agent-native mining (rejected diffs / reverted agent commits / failed receipt claims → landmine rows) rides the miner batch, and careful mode now carries the full requirement set — mandatory plan step, Polygraph regardless of tier, receipts mandatory, T1 ceiling, suggested human reviewer — while ⚠⚠+ exemplars are excluded from skill compilation. Coach (atlas coach, spec §5.14): five deterministic detectors over the session ledger deliver at most ONE tip per session, post-completion only, 7-day per-type cooldown, dismissible forever; the weekly weak-model reflection is key-gated and may only propose from the fixed catalog. All of it runs as syncd nightly jobs (scar mining → trust eval → muscle pipeline → revert auto-suspend → reflection) and in atlas sync. The honest dogfood caveat: P3 ships the machinery; the §5.7.2 exit numbers — ≥ 5 promoted skills, ≥ 15% of edit operations via compiled skills, the declining cost-per-merged-change curve — are measured over weeks of real use on a live repo. The curve is earned, not asserted; the CI gates prove the mechanisms, the dogfood repo proves the economics. Expect breaking changes on every commit until a tagged release exists.

Drift Canaries have now shipped — silent model regressions get caught, attributed, and routed around (feature-additions spec §5). Providers update models behind stable API names with no changelog; teams discover it as a slow degradation nobody connects to the cause (the "silent regression tax"). Atlas runs your own per-repo benchmark continuously as the measurement instrument. Slice (§5.2.1): 5–7 bench tasks stratified across clusters, biased short/cheap/high-discrimination, rotated monthly, composition-hashed. Nightly run (atlas canary run / the syncd job, §5.2.2): for each active role binding, the slice runs in the sandbox at fixed config, reusing the bench runner (worktree-isolated, HARD-capped at $0.40/night by default; bindings rotate without starvation when the cap can't cover all). Behavioral fingerprint (§5.2.3): pass/fail PLUS edit granularity (targeted-hunk vs. whole-file rewrite ratio — the "it rewrites entire files now" class benchmarks miss), context reads before first edit, tool-call mix, tokens-per-solved, receipts-failure rate, refusal/format anomalies. Detection (§5.2.4): a trailing 30-run baseline per binding alerts on a ≥ 15-point pass-rate drop sustained 3 nights OR ≥ 2 behavioral metrics shifted > 2σ sustained — single-night blips never alert (structural: there is no code path from one night's numbers to a finding; a baseline channel with no variance can never claim a shift). Attribution (§5.2.5): a changed §5.3 model fingerprint → "provider updated the model" with before/after evidence; an unchanged fingerprint + shifted behavior → "serving-stack or config drift" with the uncertainty stated plainly — and every alert keeps MEASURED facts ("pass rate fell 9 points on your repo") visually distinct from INFERENCES ("a fingerprint change suggests a provider update"). Action ladder (§5.2.6): alert always → on confirmed sustained drift, reroute the role to a configured fallback (or pin to a dated model), never silently — a ledger event, a TUI banner ("DRIFT: editor rerouted to fallback-b — will revert on recovery"), and a visible rebind in atlas doctor; it auto-reverts when the canary recovers and is always user-overridable (atlas canary override <id>, which suppresses re-rerouting for that fingerprint). While a role is in drift state its work is capped at T1 on landmine paths (the trust resolver composes the cap with its scar ceiling). The shareable artifact (CC3) ships with the feature: atlas canary alerts --share <id> writes the drift alert card as markdown (measured numbers under one heading, the hedged inference under another). OFF BY DEFAULT — nightly canaries spend real money (the weak-role-only, $0.40/night spend stays inside CC2's ≤ 3%-of-weekly budget); enabling is an explicit canary.enabled: true in .atlas/models.yaml. Honest limits, stated in the docs: with n ≈ 6 nightly tasks the thresholds err toward missing mild drift rather than crying wolf; on repos with < 30 bench tasks the canary runs in a labeled "low-confidence" mode that alerts but never reroutes; fingerprints are an evidence-grade heuristic, not proof, since providers expose differing amounts of version truth. The §5.5 CI gates (evals/canary) prove it: synthetic drift alerts on the 3rd post-flip night with correct provider-update/serving-drift attribution; 30 noisy quiet nights raise zero false alerts; the budget cap holds at p100 across rotation; reroute → auto-revert → override-suppression all fire loudly; a low-confidence repo alerts but never reroutes.

The Logbook has now shipped — a worker-owned, evidence-linked record of YOUR professional impact (feature-additions spec §3). Every analytics tool watches you for your boss; the Logbook keeps the record for you. It synthesizes locally from data Atlas already holds (merged-unedited changes with receipts, trust-tier promotions you earned, mutation deltas you shipped, reviews you addressed) into plain markdown in a vault you own — an Obsidian vault is a folder of markdown, so the integration is a directory write (no plugin, no API, no OAuth). The worker-owned invariant (INV-L1, §3.6) is the shipping condition, enforced as architecture not policy: the vault path lives in user config (~/.atlas/logbook.json), never repo/org config; the index lives in the user-scope ~/.atlas/global.db, never the repo store; a standing test (inv-l1, in packages/logbook AND evals/logbook) walks the whole policy parser + the on-disk configs/policies.yaml and fails CI if any logbook-addressable org key ever exists or parses; the vault write is the one declared out-of-workspace write grant in the product (named verbatim-ish in SECURITY.md), performed by the engine — agent tools still cannot write outside the workspace. Surfaces: atlas logbook init (vault path + per-source toggles, Slack/Jira off by default + redaction list, all to ~/.atlas/logbook.json), atlas logbook now (on-demand synthesis), atlas logbook open, atlas logbook status; the daemon runs synthesis weekly (key-gated, config-gated, weekly-clocked); the TUI shows one logbook line in the status bar (the vault is the UI). Entry quality is lint-enforced on the OUTPUT (§3.4): every quantitative claim carries ≥ 1 evidence link (receipt hash / PR / ledger row), past-tense plain prose, no adjectives without numbers, and zero verbatim sentences from external sources — entries failing any check are dropped with reasons (never silently shipped), and work Atlas can't back with evidence becomes an "uncaptured work — add manually?" prompt rather than an invented entry. Cost: ~$0.05/week — exactly one batched weak-role call regardless of event count (a > 60-event week is significance-floor-batched, reported loudly, never silently truncated); no key → honest skip; missing/unwritable vault → entries queue in the index + a notify, never written elsewhere; re-runs are idempotent (keyed by event-set hash — same week, identical vault, no duplicate rows). Kill switch: delete ~/.atlas/logbook.json. The §3.7 CI gates (evals/logbook) prove it: a fixture ledger → synthesis (MockProvider) → the written vault re-linted to zero uncited quantitative claims and zero verbatim external sentences; idempotent re-run (byte-identical tree); queue-on-missing-vault; the Appendix-A golden shape.

Code Recalls — the machinery has now shipped: a defective model version gets recalled like a defective car part (feature-additions spec §7). AI-written code is a manufactured artifact; when a manufactured part is found defective you don't shrug, you issue a recall. Atlas can do this for code because — uniquely — Decision Blame records which model version wrote which line. When a model version is found defective (a drift canary confirms degradation, a signed advisory lands, or your own incident implicates it), atlas recall --model <fingerprint> finds every hunk that fingerprint wrote, re-verifies each against current receipts + the Polygraph, repairs what fails with the current trusted model under careful mode, and publishes a recall notice — no one else can even enumerate code by model version. A recall is a bounded campaign (a budget preview + a resumable checkpoint), never a daemon: every run always prints the enumeration preview + budget estimate + the coverage boundary and confirms before re-verify/repair (--yes for scripts). Surfaces: atlas recall --model <fp> [--since <date>] [--paths <globs>] [--skill <name>] (the always-available manual path), atlas recall import <advisory.json> (verify a signed advisory's ed25519 signature → auto-propose, never auto-run), atlas recall list / status <RN-id> / resume <RN-id>; the TUI surfaces a proposal/active-campaign line. Triggers are a confirmed drift alert (auto-proposes a recall + a notice stub, never auto-runs), the manual command, or a signed advisory ("model X versions A–B → defect class Y" — a community standard Atlas proposes; a fingerprint "range" is an explicit signed set, since content-hash fingerprints have no order). The honest coverage boundary (§7.3 / CC4) is printed on every preview: recalls cover only code written after Decision Blame shipped — pre-provenance code has no fingerprint and is invisible to a recall (there is no retroactive provenance), and a recall never implies total coverage. Re-verification inherits every receipts limitation honestly — oracle-weak is reported, never silently passed — and tier rules apply to every repair set (careful mode caps at T1, so a repaired-clean set below the T2 auto-merge floor is staged for human review; landmine ⚠⚠ paths always require human review). Production auto-proposal-from-drift is itself behind the 60-day-dogfood enablement gate (a config flag, default off, that turns on only after Drift Canaries + Decision Blame hold their acceptance bars for 60 days in dogfood) — the machinery and manual command ship now; the automatic rung waits for earned confidence. The §7.4 CI gate (evals/recall) proves it: 30 hunks planted under a defective fingerprint (incl. 4 with a known defect class), pre-provenance decoys excluded, 100% exact enumeration, the defect caught + repaired, repairs grouped per module with receipts, budget respected, the notice complete in RN-format, plus a resumable-checkpoint sub-gate (interrupt → resume → completes, no hunk re-verified twice). The honest boundary, stated plainly: the re-verify/repair execution seam (binding the receipts claim catalog + Polygraph over a sandboxed runner, and the careful-mode bench loop + per-module PR creation) is the composition-root integration that lands next; until it does, atlas recall --model enumerates and previews exactly and reports the seam honestly rather than fabricating a verdict.

Install

Requires Node 20+ and git. A C toolchain is needed on first install (npm builds the native better-sqlite3 and @ast-grep/napi addons for your platform — no pnpm required on your machine). Docker is optional but recommended (sandboxed bash; without it every shell command requires per-command approval).

One-liner (git install)

npm i -g github:klingaling/atlas-agent#main   # puts `atlas` on your PATH

npm clones the repo, installs the pinned native/wasm runtime deps, and bundles the atlas binary from source on install (a self-contained ESM bundle of the workspace; the tree-sitter .wasm grammars and the bundled skill catalog ship alongside). First run rebuilds better-sqlite3/@ast-grep/napi for your platform — that needs a C toolchain and network. Once the package is published, the registry one-liner will be npm i -g @atlas-agent/cli.

From source (development)

pnpm is required for the workspace. The dev build is tsc-based and does not trigger the install-time bundle.

git clone https://github.com/klingaling/atlas-agent.git
cd atlas-agent
pnpm install && pnpm -r build && pnpm test   # full workspace test suite, all green
cd packages/cli && npm link                  # puts `atlas` on your PATH

Quickstart

cd your-repo
atlas init              # create .atlas/ (SQLite store, default configs; offers git hooks)
atlas sync              # one-shot index: files/symbols/edges/coupling + lazy embeddings (builtin, $0) into the store
atlas daemon start      # or keep it fresh in the background (atlasd, single writer; tasks ask it to yield)
atlas doctor            # toolchain + store + index stats + sync age + daemon health (+ --index: AC-E3 report)
atlas g status          # deterministic git palette (zero tokens, fuzzy verbs)
atlas g commit "..."    # commits run the Contradiction Sentinel on staged hunks first
atlas skills list       # skill catalog: class, wave, hot index, budgets
atlas polygraph         # mutation gate on your changed files: verdict + surviving-mutant diffs
atlas receipts          # machine-checked claims for the current diff (signed receipts.json)
atlas review 42         # address PR #42's review threads (staged stepper; --mode a needs T2)
atlas why src/x.ts:42   # Decision Blame: who/when/model/skill/cost wrote this line
atlas trust             # EARNED per-path tier heatmap + evidence (+ --evaluate runs the promotion pass now)
atlas compile           # Muscle Memory: compiled-skill status, candidates pending review, run-now
atlas do <name> [paths] # apply a compiled skill: zero tokens, <1s, preview + confirm
atlas bench mine        # mine merged PRs into YOUR private benchmark
atlas bench leaderboard # resolve rate + $/solve per cluster per model (post-cutoff split)
atlas coach tips        # the fixed coach-tip catalog (tips render post-run, max 1/session)
atlas canary status     # Drift Canaries: slice, baselines, active alerts/reroutes (off by default)
atlas canary run        # run tonight's canary slice now (SPENDS REAL MONEY; $0.40/night cap)
atlas canary alerts --share <id>  # write the drift alert card as a shareable markdown artifact
atlas logbook init      # Logbook: vault path + source toggles + redactions → ~/.atlas/logbook.json (worker-owned)
atlas logbook now       # synthesize this week's evidence-linked impact record (~$0.05/wk; honest skip without a key)
atlas recall --model <fp>  # Code Recalls: enumerate every hunk a defective fingerprint wrote, re-verify, repair, notice (previews + confirms first)
atlas recall list       # past + active recall campaigns (proposal/active/complete); resume <RN-id> continues an interrupted one

export ANTHROPIC_API_KEY=sk-ant-...          # or bind roles to a local model
atlas "explain what this repo does"          # run a task (mode: code, store-assembled context)
atlas run "fix the failing test" --json      # headless NDJSON for CI/scripts

Model roles (planner/editor/weak/judge) are bound in .atlas/models.yaml — point them at Anthropic or any OpenAI-compatible endpoint (vLLM, Ollama, llama.cpp) to run fully local.

Still to come: receipts as PR checks via the GitHub App, ledger events written automatically from the forge (merges/reverts land via the local scan today), python codemod support in Muscle Memory (@ast-grep/lang-python builds grammars at install time — rejected for v1 supply-chain reasons), shared .cskill bundles, the Code-Recall re-verify/repair execution seam (the receipts/Polygraph-over-sandbox + careful-mode bench-loop binding — enumeration, advisory verification, the manual command, and the resumable campaign ship today), the production auto-propose-from-drift rung (behind the 60-day-dogfood enablement gate, default off), and the dogfood numbers the §5.7.2 exit criteria demand (≥ 5 promoted skills, ≥ 15% compiled-share, the declining cost curve — measured over weeks of real use, not asserted).

Atlas keeps its per-repo state in .atlas/ (SQLite store at .atlas/store.db, task worktrees under .atlas/worktrees/) and user-level config in ~/.atlas/. Project memory lives in ATLAS.md, proposed by the agent and merged by humans.

Repository layout

packages/        TypeScript workspace packages (core, tools, store, protocol, ...)
prompts/         versioned system/plan/compact/review prompts
configs/         models.yaml, policies.yaml, tools.yaml
skills/          SKILL.md packs
evals/           Python eval sidecar (fixtures, SWE-bench adapter, adversarial)
docker/          sandbox images

Design principles (abridged)

• Deterministic first. Anything expressible as deterministic code (git plumbing, formatting, codemod application) executes as code, never as model reasoning.
• Verify, don't vibe. Anything learned from the agent's own trajectories must pass deterministic replay verification before activation.
• Content-hash everything. Every derived artifact is keyed by the hash of its source; staleness is detectable, never silent.
• Small trusted core. Four primitive tools, a system prompt under 1,200 tokens, and a core readable by one engineer in one sitting.

Contributing & security

See CONTRIBUTING.md (DCO sign-off required), SECURITY.md for the vulnerability disclosure path and sandbox profiles, and CODE_OF_CONDUCT.md. Coding agents working in this repo should read AGENTS.md.

License

Apache-2.0 — Copyright 2026 Jonathan Klinger and Atlas contributors.