_{The ATLAS TUI live, 10× sped up, running the V3 pipeline on a file creation.}

A.T.L.A.S.

Adaptive Test-time Learning and Autonomous Specialization

🌎 What is ATLAS?

ATLAS is a local coding agent that brings frontier-style reasoning and verification to compact open models. It puts more intelligence in the system around the model (planning, candidate generation, quality scoring, sandboxed testing, and repair) so smaller models can tackle real software work entirely on your own hardware, without a hosted API or per-token fees.

💡 Why ATLAS?

• Get more from smaller models. ATLAS adds planning, candidate selection, verification, and repair around the model instead of depending on a single generation.
• Verify before accepting. Generated code can be compiled, tested, and corrected inside an isolated execution environment.
• Spend compute where it matters. Straightforward edits take a shorter path, while harder tasks receive more candidates, reasoning, and validation.
• Run your own model. Use a compatible GGUF model on NVIDIA, AMD, Apple Silicon, Vulkan, or CPU-supported hardware.
• Keep control local. ATLAS does not intentionally upload your repository or prompts to a hosted model or ATLAS-operated service. Sandbox commands have outbound network access by default; set ATLAS_SANDBOX_NET_INTERNAL=true to disable it.
• Own the full stack. ATLAS is open source and self-hosted. It requires no hosted model or third-party model-provider API key; a local per-installation service token authenticates ATLAS services.

📰 Latest News

• 2026-07-06 - V3.1.3 "Maia" released - production-platform pass: staged upgrade/rollback with auto-restore, SQLite state store (no more Redis), signed artifact manifests, structured logs + correlation IDs, interactive permissions, session resume, and two adversarial bug-fix sweeps
• 2026-06-17 - V3.1.2 "Maia" released - broader hardware reach (ROCm / Metal / Vulkan), bring-your-own-model Lens + ASA training, in-the-loop lens retraining from your own workloads, and an agent-reliability pass
• 2026-05-12 - V3.1.0 "Maia" released - native Bubbletea TUI, one-command bootstrap, streaming Lens + ASA activation steering, AST-aware surgical edits
• 2026-03-26 - Hacker News front page - 489 points, 285 comments
• 2026-03-05 - V3.0 released - 74.6% LiveCodeBench pass@1-v(k=3) on frozen Qwen3-14B (pass@1 with k=3 generated candidates, Lens selection, and repair - not single-generation pass@1; methodology)
• 2026-02-18 - V2.0 released - benchmark infrastructure, HumanEval/MBPP/LiveCodeBench/GPQA/SciCode evaluation suite

⭐ Star History

_{Updated weekly (Mondays, via GitHub Actions).}

🧱 What ATLAS Does

1. atlas-tui - native Bubbletea terminal UI; the canonical chat client. Type atlas in any project directory to launch it.

   • Live pipeline view - watch V3 stages stream in a side pane
   • Slash commands - /add, /diff, /commit, /run for local file context and shell-out
   • Input modes - chat, !bash, and /slash with a hint dropdown

2. atlas-proxy - Go agent loop that orchestrates the system.

   • Tool-call routing - classifies file operations by complexity tier
   • Grammar enforcement - GBNF schemas strongly steer output toward the expected JSON shapes, with proxy-side recovery for malformed or truncated output
   • BiasBusters - four composed mitigations (descriptions, grammar bans, system notes, ASA steering) that push the model toward structural_edit for structural code edits
   • Safety limits - turn caps, token budgets, timeouts

3. V3 Pipeline - multi-phase code generation; turns a single prompt into a verified candidate.

   • PlanSearch - constraint-driven structured planning
   • DivSampling - diverse candidates across temperature and strategy
   • Budget Forcing - per-phase thinking-token allocation
   • PR-CoT Repair - self-generated test cases for iterative fixes
   • Refinement Loops - sandbox verify and correct, then repeat

4. Geometric Lens - energy-based scoring over the model's own embeddings, no external oracle. (What is a "Geometric Lens"?)

   • C(x) Cost Field - model-hidden-dim→512→128→1 MLP that scores candidate quality
   • G(x) Quality Prediction - XGBoost ensemble used for selection
   • Per-step scoring - per-token C(x)/G(x) scoring of writes, with per-model calibrated thresholds driving interventions
   • Pattern cache - lessons from previous sessions, injected into new runs

5. Sandbox - isolated execution for build verification.

   • Multi-language execution: Python, Rust, Go, C, Shell, others
   • Compilation and linting before scoring
   • Runs both generated and existing test suites

6. llama-server - local LLM inference on one consumer GPU.

   • GPU-accelerated quantized inference (Q6_K / Q4_K_M) - NVIDIA CUDA, AMD ROCm, Apple Metal (macOS hybrid), and Vulkan; Intel SYCL on the roadmap
   • Grammar-constrained decoding at the token level
   • Self-embeddings, so the lens doesn't need a second model

Full documentation (setup, architecture, configuration, troubleshooting, benchmark reports, and the research behind each component) lives in the docs/ directory.

🚀 Get Started

One-shot install:

curl -fsSL https://raw.githubusercontent.com/itigges22/ATLAS/main/scripts/atlas-bootstrap.sh | bash

Prefer not to pipe a moving script into bash? Same installer, two more careful ways to run it:

# Pinned to a release: script, checkout, and images all at the signed tag
curl -fsSL https://raw.githubusercontent.com/itigges22/ATLAS/v3.1.3/scripts/atlas-bootstrap.sh \
  | ATLAS_BOOTSTRAP_REF=v3.1.3 bash

# Review before running
curl -fsSL -o atlas-bootstrap.sh https://raw.githubusercontent.com/itigges22/ATLAS/main/scripts/atlas-bootstrap.sh
less atlas-bootstrap.sh
bash atlas-bootstrap.sh

