Isolated Workspaces
The core idea in Fletch is the workspace: a single agent, working on a single stream of work, in its own isolated copy of your repository. Understanding the workspace is the key to understanding everything else.
A workspace is a unit of work
Section titled “A workspace is a unit of work”When you spawn an agent, Fletch gives it its own checkout of your repo — a
lightweight clone that shares your repo’s git objects, created in milliseconds, starting
from a pinned commit on your base branch — and runs it inside a sandbox. That pairing
is the workspace, living under ~/.fletch/workspaces/<id>/. Because each workspace is a
different checkout with its own .git, two agents editing the same file simply can’t
happen: they’re working different copies of the same project, and your repo’s real
.git is never writable by any of them. (Why a clone and not a linked worktree is worth
two minutes: see Security & Sandboxing.)
Think of a workspace the way you’d think of a branch you’d hand to a teammate: one coherent piece of work, start to finish.
Isolation is what makes parallelism safe
Section titled “Isolation is what makes parallelism safe”The default sandbox is a write-protection boundary. An agent can read your files and use the network, but it can only write inside its own workspace and its own config. So you can run a dozen agents at once and none of them can trash your repo, your other agents’ work, or the rest of your machine. When you want a harder boundary — one that limits reading too — switch that agent to the Docker engine.
Clean up when you’re done
Section titled “Clean up when you’re done”A workspace is disposable. When an agent’s work is merged or abandoned, archive it to keep a restorable snapshot, or discard it to remove the checkout and its branch for good. Either way, your main checkout is never touched — discarding is just deleting the workspace directory.