Limpieza y re-setup

Inventaria y elimina todo lo que Orchemax o un agente conectado dejo en un workspace, y vuelve a sembrarlo desde un estado conocido, o desinstala Orchemax por completo.

Objetivo#

Con el tiempo un workshop acumula estado: .orch/ crece, se apilan worktrees de dispatch y logs, y un agente puede dejar un dot-directory de scratch o un archivo de reporte suelto fuera de .sandbox/<seat>/. orch workspace clean inventaria todo eso -agrupado por quien es el dueno- antes de tocar nada, y solo --apply borra algo. Esta pagina tambien cubre orch uninstall, para cuando quieres que Orchemax desaparezca de un workspace (o de una maquina) por completo.

1. Inventario primero#

orch workspace clean --dry-run

(orch workspace clean a secas hace lo mismo -dry-run es el default; nunca se borra nada sin --apply.) Recorre la raiz del workspace y cada proyecto/carpeta compartida registrada, e imprime cuatro grupos:

  • orch-regenerated -todo lo que orch init / orch setup / orch project add / orch guard wire vuelven a crear en la proxima corrida: la mayor parte de .orch/, el bloque digest de AGENTS.md, los archivos puntero GEMINI.md / .github/copilot-instructions.md / .cursor/rules/orch*.mdc, .mcp.json / .cursor/mcp.json, las entradas de hooks propias de Orchemax en .cursor/hooks.json y .claude/settings.local.json (o el .claude/settings.json legado, para un workspace que no se re-cablea desde que el bloque se movio), .sandbox/README.md, y las carpetas de skill selladas orch-chair/orch-worker/orch-clarify/orch-recall.
  • orch-runtime -scratch de cada corrida: worktrees de dispatch, .orch-agent-*.log, .orch-run.cmd, estado del supervisor, y todo bajo .sandbox/<seat>/ salvo su README.md.
  • agent-litter -lo que el litter guard (ver Hooks y guards) hubiera denegado si hubiera visto la escritura: un dot-directory o un archivo con forma de scratch/reporte que un agente dejo fuera de .sandbox/<seat>/ o de la carpeta de docs. Esto tambien atrapa los archivos literales nul/con/aux/prn/com1..9/ lpt1..9 que deja una redireccion > nul de bash en Windows -Explorer no puede borrarlos (el sistema operativo intercepta el nombre plano), asi que --apply los mueve o purga usando la ruta extendida \\?\. A mano, desde Git Bash: rm -f ./nul.
  • yours-keep -nunca es un --group valido: orch.db, .orch/gates/user/, .orch/packs/. --apply rechaza este grupo de entrada.

Solo se listan rutas que Orchemax puede tocar o que tienen forma de litter -los archivos normales del proyecto nunca se enumeran. Agrega --json para scriptear contra la misma estructura.

Un archivo compartido que tambien lleva tu propio contenido (AGENTS.md, .claude/settings.local.json) nunca se borra entero: solo se quita la porcion propia de Orchemax, y antes se guarda una copia.

2. Aplicar#

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

Imprime exactamente lo que se moveria, y pregunta Move N item(s) in group(s) …? [y/N] (--yes para saltar la pregunta en un script). Las rutas se mueven a <workspace>/.orch/trash/<timestamp>/, preservando su disposicion relativa, asi que nada se destruye por error -pasa --purge para borrar directo en su lugar.

3. Re-sembrar#

orch init --yes
orch setup --yes --project <path>   # por proyecto, si usas setup por proyecto

init/setup regeneran cada ruta orch-regenerated desde la configuracion viva -para eso existe la separacion de arriba.

4. Que recibe cada proyecto#

  • .sandbox/ -el scratch propio de un seat vive en .sandbox/<seat>/, barrido por el reaper despues de guard.sandbox_days (default 14). Nada de lo que un agente escriba ahi es litter.
  • AGENTS.md + punteros por CLI (GEMINI.md, .github/copilot-instructions.md, .cursor/rules/orch.mdc, el include @AGENTS.md en CLAUDE.md) para que cada CLI conectado lea el mismo digest del workspace.
  • Gates (.orch/gates/README.md + basics/manifest.json) y tus propios overrides en .orch/gates/user/ -nunca los toca clean ni el re-seed.
  • El litter guard, activo por default: un agente puede leer el codigo del proyecto libremente; lo que escriba que no sea codigo del proyecto va en .sandbox/<seat>/ o en la carpeta de docs.

5. Verificacion de aceptacion#

orch harness scan
orch guard litter --count

harness scan confirma que cada CLI conectado sigue resolviendo su puntero AGENTS.md y sus hooks; guard litter --count reporta 0 hits contra el conjunto de archivos cambiados de git.

Desinstalar#

orch uninstall va mas alla que clean: saca a Orchemax de un workspace (o, con --scope user, de la maquina) en vez de solo re-sembrarlo. --dry-run por default; no se borra nada sin un si explicito.

Alcance workspace (default)#

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

Dos pasos, dos confirmaciones separadas (--yes responde ambas):

  1. Borra orch-regenerated + orch-runtime + agent-litter -los mismos tres grupos que workspace clean --apply.
  2. Con una segunda confirmacion explicita, tambien reubica orch.yaml y el resto de .orch/ -incluidos .orch/gates/user/, .orch/packs/ y orch.db- dentro de <workspace>/orch-uninstall-<timestamp>/. Nada aqui se borra directo (--purge opta por eso en su lugar): una ruta "yours-keep" se mueve, nunca se destruye, justamente para que se pueda recuperar.

La salida nombra la carpeta de recuperacion y lista cada ruta "yours-keep" que preservo ahi.

Alcance de usuario#

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

Elimina solo lo que Orchemax mismo escribio fuera de un workspace: ~/.claude/settings.json (los hooks propios de Orchemax y su entrada mcpServers.orch -nada mas de ese archivo), ~/.claude/orch-mcp.json, la entrada mcpServers.orch de ~/.cursor/mcp.json, los trios de skills en home (.claude/.cursor/.commandcode/.config/opencode skills/orch-*), la entrada global de agy en su MCP, el plugin de OpenCode mas su bloque provider.orchemax en opencode.json, y las variables de entorno de usuario que un wire consentido dejo (ORCH_GATEWAY_KEY, OPENCODE_DISABLE_MOUSE). Nunca toca un archivo en el que Orchemax no haya escrito, y ~/.claude/settings.json se respalda (.bak-<yyyymmdd-hhmmss>) antes de reescribirse.

De forma interactiva lista cada archivo que va a tocar y pregunta una vez; --allow-user-scope es obligatorio sin terminal (igual que orch guard wire --scope user) ---yes solo nunca otorga el alcance de usuario.

Relacionados#

  • Hooks y guards -el litter guard y los perfiles de gate sobre los que se construye el inventario de workspace clean.
  • Organiza un workshop -init/setup/project add, los comandos que vuelven a sembrar lo que clean elimina.
  • Worktrees -que es un worktree de dispatch, el mayor ocupante del grupo orch-runtime.