Skip to content
Source
Sign inSign up

Start with workspaces

Work with agents / Local workspaces

Start with workspaces

You want two agents on the same task or on two tasks at once, without them writing over each other or over your edits. Make one workspace for each agent, run the agent in it, review what it changed, then close the workspace.

6 min read

You need src on Node.js 22.15 or later, and a git checkout with at least one commit. Run each command in your checkout, or in one of its workspaces.

1. Test your disk once

src ws init

src makes a real copy-on-write test in the folder for workspaces, ../.src-ws/<repository folder>:

  • If the test works, each new workspace is a clone of the files. It is fast and uses almost no disk space.
  • If the test fails, each new workspace is a full copy of the files. The pool of ready workspaces makes src ws create fast anyway, so src offers no disk image.

On Windows, src reads the file system of the drive. ReFS (a Dev Drive) on Windows 11 24H2 or later makes each copy a block clone. NTFS makes full copies.

In a terminal, init first asks which drive holds the workspaces. To pick it in a script, add --drive <folder>. To put the workspaces in another folder, add --root <folder>. If you skip init, the first src ws create runs the test.

init also adds auto-prepare to your git hooks. src keeps 2 ready workspaces in a pool, so that create and close do not wait for a copy or an install. See Keep workspaces ready.

Note

With src ws init --spares 0, src offers to make a disk image with copy-on-write, and asks you first. See Put workspaces on a copy-on-write disk.

2. Create workspaces

src ws create api web

Each name gets its own folder, from the same starting commit (its baseline). create prints the path of each folder:

Created api at /code/.src-ws/app/ws-1 (baseline 1a2b3c4d5e6f, from HEAD)
Created web at /code/.src-ws/app/ws-2 (baseline 1a2b3c4d5e6f, from HEAD)

The folder is a slot: ws-1, ws-2 and up, with the lowest free number. Its name is not the name of the workspace. Use the path that create prints, or the path in src ws list. A slot never moves, so a tool that keeps an absolute path to it keeps working.

When the pool has a ready workspace, create takes it. Its files, its .git and its dependencies are there already, so create only cleans it to the baseline. When the pool is empty, create makes a new slot. Then a background src ws prepare fills the pool again.

Pick the baseline

--from picks the commit that the agent starts from:

You want the agent to start fromRun
Your last commitsrc ws create api
A branch, a tag or a commitsrc ws create api --from release-2
Your edits that are not committed yetsrc ws create api --from working
Another workspace as it is nowsrc ws create api-2 --from api
A checkpoint of a workspacesrc ws create api-2 --from api@cp-3

--from working takes your staged and unstaged changes to tracked files. It leaves out untracked files, and names each one. To add some, give a glob:

src ws create api --from working --include "notes/*.md"

Your checkout, its index and its branches do not change.

Each workspace gets its dependencies

src finds the dependencies from your lockfile, for example node_modules or .venv. pnpm and bun install from their own store, which links the packages. Other layers install once, and the next workspace with the same lockfile gets a clone. The output of create names the strategy of each layer, for example for pnpm:

Created web at /code/.src-ws/app/ws-2 (baseline 1a2b3c4d5e6f, from HEAD)
Layers of web:
  pnpm: installed in 19.3s

When the layers of a ready workspace from the pool have the same lockfile, create runs no install, and says so.

Each workspace has its own copy, so a package that one agent adds does not show in another workspace. To change how src installs, see Install dependencies and share caches.

Note

If the config has a setup hook and you trust it, create runs it in each new workspace. If it fails, the workspace stays as setup-failed. Fix the cause, then run src ws repair api. See Run hooks in workspaces.

3. Run commands in a workspace

src ws exec api -- pnpm test

exec prints the ports of the workspace on stderr before the command starts:

Ports of api: SRC_WS_PORT_0..9 = 10240-10249
  • The command runs in the folder of the workspace, and src exits with its exit code.
  • The command gets the folders of the shared build caches, for example TURBO_CACHE_DIR.
  • The command gets the ports of the workspace, so two dev servers never take the same port. See Give each workspace its own ports.
  • After src ws trust, the command also gets the values of the .env files in the vault of the repository. src writes no .env file. See Give each workspace its env values.
  • The workspace owns the process. src ws close stops it, and every process that it started.

To start your agent there, open its folder (src ws list shows the path), or run the agent with src ws exec.

4. Review the changes

src ws diff api

The diff compares the workspace with its own baseline. Your edits from before create are not in it. New files are in it, but ignored files, untracked .env files and the env files are not.

To bring the changes into your checkout as unstaged changes, run src ws accept api. See Review and accept agent work.

5. Close the workspace

src ws close api web

For each workspace, src:

  1. Saves a checkpoint of its files.
  2. Stops the processes that src ws exec started there. It never stops other processes.
  3. Runs the teardown hook, when the config has one and you trust it.
  4. Gives the folder to the pool, and gives its ports free.

close does not wait for a delete. A background src ws prepare cleans the folder, so that the next create can take it. When the pool is off, close deletes the folder.

The checkpoints stay, so you can still start a new workspace from one.

Done

Each agent has its own folder with its dependencies ready, and your checkout is as you left it. To let your agent make its own workspaces, see Use workspaces with a coding agent.

See your workspaces

src ws list
src ws list --json name,path,checkpoints

Each row shows the state, the baseline, the last checkpoint, the owned processes, the ports and the folder of a workspace.

  • A workspace made from another one shows under it.
  • A workspace that is behind the default branch shows it in its state, for example live, behind main by 2.
  • The last line shows the pool, for example Pool: 2 ready.