█████╗ ████████╗ ██████╗  ███╗   ███╗
  ██╔══██╗╚══██╔══╝██╔═══██╗ ████╗ ████║
  ███████║   ██║   ██║   ██║ ██╔████╔██║
  ██╔══██║   ██║   ██║   ██║ ██║╚██╔╝██║
  ██║  ██║   ██║   ╚██████╔╝ ██║ ╚═╝ ██║
  ╚═╝  ╚═╝   ╚═╝    ╚═════╝  ╚═╝     ╚═╝

Every project starts here. Every lesson travels with you.

A project-starter template with cross-project memory, multi-tool AI support, and an opinionated dev workflow baked in.

---

Contents

Requirements · Quick start · Modes · Features · What is nucleus · Comparison · Compatibility · Docs · Roadmap

---

Requirements

Before you clone, make sure you have:

Tool	Required?	Why	Check
Node.js 18+	Required	atom's three CLIs (atom-setup, nucleus, model-race) are Node packages.	node --version
Git 2.5+	Required	Cloning atom, fresh git init after setup, model-race uses Git worktrees (Git ≥ 2.5).	git --version
npm (ships with Node)	Required	Used to install the three CLIs globally.	npm --version
GitHub CLI (gh)	Optional	Lets atom-setup auto-create a private GitHub repo, and nucleus init auto-wire its sync repo. Falls back gracefully if missing.	gh --version
Docker	Optional	Only needed if you pick a Docker tier in the wizard (Dockerfile / + compose / + devcontainer). Skip if you're shipping to Vercel/Netlify or building a CLI/mobile app.	docker --version
An AI CLI	Recommended	atom is built primarily for Claude Code. Codex CLI, Gemini CLI, Cursor, and GitHub Copilot also work via AGENTS.md.	claude --version

Note

The wizard runs a pre-flight check at startup and shows you what's installed before any questions. Missing required tools = it stops with a clear message; missing optional tools = some sections offer fallback paths.

Platform: macOS, Linux. Windows users need Git Bash, WSL, or similar for the shell-style commands; the Node CLIs themselves are cross-platform.

---

Quick start

curl -fsSL https://raw.githubusercontent.com/machbuilds/atom/main/install.sh | bash

Installs atom to ~/.atom/atom/ and puts five CLIs (atom, atom-setup, nucleus, learnings, model-race) on your PATH. One time, per machine.

Then, anywhere on your machine:

atom-setup new my-project
cd my-project

atom-setup new walks through up to 10 short sections (project name, stack, license, Docker, git, and so on), then writes a fresh project into ./my-project/: a main branch with one initial commit, your chosen scaffold and presets at the root, and a working tree ready to push. The Git section can create a GitHub repo via gh and push — no manual step needed. Your atom install at ~/.atom/atom/ stays untouched.

To keep atom itself up to date later, run atom upgrade.

Tip

Want zero questions? Run atom-setup new my-project --bare and you're done in under 5 seconds. All flags pass through (--minimal, --full, --dry-run, --resume, etc.).

Don't trust curl-pipe-bash? Install manually.

git clone https://github.com/machbuilds/atom.git ~/.atom/atom
cd ~/.atom/atom
for cli in bin/atom bin/atom-setup bin/nucleus bin/learnings bin/model-race; do
  (cd "$cli" && npm install && npm install -g .)
done

Same result, every step visible. See SECURITY.md for the curl-pipe trust model.

Upgrading from v0.1.x?

See docs/MIGRATING.md. One command (atom migrate-install) relocates a 0.1.x in-place install to the new ~/.atom/atom/ layout.

Note

If the install errors with EACCES, you need to either prefix the command with sudo or set up an npm prefix that doesn't need sudo. The installer points you at this if it fails.

---

Modes

Pick how much ceremony you want at clone time:

Mode	Time	Best for
atom-setup new <name> --bare	<5 sec	Power users. Sane defaults, no questions.
atom-setup new <name> --minimal	~30 sec	Most people. 5 essential questions, defaults for the rest.
atom-setup new <name>	~2 min	New users. All 10 sections with smart defaults you can press Enter through.
atom-setup new <name> --full	~5 min	Explicit control over every option.

Plus --resume (pick up an interrupted setup), --dry-run (preview without writing), --reinstall (force re-install all CLIs even if already on PATH), and --target <dir> (operate on a different directory).

---

What atom gives you

