Fast, lightweight workspace graphs for Git repositories.
ws creates mutable workspaces from immutable layers — think lightweight branching for entire working directories. Branch from another agent's workspace. Isolate to a clean base. Diff, commit, and garbage-collect — all without touching Git itself.
On Linux, workspaces are overlayfs mounts (instant fork, zero-copy). On macOS, they use efficient directory copies — or, when Apple Container is installed, lightweight Linux VMs (auto-detected, no configuration needed). The CLI and graph model are identical on every platform.
# Start from a repository
$ ws get base:https://github.com/you/project --name=feature-a
workspace feature-a formed from a3f4d...
# Work inside it
$ ws run feature-a -- npm install
# Branch — build on another agent's work
$ ws get ws:feature-a --name=feature-b
workspace feature-b formed from 8c2e1...
# Diff against the base
$ ws diff feature-a
--- a/package.json
+++ b/package.json
@@ -1,3 +1,5 @@
{
- "version": "1.0.0"
+ "version": "1.1.0"
"dependencies": {
"express": "^4.21.0"
+ "lodash": "^4.17.21"
# Promote changes to a permanent layer
$ ws keep feature-a --message="added lodash"
kept layer 8c2e1ba7d3f4...
# See the graph
$ ws graph feature-b
ws:feature-b [active]
└─ layer:8c2e1ba7d3f4 [added lodash]
└─ layer:a3f4d9c2e1b5 [base:https://github.com/you/project#HEAD]curl -sSL https://raw.githubusercontent.com/weslien/ws/main/install.sh | bashThe installer tries, in order:
- Prebuilt binary from the latest GitHub release — checksum-verified against the published
.sha256asset - Source build at the release tag (needs
git+go1.23+) — version injected via ldflags go installas a last resort
Overrides: VERSION=vX.Y.Z installs a specific release; INSTALL_DIR=/path changes the install location. Default location is /usr/local/bin if writable, otherwise ~/.local/bin — make sure it's in your PATH:
export PATH="$HOME/.local/bin:$PATH" # if installed to ~/.local/bingit clone https://github.com/weslien/ws.git
cd ws
go install github.com/go-task/task/v3/cmd/task@latest
task install # builds with version injection and installs to ~/.local/binOr without go-task:
git clone https://github.com/weslien/ws.git
cd ws
go build -ldflags "-s -w -X main.version=v0.5.2" -o ws ./cmd/wsgit clone https://github.com/weslien/ws.git
cd ws
go install github.com/go-task/task/v3/cmd/task@latest
task build # build binary
task test # unit tests
task e2e # end-to-end lifecycle test (30 checks)
task check # lint + test + e2e
task --list # see all tasksPrebuilt binaries are provided for Windows amd64 and arm64 in each GitHub Release. Download the .tar.gz for your architecture, extract, and add the directory to your PATH.
Building from source also works:
git clone https://github.com/weslien/ws.git
cd ws
go build -o ws.exe ./cmd/wsws graph
# → Layers:
# → Workspaces:On macOS, ws uses efficient directory copies by default. For per-workspace Linux VMs (real Linux kernel; execution and file operations happen inside the VM while the workspace stays visible on your Mac), install Apple Container:
brew install container
container system start # first run prompts to install a Linux kernelRequirements: macOS 26 (Tahoe) or later, Apple Silicon (M1+).
With the CLI installed, ws auto-detects it and routes each new workspace through a container machine — same graph model, same commands. No configuration needed.
WS_BACKEND=copy ws ... # force directory copies (e.g. inside VMs-in-VMs)
WS_BACKEND=container ws ... # require the container backend (errors if not installed)Notes:
- Prefer hyphens in workspace names —
container machineidentifiers do not allow underscores (wssanitizes them, but distinct names can collide:bug_1andbug-1both map to machinews-bug-1). - First fork per machine boots a VM and stages the layer content into it; subsequent
ws keep/ws diffrun inside the VM while the workspace directory stays visible (and directly usable) on your Mac. - In-VM overlayfs is planned but deliberately not enabled yet:
ws runexecutes on the Mac, and a VM-side overlay would hide host writes fromws keep. See issue #1.
| Term | Definition |
|---|---|
| Layer | An immutable, content-addressed directory. Stored in ~/.ws/layers/<hash>. Once created, never changes. The unit of sharing. |
| Workspace | A mutable working directory. Stored in ~/.ws/workspaces/<name>. Created from a layer (formed_from). You keep it to promote to a new layer, or drop it to destroy. |
| Graph | The provenance chain of a workspace: the sequence of parent → parent → base layers. ws graph prints this tree. |
Git worktrees let you check out multiple branches into separate directories. ws is different:
- Branch from uncommitted work —
ws get ws:agent-acaptures agent-a's current dirty state, not just a committed branch. - Isolation is explicit —
ws get layer:basegives a clean slate from the immutable base, not whatever happens to be onmainright now. - No Git indexing — operations don't touch
.git/index, so there's no risk of index corruption from concurrent agent access. - Content-addressed base layers — a layer with hash
a3f4d...is exactly that content, forever. No ambiguity about what "HEAD" meant at fork time.
| Source | Meaning |
|---|---|
layer:<hash> |
Fork from an immutable layer |
ws:<name> |
Branch from another workspace's current state (snapshot-first) |
base:<repo>#<ref> |
Clone a git repo, create a layer from it, fork from that layer |
dir:<path> |
Create a workspace from a local directory (no git repo needed) |
| Command | Description |
|---|---|
ws get <source> --name=<ws> |
Create a workspace from a layer, another workspace, or a git repo |
ws run <ws> -- <cmd...> |
Execute a command inside a workspace's filesystem |
ws diff <ws> [target] |
Diff workspace vs its base, or vs another workspace/layer |
ws keep <ws> [--message=...] |
Materialize workspace changes as an immutable layer |
ws drop <ws> |
Destroy workspace and all uncommitted changes |
ws graph [ws] |
Print the layer + workspace DAG, or a specific workspace's provenance |
ws layer ls |
List all layers |
ws layer show <hash> |
Show layer metadata |
ws layer gc |
Garbage-collect unreferenced layers |
# From a layer
ws get layer:a3f4d9c2e1b5 --name=feature-a
# From another workspace (snapshot first, branch second)
ws get ws:feature-a --name=feature-b
# From a git repo
ws get base:https://github.com/you/project#main --name=feature-c
ws get base:/path/to/local/repo --name=feature-dws run feature-a -- cat package.json
ws run feature-a -- npm install
ws run feature-a -- go test ./...On Linux, the workspace is a mounted overlayfs — all writes go to the private upper directory.
# Diff workspace vs the layer it was forked from
ws diff feature-a
# Diff two workspaces
ws diff feature-a feature-b
# Diff workspace vs a specific layer
ws diff feature-a layer:a3f4d9c2e1b5ws keep feature-a --message="installed dependencies"
# → kept layer 8c2e1ba7d3f4After keep, the new layer is recorded in the graph. The workspace now tracks from the new layer as its base.
ws drop feature-aAll uncommitted changes are lost. The workspace directory is removed.
# All layers and workspaces
ws graph
# Provenance tree for a specific workspace
ws graph feature-bws layer ls
ws layer show a3f4d9c2e1b5
ws layer gc # removes layers no longer referenced by any workspace# 1. Create a test repository
mkdir /tmp/demo && cd /tmp/demo
git init
echo '{"name": "demo"}' > package.json
git add . && git commit -m "initial"
# 2. Form a workspace
ws get base:/tmp/demo --name=agent-1
# → created layer a3f4d9c2e1b5...
# → workspace agent-1 formed from a3f4d9c2e1b5
# 3. Modify
ws run agent-1 -- sh -c 'echo {"version": "1.0"} > package.json'
ws diff agent-1
# → --- package.json
# → +++ package.json
# → @@ -1 +1 @@
# → -{"name": "demo"}
# → +{"version": "1.0"}
# 4. Branch — agent-2 sees agent-1's work
ws get ws:agent-1 --name=agent-2
ws run agent-2 -- cat package.json
# → {"version": "1.0"}
# 5. Isolate — agent-3 gets the clean base
ws get layer:a3f4d9c2e1b5 --name=agent-3
ws run agent-3 -- cat package.json
# → {"name": "demo"}
# 6. Commit agent-1's changes
ws keep agent-1 --message="added version"
# → kept layer 8c2e1ba7d3f4...
# 7. See the graph
ws graph agent-2
# ws:agent-2 [active]
# └─ layer:8c2e1ba7d3f4 [added version]
# └─ layer:a3f4d9c2e1b5 [base:/tmp/demo#HEAD]
# 8. Clean up
ws drop agent-3
ws layer gc~/.ws/
├── layers/
│ ├── a3f4d9c2e1b5/ # immutable layer content
│ └── 8c2e1ba7d3f4/
├── workspaces/
│ ├── agent-1/ # mutable workspace (overlay mount on Linux)
│ └── agent-2/
├── uppers/ # overlayfs upper dirs (Linux only)
│ ├── agent-1/
│ └── agent-2/
├── workdirs/ # overlayfs work dirs (Linux only)
│ ├── agent-1/work/
│ └── agent-2/work/
└── meta/
├── layers.json # layer metadata (parent, message, timestamp)
└── workspaces.json # workspace metadata (formed_from, state)
Layers are content-addressed by a SHA-256 truncated to 16 hex characters.
- Uses
fuse-overlayfsfor unprivileged overlay mounts — nosudorequired. fuse-overlayfspackages:fuse-overlayfs(Debian/Ubuntu),fuse3(Alpine), or compile from source.- Each workspace = one overlay mount. Forking snapshots the source workspace to a new layer first, then mounts the new workspace from that layer.
- By default, uses directory copies for all fork/branch operations (no kernel overlayfs available).
- If Apple's
containeris installed (macOS 26+, Apple Silicon), ws auto-detects it and runs each workspace in a lightweight Linux VM (container machine) — execution and file operations happen inside the VM, the workspace directory stays visible on the Mac (see "macOS: Linux VM workspaces via Apple Container" above). - No additional dependencies beyond Go (copy backend).
- Supported via the copy backend. Prebuilt binaries for Windows amd64 and arm64 are provided in each GitHub Release; extract the
.tar.gzfor your architecture and add the directory to yourPATH.
internal/backend/
backend.go — Backender interface (platform abstraction)
copy.go — CopyBackend (macOS, Windows fallback)
overlayfs_linux.go — OverlayfsBackend (Linux, fuse-overlayfs)
platform*.go — Build-tag backend selection
internal/storage/
metadata.go — JSON metadata for layers and workspaces
cmd/ws/main.go — CLI
Adding a new backend (e.g., container on macOS 26, APFS clone, or ZFS snapshot) requires implementing the Backender interface. The CLI, graph engine, and metadata layer are platform-agnostic.
Q: Why not just use Git worktrees?
Git worktrees are great for human developers working on committed branches. ws is designed for agents that may have:
- Uncommitted state that another agent wants to build on
- Concurrent access to the same repo (no index races)
- Need to isolate to a guaranteed-clean base, not "whatever main is now"
Q: Can I use this to replace Docker volumes or dev containers?
Not directly — ws is a filesystem primitive, not a runtime. But it's designed to compose cleanly with containers: a container runtime can mount a ws workspace as its working directory.
Q: Does ws track file renames efficiently?
Not yet — renames trigger full copy-up on the copy backend, and overlayfs handles them at the filesystem level on Linux. A Merkle-tree content-addressed backend would optimize this.
Q: How do I clean up old layers?
ws layer gc removes any layer not transitively reachable from a live workspace. Run it periodically.
- Fork the repository
- Create a branch:
git checkout -b feature/xyz - Make your changes
- Run
go test ./...andgo vet ./... - Submit a pull request
Please open an issue before major design changes.
Inspired by:
- Git worktrees — the original multi-workspace idea
- Docker overlayfs driver< 5B97 /a> — the filesystem layering model
- Nix store — content-addressed store paths
MIT — see LICENSE.