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 createfast anyway, sosrcoffers 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 from | Run |
|---|---|
| Your last commit | src ws create api |
| A branch, a tag or a commit | src ws create api --from release-2 |
| Your edits that are not committed yet | src ws create api --from working |
| Another workspace as it is now | src ws create api-2 --from api |
| A checkpoint of a workspace | src 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
srcexits 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.envfiles in the vault of the repository.srcwrites no.envfile. See Give each workspace its env values. - The workspace owns the process.
src ws closestops 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:
- Saves a checkpoint of its files.
- Stops the processes that
src ws execstarted there. It never stops other processes. - Runs the
teardownhook, when the config has one and you trust it. - 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.