Skip to content

feat(local): clean uninstall that restores configs to pre-spawn state#3380

Closed
AhmedTMM wants to merge 1 commit intoOpenRouterTeam:mainfrom
AhmedTMM:local-clean-uninstall
Closed

feat(local): clean uninstall that restores configs to pre-spawn state#3380
AhmedTMM wants to merge 1 commit intoOpenRouterTeam:mainfrom
AhmedTMM:local-clean-uninstall

Conversation

@AhmedTMM
Copy link
Copy Markdown
Collaborator

@AhmedTMM AhmedTMM commented May 1, 2026

Summary

  • Snapshots agent config files spawn writes during spawn <agent> local so they can be reverted on uninstall.
  • Adds spawn local-restore [agent] to revert config writes outside an uninstall flow.
  • Wires a default-on checkbox into spawn uninstall ("Restore local agent configs to pre-spawn state") whenever snapshots exist.

Addresses Spawn CLI Feedback survey response: "you need a clean uninstall that restores configs to how they were prior."

How it works

  • Manifest at ~/.config/spawn/local-backups/manifest.json records {destPath, backupPath, existed, agent, timestamp} for each tracked write.
  • local/local.ts uploadFile() snapshots its destination before copying, gated on setBackupAgent() so sandbox/Docker mode is skipped (writes happen inside the container).
  • local/main.ts snapshots ~/.bashrc / ~/.zshrc / ~/.profile / ~/.bash_profile plus a per-agent list of paths spawn writes via raw shell (currently ~/.claude.json, ~/.claude/CLAUDE.md) up front so files written outside uploadFile() are still recoverable.
  • Restore: pre-existing files are restored byte-for-byte; files spawn created from scratch are removed; manifest entries are dropped on success.

Test plan

  • bun test — 2075 pass (7 new tests in local-backup.test.ts covering snapshot, restore, idempotency, agent filtering, corrupt manifest, cleanup)
  • biome check src/ — 0 errors
  • Manual: run spawn claude local on a host with a pre-existing ~/.claude/settings.json, then spawn uninstall → confirm settings.json is byte-identical to the original
  • Manual: run spawn codex local on a host with no ~/.codex/, then spawn local-restore codex → confirm ~/.codex/config.toml is removed

🤖 Generated with Claude Code

When users run `spawn <agent> local`, spawn writes config files (e.g.
`~/.claude/settings.json`, `~/.codex/config.toml`) directly to the
user's machine. Previously `spawn uninstall` left those edits in place
— survey feedback called this out as a missing piece.

This snapshots config files before spawn overwrites them and adds a
restore path:

- `local/backup.ts` — manifest at `~/.config/spawn/local-backups/`
  recording `{destPath, backupPath, existed, agent}` per write
- `local/local.ts` `uploadFile()` snapshots its destination first
  (gated on a `setBackupAgent()` call so sandbox/Docker mode skips it)
- `local/main.ts` snapshots shell rc files and a per-agent list of
  paths spawn writes via raw shell (e.g. `~/.claude.json`) before
  install begins
- New `spawn local-restore [agent]` command reverts the writes:
  pre-existing files are restored byte-for-byte; spawn-created files
  are removed
- `spawn uninstall` now lists "Restore local agent configs" as a
  default-on checkbox when snapshots exist

Bumps CLI to 1.1.0 (new user-facing command).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@AhmedTMM
Copy link
Copy Markdown
Collaborator Author

AhmedTMM commented May 1, 2026

Closing — different direction. The right fix for local-cloud config pollution is to sandbox all local runs (Docker/OrbStack) so spawn never writes to the host in the first place, rather than tracking + reverting writes after the fact. The --beta sandbox path already does this; making it the default obsoletes this PR.

@AhmedTMM AhmedTMM closed this May 1, 2026
@AhmedTMM AhmedTMM deleted the local-clean-uninstall branch May 1, 2026 19:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant