software-engineer-ai-agent-atlas

SWE-ATLAS: an AI software engineer agent for Claude Code

Turn Claude Code into a senior software engineer that carries your projects end to end: from intent, to prototype, to build, to test, to deploy, and remembers each project across sessions without rescanning the repo.

npx swe-atlas@latest new-project                 # in your current repo
npx swe-atlas@latest new-project my-workspace    # or a new workspace for many projects

One command. Works on macOS, Linux, and Windows.

SWE-ATLAS is an open-source Claude Code template and AI coding agent setup: skills, subagents, slash commands, hooks, and engineering conventions that make Claude Code behave like a senior engineer who has shipped before. It explores before it builds (wireframes, clickable prototypes, visual plans), keeps a short memory per project, handles API keys without ever showing them in chat, talks to Postgres through psql, and writes the deploy runbook. Then it hands execution to Claude Code's own plan mode, /goal, and workflows.

It ships in three CLAUDE.md flavors, so you choose how much of the wheel to hand over:

• Vanilla: minimal footprint, no ATLAS identity.
• Collaborative (default): the full senior-engineer identity with a review-and-commit loop; you stay in the driver's seat.
• Autonomous: the approval loop removed and free-will wired in, the skill that lets ATLAS decide for itself on the high-stakes forks: hold real alternatives open, ground each in evidence, refute the winner, then log the call in docs/decision_logs/. That's what lets it one-shot an app and run unattended without going off the rails.

And it runs in three workspace modes: inside one repo, around one project with several repos, or as one workspace holding many projects. You can switch later with /atlas:mode.

Claude Code already has the engine. ATLAS helps you decide what to build.

Claude Code plans before it edits, works toward a goal across turns, runs autonomously with safety checks, reviews and simplifies code, and orchestrates fleets of subagents, natively:

Kick off a workflow: describe the task and ask for a workflow in your own words, or include the keyword ultracode, and Claude writes one for it. Want it always on? Set /effort ultracode and Claude plans a workflow for every substantive task in the session. (How workflows work →)

That is the execution loop, and it keeps getting better, so ATLAS doesn't rebuild it. This release removed the ATLAS agents that the box now covers (explorer, architect, reviewer, simplifier).

What Claude Code still won't do for you: decide what's worth building, prove the shape works before you spend tokens generating it, remember ten projects across sessions, keep your keys out of the transcript, and carry a project all the way to production. That part is ATLAS.

Auto mode and dynamic workflows are in research preview at the time of writing; plan mode and /goal are generally available.

Why not another spec framework

The popular answer to "make the AI build the right thing" has been to bolt a process framework onto the model: Spec-Driven Development (SDD) and the agent frameworks in the same vein (spec-kit, BMAD, Get Shit Done, and the rest). Write exhaustive specifications first, then generate the code from them. A constitution, a spec, a plan, a task breakdown: five to seven Markdown files and a multi-phase pipeline, most of it produced before a single screen has been seen.

Four things go wrong:

• You plan before you've learned. Most of the requirements and task breakdown are guesses made before anyone has seen the thing work. You pay full freight to formalize guesses, build to them task by task, and find out at the end it isn't what anyone pictured.
• Text leaves room to disagree. You and the model can read the same paragraph and picture two different screens, and the gap only surfaces once the code exists. Prose is the wrong medium for "do we mean the same thing?"
• Markdown drifts. Keeping spec.md, plan.md, and tasks.md consistent with each other and with the code is its own tax, and plain .md can't render the wireframe, flow, or matrix it's straining to describe.
• The loop is already native. Spec → plan → tasks → implement is what plan mode, /goal, and workflows now do on their own. Wrapping a framework around the model to make it loop reinvents what ships in the box, at a heavy token premium.

ATLAS takes the opposite bet: do the minimum upfront thinking that actually de-risks the build, make it cheap, fast, and visual, so a human and the model can look at the same thing and agree before a line is written, then hand a clean artifact to the native loop.

What ATLAS does instead

1. Explore before you commit

Cheap, throwaway-friendly artifacts that let you see the thing before generating code for it:

• /brainstorm:wireframe: a low-fi wireframe as one self-contained HTML file
• /brainstorm:prototype: a clickable, multi-screen React prototype
• /design:create-design-md: three real design variants you compare in a browser, then lock as the project's DESIGN.md rule
• /plan:visual: any non-UI change (refactor, migration, architecture call) as a visual HTML plan with diagrams, a change map, and decision matrices

2. Clarify only the essentials

/plan:create-phase runs the product interview from super-product-owner: one question at a time, only what's still open, stopping as soon as a one-page brief can be written. The output is a wireframe-first phase.html with acceptance checks instead of user stories. No constitution, no task ledger.

3. Remember every project, cheaply

Each project gets a small memory that a fresh session reads in a few thousand tokens instead of scanning the repo:

Memory grows with the project: a new project starts with the map, the status, and an .env.example, and folders appear when the first decision or phase does. The stage line sets the engineering bar, so a weekend toy doesn't get production ceremony and production work doesn't get toy shortcuts. /atlas:project open loads a project at the start of a session; /atlas:project wrap updates its state at the end.

4. Bring senior judgment to every turn

A persistent engineering identity (principles, roles, conventions) plus skills that load when the work calls for them. At the center is free-will: on a medium-to-high-stakes fork (a stack, a schema, deprecating something others depend on) it refuses the first plausible answer, holds real alternatives open, grounds each in evidence, simulates the blast radius, tries to refute the winner, then logs the decision. It fires autonomously on mechanical triggers, like a fix that failed twice, a new dependency, or a migration. adversarial-review then attacks what was built: clean-context reviewers with opposing mandates, and every finding reproduced against the running app before anyone believes it.

5. Carry it to production

/deploy:plan writes the project's DEPLOY.md runbook, /deploy:check gates the release (tests, missing secrets, migration safety, build), and /deploy:run ships it: through your existing CI/CD pipeline (PR, green checks, merge with your yes), through the provider's CLI, or as exact steps you run. Then it health-checks, smoke-tests the live URL, and logs the deploy. Provider notes ship for Coolify, Vercel, Netlify, Fly.io, Railway, and Docker Compose over SSH. Production always asks first.

Workspace modes

my-workspace/                 (multi mode)
├── CLAUDE.md                 identity + "read index.md, then the project's map"
├── index.md                  | Project | One line | Stage | Stack | Path | Deploy | Status |
├── general/                  scratch, experiments, one-offs
└── projects/
    ├── shop/
    │   ├── CLAUDE.md  STATUS.md  DEPLOY.md  .env.example
    │   ├── docs/  misc/
    │   └── repos/web/  repos/api/      (their own git, ignored by the workspace)
    └── notes/ ...

Several Claude Code sessions can work on different projects in one workspace at the same time. There is no global "active project": each session carries its own. Browser sessions are named per project, Playwright MCP runs isolated, databases are registered per project, and every artifact (test runs, screenshots, prototypes) lands under its own project. Two sessions on the same project use git worktrees.

Switching modes. /atlas:mode multi (or project, repo) reads the workspace, prints the full migration plan (every move, every file created), and changes nothing until you say yes. Tracked files move with git mv so history follows. It warns before moving folders that hold their own git repo (virtualenvs, dev servers, and Claude Code's per-folder session history don't survive a move) and prefers adopting a repo where it sits.

Getting started

Quick start

# Inside an existing repo: repo mode is detected
cd your-project
npx swe-atlas@latest new-project

# A new workspace for many projects: multi mode is the default
npx swe-atlas@latest new-project my-workspace

The CLI asks for the CLAUDE.md flavor, your name, the workspace mode (and the project's name and stage), browser automation (Playwright MCP or Playwright CLI), which skills to install (an interactive checkbox: ↑/↓ move, space toggles, a selects all), when to auto-compact, and an optional advisor model. Then it copies everything from this repo as the single source of truth. Piped input works too: the skills picker falls back to comma-separated numbers (* = all) when stdin isn't a terminal.

Pick your CLAUDE.md flavor