Feature	What it does
atom-setup	Interactive wizard (Node + clack). 4 modes: --bare / --minimal / default / --full. 10 sections cover project basics, stack, license, Docker tier, CI, git. Pre-flight detection, smart defaults, resumable state. Git section creates a GitHub repo via gh and pushes — no manual step.
atom upgrade	Keeps atom itself up to date. Detects your install, polls VERSION upstream, runs git pull --ff-only + re-installs all CLIs. atom upgrade --check polls without installing.
nucleus	Your memory — raw notes from every session, project-tagged, captured fast. Lives at ~/.atom/nucleus/. JSONL storage with versioned schema migrations, keyword + structured filter search. Optionally synced to your own private GitHub repo.
learnings	Your playbook — patterns you've decided to carry forward. Lives at ~/.atom/learnings/. Auto-copied into every new project you bootstrap (filtered by stack tags). Optionally synced to your own private GitHub repo.
model-race	Parallel AI model comparison via Git worktrees. Race the same spec through claude/codex/gemini, score with weighted metrics, optional LLM judge, merge the winner.
Docker, optional	Four tiers: None / Dockerfile / + compose / + devcontainer. Smart-defaulted from your stack. Production-grade out of the box (multi-stage, non-root, healthcheck, multi-arch CI).
Multi-AI tool support	AGENTS.md is the canonical spec; CLAUDE.md / GEMINI.md / .cursorrules / .github/copilot-instructions.md are forwarders. Claude, Codex CLI, Gemini CLI, Cursor, and Copilot all read the same instructions.
Stack presets	extras/ ships 6 opinionated setups: Next.js + Railway, Python / FastAPI, Swift / Vapor, Rust / Axum, Go CLI / Cobra, TypeScript library. Each ships a manifest with pinned versions, a hello-world entry, a stack-tuned Dockerfile (web only), seed learnings, and a Quick Start spliced into the project README.
Workflow integrations	Optional Spec Kit + Task Master, GSD skills. Each opt-in via the wizard.

---

What is nucleus?

atom ships with two layers of cross-project knowledge. They're easy to confuse, so the distinction matters:

	nucleus	learnings
What it is	Your memory of every session	Your playbook of patterns to carry forward
Bar to capture	Low — "worth noting"	High — "worth carrying into every future project"
Granularity	Raw, project-tagged	Curated, generalized, per-type
Lives where	~/.atom/nucleus/	~/.atom/learnings/
Auto-copied to new projects?	No	Yes (filtered by stack tags)
Optional sync	Your own private GitHub repo	Your own private GitHub repo (separate from nucleus)

Both are 100% yours. Nothing leaves your machine without your explicit action. atom is the system; the content is yours.

Why it exists

Code can be rewritten. The lessons you learned writing it are harder to recover. They sit in your head, get half-remembered, and quietly disappear when you start the next project. Most coding sessions teach you something — a pitfall, a pattern, an architecture decision with rationale. Without a capture system, that learning evaporates the moment the session ends.

nucleus catches those lessons mid-session, low bar, project-tagged. learnings is the curated subset you've decided to carry forward — auto-copied into every new project you bootstrap. Together they give you code you can rewrite plus knowledge you can't.

The flow

       session
          │
          ▼  nucleus add  (raw, project-tagged, low bar)
   ~/.atom/nucleus/projects/<slug>/learnings.jsonl
          │
          ▼  nucleus promote <id>  (passes generalization test)
   ~/.atom/learnings/<type>/<key>.md  (your local playbook)
          │
          ▼  atom-setup new project  (filtered by stack)
   <new-project>/learnings/<type>/<key>.md  (carried forward)

Capture (first arrow) is often Claude-led but always you-in-the-loop. When you work with Claude Code in your project, Claude is instructed — via AGENTS.md and .claude/skills/nucleus/ — to run nucleus add at natural moments (after a non-obvious bug fix, a design decision with rationale, on /clear). With other AI tools, or when you'd rather drive yourself, you run nucleus add manually. There is no background daemon; capture happens when something in your session tells it to.

Promote (second arrow) is always you. nucleus promote <id> opens $EDITOR so you can refine the draft before it lands in your playbook. Graduation needs human judgment — what generalizes, what stays project-specific.

Carry forward (third arrow) runs every time you bootstrap a project from atom — your playbook follows you, filtered by stack tags.

If captures pile up unpromoted, run nucleus review for a 30-second triage of what's worth graduating.

Capture modes

