ATMOS

General Build Process

The everyday loop from workspace creation to a reviewed change.

In Atmos, building usually means turning an idea into a running, reviewed change inside a workspace.

The default loop is simple: create a workspace, let an agent or human make changes, review the diff, run the app, test it, and clean up when the task is done.

Overview

Most tasks follow this order: create a workspace, prepare the project, build with an agent or by hand, review the change, run it, test it, ship it, then archive the workspace.

1. Open or create a workspace

Follow Project & Workspace Manager:

  • Quick New Workspace for speed.
  • New Workspace Composer (⌘N) when you have prompts, GitHub links, or images.
  • Kanban when triaging many tasks.
  • Groups when related projects should sit under one named cluster.

Wait for Workspace Setup Progress to finish before you start editing or running agents.

2. Run the setup script

If the project defines a Setup Script, it runs automatically during creation. Typical jobs:

  • Install project dependencies.
  • Copy example settings or sync secrets.
  • Generate local config.

Steps shown in the UI include Create Workspace, Run Setup Script, and Ready. You can proceed when blocking steps complete.

Configure scripts under project ⋯ → Workspace Scripts.

3. Build with a Code Agent in the terminal

  1. Open the workspace Terminal tab.
  2. Start your coding agent in that shell (including Grok Build and other built-ins from Agent Select).
  3. Or use the global agent chat panel for focused tasks that do not need a full terminal flow.
  4. Paste structured context into the composer when available — it appears as context chips (code, diff, browser element, terminal selection, and more).
  5. For tangents without polluting the main agent, use /side. For a full parallel pane with the same context, use /spawn. See Terminal Side Chat.

Give the agent a clear goal, files, and constraints. Let it iterate with tools while you watch output in the same pane.

4. Review code (optional)

Before you trust the diff:

  1. Open the right sidebar Review tab.
  2. Create a Review Session.
  3. Comment on diffs or run Agent Review with a review skill.
  4. Use Fix to send open comments back to the Code Agent.

See Code Review in Atmos for the full loop.

5. Manual adjustments (optional)

Use the built-in editor for small fixes, or your primary IDE for large refactors. Re-run tests in the terminal after edits.

6. Run and preview

  1. Configure a Run Script on the project if you have not already.
  2. In the workspace, open the right sidebar Run / Preview tab.
  3. Click Run (or ⌘R) to execute the run script in the terminal.
  4. When the app prints a preview link, Atmos can open it in the built-in browser preview.

If no run script exists, you will see No Run Script Configured with a shortcut to Workspace Scripts.

The browser preview supports tabs, desktop and mobile viewport modes, element selection (pastes into the composer as an Element chip), annotations, favorites, developer tools, extension install, center-stage browser tabs, and a standalone desktop Browser window.

On Desktop macOS 14+, the browser toolbar overflow menu can:

  • Import cookies from another browser on this Mac into the Atmos browser profile (stays on-device).
  • Clear cache without signing you out.
  • Clear cookie & storage when you need a clean site session (this signs you out of sites).

The footer shows Atmos Local Services when local processes are detected. Use it to reopen running services or check which local URLs Atmos knows about.

7. Test, ship, and clean up

  1. Run project tests in the terminal (unit, e2e, lint—whatever your repo uses).
  2. Commit or open a PR from your normal Git flow (Atmos Git view helps inspect diffs; PR and CI details open in center tabs).
  3. Archive the workspace when the task is done (sidebar or Kanban Archive).
  4. If configured, the Purge Script removes heavy generated files so old workspaces do not fill your disk.
  5. Use Disk Analyzer when you need a usage map of Atmos-related paths.

Archive Behavior in Settings → Workspace controls confirmations and what happens to terminal sessions when a workspace is archived.

On this page

Overview1. Open or create a workspace2. Run the setup script3. Build with a Code Agent in the terminal4. Review code (optional)5. Manual adjustments (optional)6. Run and preview7. Test, ship, and clean upRelated