Workspaces

A workspace is a folder working on one change. Your work lives in the change, not the folder, so you can have as many workspaces as you like and delete one without losing anything.

One workspace per agent

on get upstream.codes/acme/shop ../shop-search    # a new workspace
on workspaces add ../shop-search                  # the same, from inside a workspace
on workspaces                                     # this project's workspaces on this machine
on workspaces clean                               # remove the ones whose work is done

Two processes editing one folder is how work gets lost, so give each agent its own. A new workspace takes seconds: files come from a cache all your workspaces share, copied on write where the disk supports it.

on workspaces clean saves each workspace first. It removes one only if its change is empty, no on command is running in it and nothing changed for two hours (--idle 10m for less). Work that hasn't landed is never removed.

Hand part of a task to a subagent

on workspaces add ../shop-tests --on .

This makes a workspace on a new change that starts from yours as it is now. Landing the subagent's change lands yours first.

Several changes in one folder

Command	What it does
on new "Title"	Starts another change on the latest main. The current one stays saved.
on new "Title" --on <change>	Starts a change on top of one that hasn't landed.
on switch <change>	Puts this workspace on another change.
on describe "Title"	Sets the current change's description.
on drop	Abandons the current change. on undo brings it back.

One workspace holds one change at a time, and one change is in one workspace at a time. If you switch to a change another workspace holds, you take it over. Edits there that weren't saved yet go into a new change labelled "rescued from", so nothing is lost.

Copy build folders

onset.toml can list folders that new workspaces copy from your most recent workspace of the same project:

[workspace]
copy = ["node_modules", "target"]

Big projects

on get upstream.codes/acme/monorepo --lazy
on get upstream.codes/acme/monorepo --only src/web --only docs

--lazy shows every file at once and fetches each one from the host the first time it's opened. It works on macOS, Linux and Windows with nothing to install. After a restart, on mount or any on command in the folder starts it again, and on mount --stop stops it.

--only gets just the folders you name.

Your editor's Git panel works

Each workspace has a .git for editors and tools that read Git. It's checked out at the version your change started from, so gutter markers, git status and git diff show your edits. git commit and git push are refused, with the on command to run instead. Set ONSET_GIT=0 to go without it.

Delete a workspace

Delete the folder. Its change stays, on log --changes lists it, and on get <project> <folder> --change <id> opens it again on any machine.

Run any on command, like on status, before you delete a folder you just edited. That saves the last few seconds of work.

Offline

Everything works offline except land, get, access and the parts of log and status that need the host's latest main. Saves queue up and upload when you're back online.

A project made with on init has no host at all, and landing is local. on publish moves it to a host with its history and version numbers.