Mode	What happens
claude-managed (default)	When you work with Claude Code, Claude is instructed to run nucleus add at natural session boundaries (after a fix, decision, or on /clear). Lowest friction if Claude is your daily driver.
manual	Claude (or you) decides; you run nucleus add yourself. For users who want full control or aren't using Claude.
auto-timer	Reserved — wizard collects the interval but no background daemon ships yet. Behaves like claude-managed in practice.

Picked at atom-setup time, configurable later via ~/.atom/nucleus/config.json.

---

How it compares

	atom	create-next-app	cookiecutter	degit
Stack-agnostic	yes	no (Next.js only)	yes	yes
Interactive wizard	yes (4 modes)	yes	yes	no
Stack presets	yes	partial	yes	no
AI-tool integration	yes (multi-tool via AGENTS.md)	no	no	no
Cross-project memory + playbook	yes (nucleus + learnings)	no	no	no
Parallel-model workflow	yes (model-race)	no	no	no
Constitution / principles	yes	no	no	no
Production Docker defaults	yes (4 tiers, opt-in)	partial	no	no
Multi-arch CI workflow	yes (amd64 + arm64)	no	no	no

degit is the closest analog for "just give me the files." atom does more: it accumulates real practice (presets, learnings, AI-tool wiring) and it grows with your work via nucleus.

---

Tool compatibility

Note

atom is built primarily for Claude Code. The richest experience — slash commands, the nucleus skill, deep tooling integration — assumes you're working in Claude Code. If you use Claude, everything just works.

Other AI tools work, with caveats. Codex CLI (GPT), Gemini CLI, Cursor, and GitHub Copilot all read AGENTS.md (or a forwarder pointing to it). The full project instructions, including how to use nucleus and model-race, live in AGENTS.md. Every AI tool that lands in this project knows nucleus exists, when to search it, and when to capture.

What other tools miss today:

• Skill auto-invocation. Claude has a Skill tool that activates the nucleus skill at session boundaries. Other tools have to be prompted to remember nucleus, or you call nucleus add manually.
• Slash commands. /gsd-new-project, /nucleus-promote, etc. are Claude-only conventions today.

Roadmap. As Codex CLI, Gemini CLI, and others grow richer integration surfaces (skill systems, slash command equivalents), atom will add tool-specific wrappers that delegate to AGENTS.md for content. The plan is to never duplicate — one source of truth, multiple read paths.

---

What's inside (full file tree)

atom/
├── AGENTS.md          Canonical AI tooling instructions (every tool reads this)
├── CLAUDE.md          Forwarder → AGENTS.md (Claude Code auto-load)
├── INSTALL.md         Per-project tooling setup
├── CONTRIBUTING.md    How to add new learnings to atom
│
├── docs/              Read these before starting any new project
│   ├── VOICE.md
│   ├── WORKFLOW.md
│   ├── PATTERNS.md
│   ├── LESSONS_LEARNED.md
│   ├── LEARNINGS_TAXONOMY.md
│   ├── HOW_TO_WRITE_CONSTITUTION.md
│   ├── HOW_TO_PICK_DEPLOY_TARGET.md
│   ├── HOW_TO_DESIGN.md
│   ├── planning/      Per-feature build plans
│   └── INBOX.md       Raw capture before generalising
│
├── scaffold/          Promoted to project root by atom-setup
│   ├── AGENTS.md      Canonical instructions skeleton — fill <TODO> markers
│   ├── CLAUDE.md      Forwarder → AGENTS.md
│   ├── GEMINI.md      Forwarder → AGENTS.md
│   ├── .cursorrules   Forwarder → AGENTS.md
│   ├── .gitignore
│   ├── .github/       CI workflows + PR template + copilot-instructions.md
│   ├── .claude/       Claude-specific skills (nucleus + agent skills)
│   └── package.json   Baseline scripts
│
├── bin/               Global CLIs (install once per machine)
│   ├── atom/          Top-level help dispatcher (`atom --help`)
│   ├── atom-setup/    Interactive wizard
│   ├── nucleus/       Your session memory CLI
│   ├── learnings/     Your playbook CLI
│   └── model-race/    Parallel AI model comparison via Git worktrees
│
├── scripts/           Maintenance scripts (e.g. copy-learnings.mjs, test-atom-setup.sh)
│
└── extras/            Opt-in stack presets, copied based on user choice
    ├── docker/                Dockerfile, compose, devcontainer, CI
    ├── web/nextjs-railway/    Next.js + Railway preset (incl. Dockerfile)
    ├── web/python-fastapi/    Python + FastAPI preset (v0.2)
    ├── web/swift-vapor/       Swift + Vapor preset (v0.2)
    ├── web/rust-axum/         Rust + Axum preset (v0.2)
    ├── cli/go-cobra/          Go CLI + Cobra preset (v0.2)
    ├── lib/typescript-library/ TypeScript library starter (v0.2)
    ├── ai/                    (placeholder — v0.3)
    └── mobile/                (placeholder — v0.3)

