Clean re-setup

Inventory and remove everything Orchemax or a wired agent left in a workspace, then re-seed it from a known state — or uninstall Orchemax entirely.

Goal#

Over time a workshop accumulates state: .orch/ grows, dispatch worktrees and logs pile up, and an agent can leave a scratch dot-directory or a stray report file outside .sandbox/<seat>/. orch workspace clean inventories all of it — grouped by who owns it — before anything is touched, and only --apply ever deletes. This page also covers orch uninstall, for when you want Orchemax gone from a workspace (or a machine) altogether.

1. Inventory first#

orch workspace clean --dry-run

(Bare orch workspace clean does the same thing — dry-run is the default; nothing is ever deleted without --apply.) It walks the workspace root and every registered project/shared root and prints four groups:

  • orch-regenerated — everything orch init / orch setup / orch project add / orch guard wire recreate on the next run: most of .orch/, the AGENTS.md digest block, GEMINI.md / .github/copilot-instructions.md / .cursor/rules/orch*.mdc pointer files, .mcp.json / .cursor/mcp.json, the Orchemax-owned .cursor/hooks.json and .claude/settings.local.json hook entries (or the legacy .claude/settings.json, for a workspace that has not re-wired since the block moved), .sandbox/README.md, and the sealed orch-chair/orch-worker/orch-clarify/orch-recall skill folders.
  • orch-runtime — per-run scratch: dispatch worktrees, .orch-agent-*.log, .orch-run.cmd, supervisor state, and everything under .sandbox/<seat>/ except its README.md.
  • agent-litter — what the litter guard (see Hooks and guards) would have denied had it seen the write: a dot-directory or a scratch/report-shaped file an agent left outside .sandbox/<seat>/ or the docs folder. This also catches the literal nul/con/aux/prn/com1..9/lpt1..9 files a bash > nul redirect leaves behind on Windows — Explorer cannot delete these (the OS intercepts the plain name), so --apply moves or purges them through the \\?\ extended-length path instead. By hand, from Git Bash: rm -f ./nul.
  • yours-keep — never a valid --group: orch.db, .orch/gates/user/, .orch/packs/. --apply refuses this group outright.

Only Orchemax-touchable or litter-shaped paths are listed — ordinary project files are never enumerated. Add --json to script against the same structure.

A shared file that also carries your own content (AGENTS.md, .claude/settings.local.json) is never deleted outright: only Orchemax's own marked slice is stripped, and a snapshot of the file is still taken first.

2. Apply#

orch workspace clean --apply --group agent-litter --group orch-runtime --group orch-regenerated

Prints exactly what would move, then asks Move N item(s) in group(s) …? [y/N] (--yes to skip the prompt in a script). Matched paths move to <workspace>/.orch/trash/<timestamp>/, preserving their relative layout, so nothing is destroyed by mistake — pass --purge to hard-delete instead.

3. Re-seed#

orch init --yes
orch setup --yes --project <path>   # per project, if you use per-project setup

init/setup regenerate every orch-regenerated path from live config — that's the whole point of the split above.

4. What each project gets#

  • .sandbox/ — a seat's own scratch lives at .sandbox/<seat>/, swept by the reaper after guard.sandbox_days (default 14). Nothing an agent writes there is ever litter.
  • AGENTS.md + per-CLI pointers (GEMINI.md, .github/copilot-instructions.md, .cursor/rules/orch.mdc, the @AGENTS.md include in CLAUDE.md) so every wired CLI reads the same workspace digest.
  • Gates (.orch/gates/README.md + basics/manifest.json) and your own overrides in .orch/gates/user/ — never touched by clean or re-seed.
  • The litter guard, on by default: an agent may read project code freely; anything it writes that is not project code belongs in .sandbox/<seat>/ or the docs folder.

5. Acceptance check#

orch harness scan
orch guard litter --count

harness scan confirms every wired CLI still resolves its AGENTS.md pointer and hooks; guard litter --count reports 0 hits against git's current changed-file set.

Uninstall#

orch uninstall goes further than clean: it removes Orchemax from a workspace (or, with --scope user, from the machine) rather than just re-seeding it. --dry-run by default; nothing is deleted without an explicit yes.

Workspace scope (default)#

orch uninstall --dry-run
orch uninstall --yes

Two steps, two separate confirmations (--yes answers both):

  1. Deletes orch-regenerated + orch-runtime + agent-litter — the same three groups workspace clean --apply would.
  2. With a second, explicit confirmation, also relocates orch.yaml and the rest of .orch/ — including .orch/gates/user/, .orch/packs/ and orch.db — into <workspace>/orch-uninstall-<timestamp>/. Nothing here is ever hard-deleted (--purge opts into that instead): a "yours-keep" path is moved, never destroyed, precisely so it can be recovered.

The output names the recovery folder and lists every "yours-keep" path it preserved there.

User scope#

orch uninstall --scope user --allow-user-scope

Removes only what Orchemax itself ever wrote outside a workspace: ~/.claude/settings.json (Orchemax's own marked hooks and its mcpServers.orch entry — nothing else in that file), ~/.claude/orch-mcp.json, ~/.cursor/mcp.json's mcpServers.orch entry, the home skill trios (.claude/.cursor/.commandcode/.config/opencode skills/orch-*), agy's global MCP entry, the OpenCode plugin plus its opencode.json provider.orchemax block, and the User environment variables a consented wire set (ORCH_GATEWAY_KEY, OPENCODE_DISABLE_MOUSE). It never touches a file it did not write into, and ~/.claude/settings.json is backed up (.bak-<yyyymmdd-hhmmss>) before it is rewritten.

Interactively it lists every file it is about to touch and asks once; --allow-user-scope is required non-interactively (mirrors orch guard wire --scope user) — --yes alone never grants user scope.

  • Hooks and guards — the litter guard and gate profiles workspace clean's inventory is built on.
  • Organize a workshop — init/setup/project add, the commands that re-seed what clean removes.
  • Worktrees — what a dispatch worktree is, the orch-runtime group's biggest occupant.