Moving a live setup without breaking it

In one evening I moved an always-on Mac’s whole agent setup to a new layout: background services, every repository, a job queue and the guard rails around them. It worked because the move was a script with a dry run, a journal and a real rollback. It still needed a handful of fixes by hand, and that’s the more useful part of the story.

Why move at all #

The old layout had grown one fix at a time. Projects sat directly in the home folder, each with its own Remote Control server, ten in all, plus a server for the home folder itself that could never start because Claude Code won’t save trust for a home directory. Every attempt to cut down permission prompts fought that layout instead of fixing it.

The new design was simple to describe:

  • one ~/projects folder holding three projects and the setup’s own “Manager” repo;
  • four Remote Control servers instead of ten, running as launch agents with clear, consistent names;
  • a root-owned runner daemon picking jobs from each project’s queue;
  • helpers such as the git wrapper installed root-owned, outside anything an agent can write.

The catch: this was the machine doing real work every night, with repos full of half-finished branches. Moving it was a migration, not a tidy-up.

The cutover script: dry run, journal, rollback #

The move was one shell script with three properties that mattered more than anything it actually did.

  1. A dry run. --dry-run printed every step it would take, every file it would move and every service it would stop, without touching anything. I read it end to end before the real run.
  2. A journal. Each step wrote a line to a journal file and a state file when it finished. If the script stopped for any reason, running it again picked up after the last completed step instead of starting over. --status printed where it had got to.
  3. A real rollback. Before changing anything, it took a dated backup of everything it would touch: launch agent files, settings, the old folders. --rollback replayed the journal backwards and restored them.

The install of the root-owned parts was split out from the move, in two commands: one run with sudo for the system pieces, one as my user for the rest. Each installed from a staged export of one exact git commit, so what got installed was precisely what had been reviewed, not whatever happened to be in the working folder.

Preflight: what it refused to start with #

The most valuable part of the script ran before it changed anything. A preflight check refused to start unless the machine was in a known, quiet state, and on the night it refused several times:

Preflight checkWhat it foundWhat I did
No running agent sessionsRemote Control sessions still aliveStopped them cleanly, re-ran
Every repo cleanA downloaded zip, a stray .DS_Store, a settings backup, a Python cacheMoved the zip to a backup folder, committed a real note, deleted the junk
No detached worktreesA mock-ups worktree on a detached HEADCreated a branch for it and pushed
Worktrees validOne marked prunable, left behind by an agentgit worktree repair, then pushed its branch
Branches pushedLocal-only work in two reposPushed it first

Each of those would have been a silent loss or a mystery later. A dirty repo moved mid-change, or an agent’s worktree orphaned by the new paths, is exactly the sort of thing you discover three weeks on. Refusing to start was annoying for twenty minutes and saved the evening.

The night itself: what the checks caught and missed #

Once preflight passed, the move itself ran cleanly. Then the new services started, and four things went wrong that no check had looked for:

  • A flag the tool no longer accepted. The launch agent template passed a --model option that the pinned Claude Code version rejected with “Unknown argument”. All four servers failed at start-up. I removed the flag from the installed plists with a short Python script, then fixed the template properly in the repo the next day.
  • Trust is per folder. Each new project folder had to be trusted once, by hand, by running claude in it. The design said so; the script couldn’t do it for me.
  • The journal didn’t know about my hand fix. While fixing the plists I’d unloaded the services by hand. The journal still thought they were loaded, so the “start services” step skipped them. I loaded three by hand.
  • A resume flag with nothing to resume. The Manager’s server used --continue to pick up its last session, and on a fresh layout there wasn’t one, so it refused to start. The flag came out.

There was one ordinary snag too: the git hosting wouldn’t show a merge page, because the new main branch didn’t exist on the server yet. One push fixed it.

Lessons #

  • Preflight is worth more than the migration. Most of the value came from refusing to start in a messy state.
  • Resumable beats perfect. A journal meant every stop was a pause, not a restart, and I never had to wonder what state the machine was in.
  • A journal is only as good as its assumptions. It assumes nobody changes things behind its back. If you fix something by hand mid-run, check --status and expect to finish that step by hand too.
  • Patch live, fix at the source. A quick hand edit kept the evening moving; the real fix went into the template and the tests the next day. Do both, or the next install brings the bug back.
  • Test what the services do, not just that the files exist. Every check passed and all four servers still failed, because none of the checks actually started one.
  • Keep the rollback, even when you don’t use it. I never ran it. Knowing it was there is why I was willing to start on a weeknight.

The next morning the new layout ran its first proof job in seven minutes with zero prompts. That is the only test that really counts.