lucapohl-angel/atlas_os

---

Why I Built This

Atlas exists because most AI coding CLIs are either:

• a single chatbot that loses project shape after a few prompts, or
• a process you have to assemble yourself before it can help you ship.

ATLAS·OS keeps the flow simple (atlas, describe the goal, ship) while keeping the engine serious: multi-agent orchestration, typed tools, hook-based safety, and persistent project state.

---

How It Compares

Atlas’s edge is not one isolated feature. It is the SDD pipeline, specialist agents, typed hooks/tools, MCP integration, and release workflow shipped as one terminal system.

---

Install

macOS

npx atlas-os@latest

# Or install globally
npm install -g atlas-os
atlas

Linux

npx atlas-os@latest

# Or install globally
npm install -g atlas-os
atlas

Atlas checks npm for newer atlas-os releases when the TUI opens. If your global install is behind, it shows a short dismissible update notice with:

npm install -g atlas-os@latest

Windows

WSL2 is recommended for the full Atlas experience.

# In an elevated PowerShell, one time:
wsl --install -d Ubuntu

Then inside Ubuntu:

sudo apt update && sudo apt install -y nodejs npm
npm install -g atlas-os
atlas

Native Windows can run the core CLI, but the shell tool expects POSIX commands. Use WSL2 if you want tool execution to match Linux/macOS behavior.

What Gets Installed

The package installs a small dispatcher plus the native binary for your platform. Other platform binaries are optional dependencies and are skipped automatically. If the native binary is unavailable, Atlas falls back to the bundled JS build on Node.js 20+.

VS Code Setup

The VS Code integrated terminal catches shortcuts like Ctrl+P before terminal apps can see them. Run this once if you use Atlas inside VS Code:

atlas vscode-setup
# then reload VS Code

Use --dry-run to preview the settings change, or --path for a non-default VS Code settings file.

VS Code Extension

The VS Code extension lives in packages/vscode and embeds the same @atlas/core engine as the terminal app. For local testing:

pnpm --filter atlas-os-vscode run package

Then install packages/vscode/dist/atlas-os-vscode.vsix with Extensions: Install from VSIX.... The extension reads ~/.atlas/config.yaml, layers explicit atlas.* VS Code settings on top, stores newly entered provider keys in VS Code SecretStorage, and opens ChatGPT / Codex sign-in through the Command Palette action Atlas: Sign in to ChatGPT / Codex.

Providers

The easiest path is inside the TUI:

atlas

Then open /config, choose a provider, and paste the key. Atlas stores it in ~/.atlas/config.yaml.

Environment variables also work:

export OPENROUTER_API_KEY=sk-or-...     # broad hosted-model catalog
export ANTHROPIC_API_KEY=sk-ant-...     # Anthropic direct
export OPENAI_API_KEY=sk-...            # OpenAI / ChatGPT direct
export OPENCODE_ZEN_API_KEY=oc-...      # OpenCode Zen BYO key
export OPENCODE_GO_API_KEY=oc-...       # OpenCode Go BYO key

Local OpenAI-compatible servers work too. Atlas auto-detects Ollama at http://localhost:11434/v1 and also works with LM Studio, vLLM, and llama.cpp servers that expose an OpenAI-compatible /v1 API.

Optional config:

defaultProvider: openrouter
defaultModel: anthropic/claude-sonnet-4.5
atlasMode: smart  # full | smart
providers:
  openrouter:
    apiKey: sk-or-...
  opencode:
    zen:
      apiKey: oc-...
    go:
      apiKey: oc-...

Hosted Atlas Modes

Open /config -> Atlas power mode to choose how Atlas presents the hosted provider cost posture.

The active mode is also shown in the TUI top bar: ATLAS POWER uses a bright red badge, and ATLAS SMART uses a bright green badge.

The model picker marks each catalog row with cache: yes (cheaper), cache: unknown, or cache: no. OpenRouter and OpenCode rows are sourced from live /models response cache-pricing fields, so DeepSeek, Kimi/Moonshot, Gemini, OpenAI, Anthropic, and other cache-priced routes are labeled from provider data. Prefer cache-capable routes when you want Full Atlas power with lower repeat-turn cost.

Project Bootstrap

Run this once per machine or project workspace:

