# Workspaces

Workspaces are the core concept in Polyscope. Each workspace is an isolated copy of your repository where a coding agent can work independently — without affecting your main codebase or other workspaces.

## How Workspaces Work

When you create a workspace, Polyscope:

1. Creates a clone of your repository
2. Checks out a new branch based on your base branch (usually `main`)
3. Runs any setup scripts defined in `polyscope.json`

The clone is cheap and fast: on macOS it uses **copy-on-write** at the filesystem level, so even large repositories clone in a fraction of a second and add almost nothing to your disk usage. On Linux and Windows the mechanism differs. See [copy-on-write](/docs/core-concepts/workflows#what-is-copy-on-write) on the Workflow page for how it works and what changes per platform.

<!-- ![Multiple workspaces in the sidebar](/images/docs/TODO.png) -->

Each workspace has:

- Its own **branch** and git history
- Its own **file system** — changes don't affect other workspaces
- Its own **agent session** — a separate conversation with the coding agent
- A randomly generated **name** like "brave-bunny" or "golden-raven"

## Creating a Workspace

There are several ways to create a workspace:

- Press **&#8984;N** to open the repo picker and create a new workspace
- Use the **+** button on a repository in the sidebar
- Use the command palette (**&#8984;K**) and search for "New workspace"
- Create from a GitHub issue or pull request (see [GitHub](/docs/integrations/github))
- Create from a Linear issue (see [Linear](/docs/integrations/linear))
- Create from a Nightwatch issue (see [Nightwatch](/docs/integrations/nightwatch))
- Create from a Sentry event (see [Sentry](/docs/integrations/sentry))

### Base Repository Workspaces

By default, workspaces are created from a copy-on-write clone. You can also create a workspace directly on the base repository itself — without creating a clone. This is useful when you want the agent to work in the same directory as your main checkout, for example when you want changes to appear immediately in a running dev server.

Please note that only one base-repository workspace can be created at once.

![Base repository workspace in the sidebar](/images/docs/base-repository.png)

## Workspace Lifecycle

Every workspace follows a simple lifecycle:

```
Created → Active → Merged / PR Created / Deleted
```

### Created

When a workspace is created, Polyscope makes a copy-on-write clone and runs the setup script (if configured). This usually takes just a few seconds, even for large repositories.

The setup script is your chance to install dependencies, build assets, run migrations, or link services. See [Workflow](/docs/core-concepts/workflows) for configuration details.

### Active

This is the main working phase. You prompt the agent, review changes, iterate, and refine. During this phase you can:

- **Send prompts** — Describe tasks for the agent
- **Review diffs** — Check changes with **&#8984;D**
- **Use the terminal** — Run commands with **&#8984;`**
- **Preview your app** — Open the built-in preview with **&#8984;P**
- **Link other workspaces** — Give the agent cross-repo context

### Merged

Click **Merge** in the workspace header to merge changes directly into your base branch. The agent will stage, commit, push, and update the remote. This is ideal for small, self-contained changes.

### PR Created

Click the **PR** button to have the agent create a pull request instead. The agent commits, pushes the branch, and creates a PR on GitHub. Once a PR exists, subsequent pushes go to the same PR.

You can also create a **draft PR** for CI feedback without signaling the work is ready for review.

### Deleted

When you're done with a workspace, delete it via the command palette or right-click menu. Polyscope runs the archive script (if configured) before removing the clone.

## Workspace Statuses

Each workspace shows its status in the sidebar:

- **Active** — The workspace is available for use
- **Spinner** — An agent is currently running
- **Badge** — The agent is waiting for your input (plan approval or question)
- **Merged** — Changes have been merged to the base branch
- **Dimmed** — Workspace has been merged or archived

## Configuring Workspaces with `polyscope.json`

Most workspace behavior is controlled through a `polyscope.json` file in your repository root. This single file defines how workspaces are set up, what they can preview, and what reusable tasks are available:

```json
{
  "scripts": {
    "setup": "npm ci && npm run build",
    "archive": "rm -rf dist"
  },
  "preview": {
    "url": "http://localhost:3000"
  },
  "tasks": [
    {
      "label": "Security review",
      "prompt": "Review the codebase for security vulnerabilities..."
    }
  ]
}
```

- **`scripts.setup`** — Runs automatically when a workspace is created. See [Workflow](/docs/core-concepts/workflows) for examples.
- **`scripts.archive`** — Runs before a workspace is deleted.
- **`preview.url`** — Gives each workspace a live preview. See [Visual Editor](/docs/digging-deeper/visual-editor) for details.
- **`tasks`** — Reusable prompts you can launch with a single click. See [Tasks](/docs/advanced/tasks) for details.

You can create or edit this file from the command palette (**&#8984;K**) by searching for "polyscope.json".

## Customizing Merge and PR Behavior

You can customize merge and PR prompts per repository in the repository settings. This lets you enforce team conventions like conventional commits, required tests, or PR templates. See [Repositories](/docs/core-concepts/repositories) for details.