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 scripts in a .atlas/ directory at the root:

  • .atlas/setup.sh — runs automatically when a workspace is created. use it for installing dependencies, creating databases, etc.
  • .atlas/teardown.sh — runs when a workspace is archived. use it for cleanup.

conductor.json support

atlas natively supports conductor.json — if your repo already uses conductor for workspace orchestration, atlas will read its setup, run, and archive scripts and run them at the right time. existing conductor scripts work out of the box.

when conductor mode is enabled for a repo, atlas allocates a port for the conductor server (starting at 3000, incrementing by 10) and shows a dedicated conductor server tab in the workspace view.

environment variables

all setup, teardown, and conductor scripts receive the following environment variables:

  • ATLAS_WORKSPACE=1
  • CONDUCTOR_WORKSPACE_NAME — the workspace name
  • CONDUCTOR_WORKSPACE_PATH — full path to the worktree
  • CONDUCTOR_ROOT_PATH — path to the repo’s bare clone
  • CONDUCTOR_DEFAULT_BRANCH — the repo’s default branch
  • CONDUCTOR_PORT — allocated port (when conductor is enabled)

this means if you already have conductor scripts that reference these env vars, they’ll just work.

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
└── atlas.db                  # sqlite database

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 conductor archive script (if conductor is enabled), otherwise runs .atlas/teardown.sh if it 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.