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.

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.
  3. Or use the global agent chat panel for focused tasks that do not need a full terminal flow.

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, annotations, favorites, developer tools, extension install, and a standalone desktop Browser window. Use it when you want to inspect the running app without leaving the workspace.

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 first).
  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.

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