workspaces

what is a workspace?

a workspace in atlas is a git worktree — an isolated working directory tied to a specific branch. unlike cloning a repo multiple times, worktrees share the same git history and objects, so they’re fast to create and lightweight on disk.

creating a workspace

when you create a workspace you can:

  • create a new branch from any remote branch (prefixed with ws/)
  • check out an existing branch as a worktree

atlas runs git fetch origin first to ensure you’re working with the latest refs, then creates the worktree with git worktree add.

setup & teardown scripts

repos can include a .atlas/ directory with scripts that atlas runs automatically during the workspace lifecycle — setup, teardown, preflight checks, and dev servers. see the scripts docs for full details, environment variables, and examples.

directory structure

atlas organizes everything under ~/.atlas/:

~/.atlas/
├── repos/                    # git clones (head detached)
│   └── my-app/
└── workspaces/               # git worktrees
    └── my-app/
        ├── amber-arch/       # workspace worktree
        └── fix-login/        # workspace worktree

the database (atlas.db) and terminal scrollback are stored separately in the system app data directory (~/Library/Application Support/com.atlasworkspaces.mac/ on macos).

workspace lifecycle

each workspace has a status: active or archived.

  • active — worktree exists on disk, terminals and agents can run
  • archived — worktree removed, branch deleted, terminal sessions closed

archiving

when you archive a workspace, atlas:

  1. runs the teardown script if one exists
  2. kills all running terminal processes in the workspace
  3. removes the git worktree with git worktree remove
  4. deletes the workspace branch from git
  5. marks the workspace as archived in the database

workflow status

workspaces can be tagged with workflow labels like wip, in-review, done, or on-hold. these are customizable in settings — you can define your own labels and colors.

jira integration

workspaces can be linked to jira tickets. atlas uses your jira credentials to search and display issue details directly in the workspace view.