# Workflow

Polyscope is built around a simple, repeatable workflow: **one workspace per feature or fix**. This keeps work isolated, easy to review, and safe to ship.

## The Core Loop

The recommended workflow in Polyscope follows this pattern:

1. **Create a workspace** — Press **⌘K** and type **new** to select a repository and spin up an isolated clone as new workspace
2. **Work on one thing** — Give the agent a focused task: a single feature, bug fix, or refactor
3. **Review and ship** — Check the diff (optionally use [Review](/docs/digging-deeper/review) for a dedicated review agent), then merge directly or create a pull request
4. **Delete the workspace** — Clean up and move on to the next task

Repeat this for every piece of work. Each workspace is disposable — treat them like branches you create, use, and throw away.

<!-- ![Polyscope workflow](/images/docs/TODO.png) -->

## What is copy-on-write?

The create-and-throw-away loop above is only practical because creating a workspace is effectively free. That comes down to **copy-on-write**.

Copy-on-write (CoW) is a filesystem feature that lets two files share the exact same bytes on disk until one of them changes. When Polyscope clones your repository, it copies no file contents at all — it writes a second set of directory entries pointing at the *same* underlying data as the original. Two things follow, and they're the whole point:

- **Creating a workspace is near-instant.** Polyscope writes a little directory metadata instead of copying gigabytes, so even a large repository — `node_modules`, `vendor` and all — clones in a fraction of a second. Spinning up a fresh workspace for every task never makes you wait.
- **It barely touches your disk.** A new clone adds only kilobytes up front, so you can keep many workspaces open at once without multiplying your repository's size on disk.

When an agent (or you) edits a file, the filesystem gives just that file its own fresh copy of the changed data and writes the change there. That copy belongs to this workspace alone — the original repository and every other workspace keep seeing the unchanged version. Files nobody has touched (the vast majority, especially `node_modules` and `vendor`) go on sharing the same data on disk.

```
Original repo          Workspace clone (just created)
┌──────────────┐       ┌──────────────┐
│ app/         │◄──────│ app/         │   shared on disk
│ node_modules/│◄──────│ node_modules/│   shared on disk
│ README.md    │◄──────│ README.md    │   shared on disk
└──────────────┘       └──────────────┘

After the agent edits README.md:
┌──────────────┐       ┌──────────────┐
│ app/         │◄──────│ app/         │   still shared
│ node_modules/│◄──────│ node_modules/│   still shared
│ README.md    │       │ README.md    │   copy owned by this workspace
└──────────────┘       └──────────────┘
```

You only ever spend time and disk on what actually changes — which is exactly what makes disposable, one-workspace-per-task development practical.

### Copy-on-write is macOS only

CoW cloning relies on APFS, the default macOS filesystem, so it only applies when you run Polyscope on a Mac. (It also doesn't apply on a Mac when the repo lives on a non-APFS volume — like an external exFAT drive — or is itself a git worktree.)

**On Linux and Windows**, Polyscope clones with `git clone --local` instead. This hardlinks git's internal objects, so checking out your tracked files is still fast and cheap. The difference is that gitignored files — `node_modules`, `vendor`, build artifacts — are **not** carried over, because git ignores them. Your workspace's [setup script](#setup-and-shutdown-scripts) reinstalls dependencies instead, which is why a setup step like `npm ci` matters more off macOS.

If reinstalling is slow or impossible offline, set [`copyGitignored`](/docs/core-concepts/polyscope-json#copygitignored) to `true` to copy those ignored files into the clone. It trades clone speed and disk space for having dependencies ready immediately — on macOS, CoW already includes them at almost no cost in time or disk.

## Why One Workspace Per Task

Keeping each workspace focused on a single task has several advantages:

- **Clean diffs** — Every workspace produces a focused set of changes that's easy to review
- **No interference** — Agents in different workspaces can't step on each other's toes
- **Parallel work** — Run multiple workspaces at the same time for independent tasks
- **Easy rollback** — If something goes wrong, delete the workspace and start fresh

Avoid cramming multiple unrelated changes into one workspace. If a task naturally splits into independent parts, use separate workspaces.

## Setup and Shutdown Scripts

The key to a fluent workflow is automating workspace setup and teardown. Define scripts in `polyscope.json` so every new workspace is ready to go immediately:

```json
{
  "scripts": {
    "setup": "npm ci && npm run build",
    "archive": "herd unlink"
  }
}
```

- **`setup`** — Runs automatically after a workspace is created. Install dependencies, build assets, run migrations, link services — whatever your project needs.
- **`archive`** — Runs before a workspace is deleted. Unlink services, clean up external resources.

### Example: Laravel with Herd

[Laravel](https://laravel.com/) and [Laravel Herd](https://herd.laravel.com/) are a perfect combination for AI-driven web application development and provide you with a robust foundation, even if you're new to Laravel.

```json
{
  "scripts": {
    "setup": ["herd link", "herd secure"],
    "archive": ["herd unsecure", "herd unlink"]
  },
  "preview": {
    "url": "https://{{folder}}.test"
  }
}
```

This registers each workspace as a Herd site with HTTPS, and gives it a live preview URL. See [Laravel Herd](/docs/integrations/laravel-herd) for more details.

### Example: Node.js

```json
{
  "scripts": {
    "setup": "npm install && npm run build",
    "archive": "rm -rf dist"
  },
  "preview": {
    "url": "http://localhost:3000"
  }
}
```

## When to Use Multiple Workspaces

Create separate workspaces when you have:

- **Independent tasks** — A bug fix and a feature that don't overlap
- **Exploratory work** — Try different approaches in parallel and keep the best one
- **Large refactors** — Split into smaller, focused chunks
- **Review + build** — Have one agent review code while another builds a feature

If tasks depend on each other's output, complete the first before starting the next, or use [linked workspaces](/docs/digging-deeper/linking-workspaces) so agents can coordinate.

## Tips

- **Start small** — When working on a new codebase, give the agent smaller tasks first to build confidence in its understanding
- **Review before merging** — Always check the diff (**&#8984;D**) before shipping
- **Use plan mode** for complex changes — Have the agent propose a plan before coding