The script detects your distro (Ubuntu, Debian, RHEL, Fedora, Rocky, Alma) and your GPU vendor (NVIDIA → nvidia-container-toolkit; AMD → ROCm device passthrough), installs the appropriate runtime, downloads the model weights, builds the ASA steering vector, and starts the stack. Expect 10-30 minutes; the model download is the bottleneck.

Then in any project directory, run atlas.

Requirements

Apple Silicon runs natively through the macOS hybrid Metal path (native llama-server + Docker for the rest - see SETUP_MACOS.md); Intel Arc (SYCL) is on the roadmap. For the manual install path (Docker Compose, bare-metal, K3s) and the full set of bootstrap flags, see SETUP.md.

⚠️ Known Limitations

• Linux Docker stack, plus a native macOS path. NVIDIA (Supported), AMD ROCm (Community-tested), and Vulkan (Preview) Docker paths exist today; Apple Silicon (Supported) runs via the native macOS hybrid Metal path (#32). Intel Arc / SYCL is Roadmap. Level definitions: SUPPORT_MATRIX.md.
• Current registry models are not formally benchmarked yet. The canonical 74.6% LiveCodeBench score is from the frozen 14B reference build. New model-specific numbers are tracked in #28. The reference methodology and ablations live in docs/reports/V3_ABLATION_STUDY.md; raw traces are on HuggingFace.
• Complex feature additions can be inconsistent. Compact models sometimes spend agent turns exploring an unfamiliar codebase before writing code. Reliability has improved through the V3.1.2 agent-reliability pass; fresh model-specific numbers are tracked in #28.
• Grammar-constrained decoding is slow. Around 51 tok/s on llama-server.

🗺️ Roadmap

V3.1.3 "Maia" - Current release. Production-platform pass on top of V3.1.2: staged atlas upgrade/rollback with automatic restore, SQLite state store replacing Redis (ADR 0007), signed artifact manifests, structured JSON logs with cross-service correlation IDs, interactive permission prompts, session resume, typed config validation/migration, and two adversarial bug-fix sweeps (33 confirmed fixes).

V3.1.2 "Maia" - Broader hardware reach, bring-your-own-model training, and an agent-reliability pass on top of the V3.1.0 base (TUI, one-command install, streaming Lens + ASA).

• Hardware reach: AMD ROCm via llama.cpp incl. RDNA4 / RX 9070 (gfx1200/gfx1201) (#26); Apple Silicon native macOS hybrid Metal path (#32, see SETUP_MACOS.md); Vulkan universal fallback covering AMD / Intel / Snapdragon / Apple-via-MoltenVK / CPU (#114).
• Bring-your-own-model: local Lens training pipeline (atlas lens build / retrain, #100) and ASA per-model calibration parity (atlas asa check/build/publish, #113) - train Lens + ASA artifacts for additional GGUFs, with per-model operating thresholds that ship with the lens.
• In-the-loop lens training: rate passes in the TUI (/good · /bad · /review · /deny) → collected, weighted samples → atlas lens retrain on your own workloads.
• Agent reliability: tool-result visibility fix, read-dedup, traceback → directed-edit, move_file, pip-install / case-mismatch steers, sandbox shell policy + host-sized cgroup limits.
• Structural call-graph reasoning (#39 / #125, thanks @yogthos); ARCHITECTURE.md translated to zh-CN / ja / ko (#25).

V3.2 - Next milestone: deeper code reasoning.

• RPG-style architecture-first planning was built (#120), A/B-measured, and removed: no improvement on the reference model at ~10x planning latency. #148 is the record; the design study is docs/reports/RPG_WAVELET_PLANNING_V3_2.md.
• Structural code reasoning (tail) - deepen the shipped call-graph layer (#39).
• Reasoning with sampling - efficiency and quality gains (#9).
• Deferred infra: automated HuggingFace submission pipeline (#102); ROCm on K3s / Kubernetes; formal registry-model benchmarks - LiveCodeBench, GPQA Diamond, SciCode (#28).

Backlog / help wanted

• Hardware: ARM64 multi-arch builds (#115), multi-GPU for larger models (#34), Intel oneAPI / SYCL (#27).
• Tooling: VS Code / JetBrains extension (#35).
• Sandbox languages: Java / Kotlin (#29), Ruby / PHP (#30).
• Architecture: model-agnostic platform (#66).

❤️ Support ATLAS

ATLAS is built by a single college student in his free time on a single consumer GPU (the story behind ATLAS). If the project has been useful to you and you want to help keep it sustainable, please consider sponsoring on GitHub.

Sponsorship directly funds:

• Compute & hardware - more GPUs for faster benchmark iteration, access to architectures the maintainer can't afford (AMD ROCm, higher VRAM cards, cloud rentals for larger-model experiments).
• Contributor bounties - meaningful compensation for external contributors who put real time into substantive PRs, so ATLAS can grow faster than a single-person pace allows.
• Research - continued academic engagement around the architecture, from future workshop and conference submissions to paper writing and collaborations that validate and extend the approach.
• Community - continued support for the community and platforms ATLAS runs on, including documentation, user-facing channels, and educational content that help ATLAS reach more developers and better serve the ones already using it.

Every sponsor is credited in the release notes of the version they helped fund.

🤝 Contributing

ATLAS is developed in the open and welcomes contributors and core maintainers. Bug fixes, accelerator support, and larger subsystem work are all welcome.

Found a bug or hit a wall? Open an issue - you don't need to submit a fix. Bug reports and feedback help just as much as code.

See CONTRIBUTING.md for guidelines and the repository map for an overview of the codebase layout.

📄 License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).