--- title: "Workspaces: worktrees, branches, ports and archiving" description: "How microManager creates a workspace (worktree, branch, files, ports, setup script), names it, tracks its status, archives it and restores it." url: "https://micromanager.win/docs/workspaces" updated: "2026-11-08" --- # Workspaces A workspace is one task in one repository. It is a git worktree on its own branch, with its own chat tabs, terminals, ten reserved ports and a setup script run, and it can be archived without losing its branch, its uncommitted work or its .context notes. Updated 8 November 2026 ![The New workspace dialog over the app: repository ledger-api, a new branch from main, a name to be set from the first message, agent Claude Code, model Haiku, effort Agent default, mode Accept edits, and a first message asking it to reject account names longer than 60 characters.](https://micromanager.win/screenshots/new-workspace-dialog.png) A new workspace is a git worktree on its own branch, with an agent ready to work in it. ## What happens when I create a workspace? When you press **⌘N** (Ctrl+N on Windows and Linux) and pick a repository, a base branch and an agent, microManager: 1. **Picks a name.** It chooses a city from a bundled list of about 400 world cities that no other workspace or branch in the repository uses, such as `lisbon`. The branch is `/lisbon`, where the prefix comes from Settings → General → Branch prefix: your GitHub username (looked up once with `gh api user`), a custom prefix, or none. 2. **Creates the worktree.** It fetches the base branch from the remote (giving up after 30 seconds, so it still works offline) and runs `git worktree add -b /`. If the remote has no such branch, it starts from your local one. The new branch has no upstream until it is pushed. 3. **Adds a `.context/` folder** to the worktree and lists it in the repository’s git exclude file (`.git/info/exclude`), so notes and screenshots shared between agents are never committed. 4. **Copies your ignored files**, such as `.env`, from the repository’s main checkout. See [files to copy](https://micromanager.win/docs/files-to-copy). 5. **Reserves ten ports**: the lowest multiple of 10 from 51000 up that no other active workspace uses. The first one is in `MICROMANAGER_PORT` (and `CONDUCTOR_PORT`). See [environment variables](https://micromanager.win/docs/environment-variables). 6. **Runs your setup script** in a **Setup** terminal you can watch. The workspace is ready as soon as the worktree exists, so agents can start while setup is still running. While it runs, and if it fails, a bar above the chat says so, with **Show output**; its log is kept, so you can read it after a restart. 7. **Opens the first chat** with the agent and model you picked, and sends your first message if you wrote one. To work on a branch that already exists, or on an open pull request, choose **Branch** or **Pull request** under **Start from** in the same dialog, or press **⌘⇧N** (Ctrl+Shift+N). The worktree then checks that branch out instead of making a new one: a branch only on the remote is checked out tracking it, and a pull request’s branch comes through `gh pr checkout`, with the workspace named after the pull request and targeting the branch it merges into. ## Where do workspaces live on disk? By default in `~/micromanager/workspaces//`, inside your home folder on every system. Change the folder in Settings → General → Workspaces folder; new workspaces go to the new place. Workspaces imported from Conductor stay exactly where they already are, and nothing is moved. ## How does automatic naming work? After you send the first message in a workspace’s first chat, microManager can give the workspace a readable name and its branch a matching one, such as “Add CSV export” on `/add-csv-export`. It does this only when: - **Name workspaces from the first message** is on in Settings → General (it is by default), - the branch still has its placeholder city name, and - the branch has no upstream, is not on the remote and has no open pull request. A name you typed yourself, in the New workspace dialog or later, is kept; only the branch is renamed then. It asks Claude Code for a name in one-shot mode with the Haiku model (giving up after 20 seconds) when Claude Code is available, whichever agent the chat runs, and otherwise derives one from your message on your computer. The branch is renamed with `git branch -m`. A branch that has been pushed or has an open pull request is never renamed. You can rename the workspace from the workspace header at any time, and its branch there too until it is pushed. ## What do the sidebar’s marks mean? Each workspace in the sidebar shows: - **Activity**: a spinner while the workspace is being set up or an agent is working, a mark when an agent needs your answer, an error mark, a dot for unread replies, or a check once the workspace is Done or its pull request is merged. - **Branch**, **diff size** (lines added and removed) and a **pull request badge**: its number, colored by its checks while it is open, or Draft, Merged or Closed. Right-click a workspace to pin it, rename it, mark it read, copy its branch name, archive it or set your own status: Backlog, In progress, In review or Done. Pinned workspaces stay at the top; the rest are sorted by most recent activity. **⌘1** to **⌘9** (Ctrl+1 to Ctrl+9 on Windows and Linux) jump to the first nine. ## What is the target branch? The branch the workspace will merge into, shown as **→ target** in the header. Diffs compare against it and pull requests are opened against it. It starts as the repository’s default branch; pick another from the header at any time. ## What does archiving do? Archiving a finished workspace: 1. stops the workspace’s agents and terminals, 2. runs the archive script, if there is one (up to 2 minutes; one from the repository’s own files only once you trust it), 3. saves the uncommitted work, untracked and staged files included, as a hidden git commit under `refs/micromanager/archived/`, 4. copies the `.context/` folder into microManager’s own data folder, 5. records the commit the branch points to, 6. removes the worktree folder with `git worktree remove --force`, and 7. deletes the workspace’s checkpoints. **The branch is kept, and so are your uncommitted work and the notes in `.context/`.** Other files git ignores, such as `node_modules` or `.env`, are removed with the folder; restoring copies your files to copy again. With **Archive after merging** on in Settings → General, a workspace is archived as soon as you merge its pull request from microManager. ## How do I restore or delete an archived workspace? **Restore** recreates the worktree for the same branch at the same path (from the recorded commit if the branch was deleted meanwhile), puts the saved uncommitted work and the `.context/` folder back, copies your ignored files again and runs the setup script again. If the branch gained commits that change the same lines while the workspace was archived, the saved changes are kept aside instead of being forced over them, and a bar under the workspace’s tabs lists their files: **Bring back** puts them in the worktree, with conflict markers where both changed the same lines, and **Discard…** deletes them. **Delete** is available only for archived workspaces: it deletes the branch if it is merged into the target branch, or its pull request was merged and every local commit was pushed (a squash merge leaves no other trace), or when you confirm that you want to force it, and drops the saved work. ## What is the `.context` folder for? `.context/` sits inside every workspace and is ignored by git. Agents are told about it, so it is a good place for plans, notes and screenshots that several agents, or several tabs, should share without committing them. ## Where to go next - [Repository settings](https://micromanager.win/docs/repository-settings) - [Files to copy into new workspaces](https://micromanager.win/docs/files-to-copy) - [Why worktrees (feature overview)](https://micromanager.win/features/git-worktrees)