atlas init

Then open Atlas:

atlas

New launches start on a fresh splash. Use /sessions or /resume when you want to manually reopen an older transcript.

---

How It Works

Greenfield

Use Atlas when you have an idea but no project shape yet.

1. Run atlas init.
2. Start atlas.
3. Describe the product or feature.
4. Atlas routes through planning, architecture, stories, implementation, QA, and release.

Typical flow:

idea only         -> Athena      (PM: clarify and write the PRD)
PRD ready         -> Prometheus  (architect: lock design and constraints)
stories needed    -> Hestia      (scrum master: split into buildable work)
story ready       -> Hercules    (dev: implement)
implementation    -> Nemesis     (QA: verify and file issues)
verified          -> Iris        (release: package and ship)

Brownfield

Use Atlas inside an existing repo when you want it to understand what is already there before changing code.

1. Open the repo.
2. Run atlas init if the built-in agents/skills are not installed yet.
3. Start atlas.
4. Use /onboard to map the codebase, reuse existing docs when available, and generate or update onboarding artifacts.
5. Ask for the change you want. Atlas should inspect the repo, plan narrowly, edit, then run the repo’s own verification gates.

Sessions are saved, but Atlas does not auto-open the last one. Reopen old work from /sessions when you need it.

---

Dev

Requirements:

• Node.js 20+
• pnpm 10.33.2 (npm install -g [email protected], or Corepack if your Node install provides it)

Local build:

git clone https://github.com/lucapohl-angel/ATLAS_OS.git
cd ATLAS_OS
pnpm install
pnpm --filter @atlas/core build
pnpm --filter atlas-os build
node packages/cli/dist/bin/atlas.js doctor

VS Code extension development has started in packages/vscode. It is a local extension host that embeds @atlas/core; it does not require a hosted Atlas backend.

pnpm --filter atlas-os-vscode build
pnpm --filter atlas-os-vscode test:run

Local Models While Developing

For local development, start an OpenAI-compatible server such as Ollama and pull a coding model:

ollama pull qwen2.5-coder:1.5b   # fastest low-RAM smoke model
ollama pull qwen2.5-coder:7b     # better local coding baseline

Then run Atlas and open /config -> Local models. The picker writes ~/.atlas/config.yaml and requires a restart after changing mode because the provider map is built at startup.

providers:
  local:
    baseUrl: http://localhost:11434/v1
    toolMode: hybrid  # lite | hybrid | full
    requestTimeoutMs: 300000

Hybrid mode advertises only the compact development allowlist: read_file, edit_file, write_file, terminal, git, todo, clarify, and open_question.

Full quality gate:

pnpm --filter @atlas/core build && \
pnpm --filter @atlas/core test:run && \
pnpm --filter atlas-os typecheck && \
pnpm --filter atlas-os test:run && \
pnpm --filter atlas-os build && \
pnpm --filter atlas-os-vscode typecheck && \
pnpm --filter atlas-os-vscode test:run && \
pnpm --filter atlas-os-vscode build && \
pnpm lint

Experienced-user tweaks:

• Providers: edit ~/.atlas/config.yaml, set provider env vars, or use /config in the TUI.
• Hosted cost mode: use /config -> Atlas power mode to switch between Atlas Power Full and Atlas Smart Mode. The top bar shows ATLAS POWER in bright red or ATLAS SMART in bright green, and model rows show cache support when known.
• Model switching: use /models, then type in the search field to filter long provider catalogs by model id or label.
• Local models: use /config -> Local models to choose Lite, Hybrid, or Full Atlas mode for Ollama / LM Studio / vLLM.
• MCP servers: use /mcps and /mcps add in the TUI, or edit ~/.atlas/config.yaml under mcp.servers.
• Agents: add user agents under ~/.atlas/agents//AGENT.md; project overrides can live in /.atlas/agents/.
• Skills: add skills under ~/.atlas/skills//SKILL.md; use /skills to inspect or toggle them.
• Models: use /model, /config, or defaultModel / fallbackModels in ~/.atlas/config.yaml.
• Sessions: use /sessions to resume, rename, start fresh, delete one saved transcript, select several for deletion, or delete all saved sessions with a confirmation prompt.

---

License

MIT.

---