Cleaning Up Agent Worktrees Without Losing Work
Cleaning Up Agent Worktrees Without Losing Work. A safe removal checklist: merged branches, uncommitted diffs, and Ferryx-managed paths you should never delete blindly. Built for parallel AI agent workflows.
What worktrees own
The manual workaround for parallel agents is cloning the repository once per agent. Clones drift apart, remotes multiply, and upkeep is easy to forget. Worktrees keep one history while giving each agent an independent index and working tree, which ends both merge chaos and index.lock contention. In the specific case of “Cleaning Up Agent Worktrees Without Losing Work”, the Ferryx angle is straightforward: a safe removal checklist: merged branches, uncommitted diffs, and ferryx-managed paths you should never delete blindly. built for parallel ai agent workflows. Teams evaluating this often arrive from a shared-checkout pain story or from tooling that treats the terminal as a disposable window. Ferryx takes the opposite stance—sessions are daemon-owned, isolation is a first-class action, and everything you need to verify sits behind documented surfaces.
Merge-then-remove order
A Git worktree is a second working directory attached to the same repository. Ferryx manages them under .orca-worktrees/wt-<slug> with branches named orca/<workspace-id>/<slug> and jails every path to the repository root. Applied to “clean up agent worktrees”, that context matters because the failure modes people search for are almost always failures of ownership or visibility rather than of raw rendering. When the process outlives the window, when the buffer can prove what it missed, and when each agent’s files live in a jailed worktree, the same task that used to require three clones and a spreadsheet becomes a pane layout you can read at a glance.
Practical steps
- Confirm the repository is clean enough to branch (committed or intentionally dirty state you understand).
- Create a managed worktree from Ferryx (or
git worktree addif you are doing it by hand) with a descriptive branch name. - Point the agent at that worktree path and start work; the shared
.githistory means fetches apply everywhere. - Diff and review from the main checkout with
git diff main...<agent-branch>before merging. - Remove the worktree only after the branch is merged or explicitly discarded:
git worktree removeplus branch cleanup.
| Checkpoint | What good looks like |
|---|---|
| Isolation | Each parallel actor has its own worktree or a documented reason not to |
| Visibility | Status badges or attention counters answer “who needs me?” without polling |
| Persistence | Closing the window does not end agent processes |
| Evidence | Claims map to product facts or a linked source |
How this fits Ferryx today
Ferryx ships calendar-versioned releases for macOS (universal DMG), Windows (x64 installer), and Linux (AppImage and .deb). The desktop shell, daemon, and optional ferryx-cli headless binary are described with sources on the product facts page. If you are new to the workspace model, start with the introduction; if you want the mechanical details of sessions and replay, read technical architecture.
Related reading:
FAQ
How is a worktree different from a clone?
A clone copies the whole repository. A worktree adds a working directory that shares the same object database and refs, so it is cheaper and stays in sync.
Where does Ferryx put managed worktrees?
Inside the repository under .orca-worktrees/wt-<slug>, jailed to the repository root so paths cannot escape the project.
How do I clean one up safely?
Merge or discard the branch first, then remove the worktree through Ferryx or git worktree remove. Never rm -rf a directory that still has unmerged commits.
Limits and non-goals
Ferryx is early software: core flows work, but expect rough edges and breaking changes between calendar-versioned releases. Some OS integrations remain platform-specific (Dock badge counters and launchd supervision are macOS-only today), Windows builds are not code-signed yet so SmartScreen warns on first run, and remote features assume you control the host and pairing grants. None of that changes the core claim of this post—daemon-owned sessions, managed worktrees, and visible multi-agent workflows—but it is the honest boundary of what has shipped. Verify anything version-sensitive against the facts page and the release notes before you standardise a team workflow on it. If something in this guide disagrees with your build, trust the repository sources linked from product facts and open an issue with your version string attached.
How to verify these claims
Every concrete statement in this post ties back to a checkable surface: package names and license terms live on product facts, session and buffer behaviour is described in technical architecture, and keyboard bindings are listed under shortcuts. Where a third-party tool is mentioned, treat vendor docs as authoritative for that tool and re-check dates before quoting them in a decision document. That discipline is why this site does not publish performance benchmarks it has not measured: reproducible architecture facts age better than marketing numbers.