Atom

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

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.

[](LICENSE) [](https://nodejs.org) [](docs/planning/) [](#tool-compatibility)

---

Contents

[Requirements](#requirements) · [Quick start](#quick-start) · [Modes](#modes) · [Features](#what-atom-gives-you) · [What is nucleus](#what-is-nucleus) · [Comparison](#how-it-compares) · [Compatibility](#tool-compatibility) · [Docs](#documentation) · [Roadmap](#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.).

> [!TIP] > Live in Claude Code? Install puts an /atom-new skill on your machine. Type /atom-new in any session. Claude walks you through the same bootstrap conversationally, no trip back to the terminal. The wizard above is still there when you want the fast, no-questions path.

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](SECURITY.md) for the curl-pipe trust model.

Upgrading from v0.1.x?

See [docs/MIGRATING.md](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 --bare | --minimal | ~30 sec | Most people. 5 essential questions, defaults for the rest. | | atom-setup new | ~2 min | New users. All 10 sections with smart defaults you can press Enter through. | | atom-setup new --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 (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. | | /atom-new skill | Bootstrap a new project from inside Claude Code. Type /atom-new in any session and Claude drives the same wizard conversationally, no terminal round-trip. Install symlinks it into ~/.claude/skills/; atom upgrade's git pull refreshes it for free. | | 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//learnings.jsonl
          │
          ▼  nucleus promote   (passes generalization test)
   ~/.atom/learnings//.md  (your local playbook)
          │
          ▼  atom-setup new project  (filtered by stack)
   /learnings//.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 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  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
│
├── skills/            Global Claude Code skills, symlinked into ~/.claude/skills/
│   └── atom-new/      `/atom-new`. Bootstrap a project conversationally
│
├── 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

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: machbuilds
• Source: machbuilds/atom
• License: MIT

Install and usage instructions live in the source repository linked above.