The 10 wizard sections

Step 2 — stack preset picker (18 options, 6 with opinionated presets)

Step 3 — nucleus capture mode (prior answers stay on screen as context)

1. Project basics — name, description, visibility, multi-agent y/n
2. Stack & deploy — primary stack, deploy target. Drives presets.
3. nucleus — enable, capture mode (claude-managed / auto-timer / manual)
4. Memory stack — mem0 / Multica / Chrome DevTools MCP
5. Workflow tooling — Spec Kit + Task Master, GSD, model-race
6. Docker — None / Dockerfile / + compose / + devcontainer (smart-defaulted from stack)
7. License — MIT / Apache-2.0 / GPL-3.0 / Proprietary / None
8. CI/CD — auto-deploy on push to main (only asked if deploy target concrete)
9. Constitution — generate starter constitution after setup
10. Git — fresh git init, then: create a new GitHub repo via gh (with visibility choice + optional push) / add an existing remote / skip

--bare skips all of these and uses sane defaults. --minimal asks only the essentials (1, 2, 3, 7, 10).

Polish features (every wizard run)

Summary screen (above) and the dry-run changes panel (below) — together in one frame

• Pre-flight detection. Checklist of git, node, gh, docker, gum availability at the top of every run.
• Smart defaults. Project name from cwd. Author/email from git config. GitHub user from gh auth status. Year from current date.
• Final confirmation. Summary screen BEFORE writing any files. Press Enter to confirm or N to bail.
• Resume support. Cancel mid-wizard, re-run with --resume to pick up where you left off. State at .atom-setup-state.json (gitignored). Secrets stripped before write.
• Idempotent. Re-runnable. Running again does not break partial config; you can re-enable features you previously declined.
• Dry run. --dry-run shows everything that would change without writing a single file.

---

Documentation

• AGENTS.md — what every AI tool reads when it lands in this repo
• CONTRIBUTING.md — how to add learnings back to atom (generalization test, two-stage workflow)
• bin/atom-setup/README.md — wizard reference
• bin/nucleus/README.md — nucleus CLI reference, schema, capture modes
• bin/model-race/README.md — race lifecycle, config, scoring
• docs/planning/ — per-feature build plans (decisions + rationale)
• docs/LEARNINGS_TAXONOMY.md — canonical applies_to vocabulary
• extras/docker/README.md — Docker tier mapping, stack adaptation patterns
• INSTALL.md — per-project tooling setup (mem0, Multica, etc.)

---

Roadmap

Tip

atom is actively developed. Everything in the Features table works today. The roadmap below is what's shipping next.

v0.2 (in progress)

Shipped so far:

• atom upgrade — keep atom up to date with one command
• ./atom-setup --reinstall flag — force re-install stale globals
• nucleus migrate — versioned schema migrations for JSONL files, auto-triggered
• Live gh repo create in wizard §10 — creates GitHub repo and pushes; non-fatal on failure
• 5 new stack presets: Python/FastAPI, Swift/Vapor, Rust/Axum, Go CLI/Cobra, TypeScript library
• Inline constitution generation in the wizard (§9) — populated draft from §1+§2 answers
• nucleus review + honest capture framing; backlog age nudge
• ~/.atom/atom/ canonical install + atom-setup new <name> verb
• install.sh curl one-liner + atom migrate-install for 0.1.x users

Coming next in v0.2:

• bin/atom-update-check + snooze (gstack pattern)

v1.0

• First public release. Polished docs, demo screencast, full stack-preset coverage.

Beyond

• Tool-specific wrappers as Codex/Gemini/Cursor gain skill-system equivalents
• Plugin system for custom presets
• nucleus web UI for cross-project learning browsing

---

Contributing

atom evolves with every project that's shipped from it. The flow:

1. During the project, capture learnings via nucleus add (or docs/INBOX.md if you prefer manual).
2. At the end of the project, run nucleus promote <id> for entries that pass the generalization test. Files land in your local playbook at ~/.atom/learnings/<type>/<slug>.md and ride forward into every new project you bootstrap.
3. Periodically, refine those into prose for docs/LESSONS_LEARNED.md.

See CONTRIBUTING.md for the rules and the generalization test.

---

License

MIT.