Project & Workspace Manager

Create and manage projects and workspaces—the foundation of every Atmos workflow.

Projects and workspaces are how Atmos organizes real work. A project is a codebase on disk. A workspace is a focused place for one task, with its own branch, terminal, editor, agents, and review history.

Overview

What is a workspace?

A workspace is a single unit of work: a feature, bug fix, experiment, or review. Everything you do in Atmos—terminals, Code Agents, diffs, Kanban cards—hangs off a workspace.

Why separate workspaces?

Separate workspaces let multiple tasks share one project while staying on different branches. That enables:

  • Parallel Code Agents on separate branches.
  • Clear separation between tasks.
  • Fast context switches without re-cloning.

Core capabilities

CapabilityWhat it does
Import ProjectAdd a project folder to Atmos
Create workspaceCreate a focused task workspace
Quick New WorkspaceOne-click workspace with auto-generated name/branch
KanbanStatus, priority, labels across workspaces
Workspace scriptsSetup, run, and purge automation per project
Ignored folder syncBring selected ignored folders into new workspaces

1. Add a project

  1. In the left sidebar footer, click Add Project (folder icon), or use Add Project from Global Search / the New Workspace composer.
  2. In Import Project, pick Project Path (type or Browse… → Select Project Directory).
  3. Confirm Git detection, set Project Name, then Import Project.

The project appears in the sidebar with its workspaces underneath.

On mobile, project import selects a path on the connected Atmos Computer. Use browse or search to find a Git repository on that computer, validate the path, then import it. Mobile does not clone projects from the phone.

The Mobile App is currently in development and temporarily unavailable.

2. Configure workspace scripts

Per-project scripts run at key lifecycle moments. Open the project ⋯ menu → Workspace Scripts.

ScriptWhen it runs
Setup ScriptAfter a new workspace is created (dependencies, env files, etc.)
Run ScriptOne-click start for your app or local preview
Purge ScriptCleanup when removing or archiving a workspace

The dialog lists environment values you can use in scripts (project path, workspace name, and workspace folder).

Click Save Scripts when done.

3. Ignored Folder Sync

Some teams keep agent instructions, prompts, or local tools in folders that are not committed to Git. Enable sync when new workspaces should still receive those folders.

  1. Open Settings → Workspace → GitIgnore Directories Sync.
  2. Turn on the master switch.
  3. For each folder, choose whether Atmos should link it, copy it, or ignore it.
  4. Add custom folders if needed.

If sync fails, Atmos shows a GitIgnore Sync Failed message when the workspace is created.

4. Create a workspace

4.1 Quick New Workspace (sidebar)

  1. On a project row, click Quick New Workspace (⚡).
  2. Atmos creates a workspace with an auto-generated name and branch, sets it to In Progress, and prepares it.
  3. You land in the workspace when setup finishes.

Best for: fast spikes with no GitHub link or custom branch name.

4.2 New Workspace Composer

  1. Open New Workspace from the Management Center (⌘N), the project menu, or Global Search.
  2. The New Workspace overlay covers the center and right panels (sidebar stays visible).
  3. In the prompt composer:
    • Type the goal, add helpful references, or paste images.
    • Set Priority, Status, Labels, and pick a project.
  4. Advanced (⋯): set Name, Base branch, Current workspace branch, or link a GitHub Issue / GitHub PR.
  5. Press Create Workspace — Atmos creates the workspace, prepares it, opens it, and can queue the first agent prompt.

Best for: agent-first tasks with rich context up front.

4.3 Create New Workspace dialog (Kanban & issues)

  1. From Kanban, click + on a column or Build workspace from issue on an Issue Only card.
  2. In Create New Workspace or Build Workspace from Issue, choose the project, name, branch, and optional GitHub issue or pull request.
  3. Create Workspace runs the same preparation flow as the composer.

Mobile workspace creation supports the same core idea with a smaller screen: title, base branch, optional internal name and branch, GitHub Issue or PR URL, TODO extraction, priority, status, labels, setup progress, Confirm TODOs, Retry Setup, and Open Workspace.

4.4 Kanban: Issue Only workspaces

  1. Open Kanban (sidebar icon or ⌘⇧K for expanded board).
  2. Click Import GitHub Issues, select a repo, load issues, then Import N Issue(s).
  3. Issues appear as GitHub Issue Only Workspace cards, tracked on the board before a real workspace exists.
  4. When ready, use Build workspace from issue to create the real workspace and start building.

5. Manage workspaces with Kanban

Columns follow workflow status: Backlog, To Do, In Progress, In Review, Blocked, Completed, Canceled.

Toolbar:

  • Filter by status, priority, labels, project.
  • Group By Project, By Status, or By Time.
  • Sort by Last Visit, Create Time, or Priority.
  • Toggle Show Issue Only / Hide Issue Only.

Actions on cards: drag to change status, Pin, Archive, Delete, or open the workspace.

Use Kanban to answer: What should I work on next?

6. Workspace Overview

The workspace overview summarizes the current task without opening every panel. Use it to check requirements, tasks, notes, pull requests, Actions, and workspace state before deciding what to run next.

On mobile, Overview is one of the three workspace views alongside Terminal and Changes.

On this page

OverviewWhat is a workspace?Why separate workspaces?Core capabilities1. Add a project2. Configure workspace scripts3. Ignored Folder Sync4. Create a workspace4.1 Quick New Workspace (sidebar)4.2 New Workspace Composer4.3 Create New Workspace dialog (Kanban & issues)4.4 Kanban: Issue Only workspaces5. Manage workspaces with Kanban6. Workspace OverviewRelated