Worktree Atlas

Worktree Atlas is a single-page Electron app for people whose repositories accumulate git worktrees faster than they can track them. Once you start running agents in parallel, wt list stops being a command and becomes an archaeological dig. The app watches every worktree in a repository and reduces each one to a readiness verdict, so deleting a worktree becomes a one-keystroke decision with a reason attached.

Why I built it

I run agents in parallel worktrees with worktrunk. Each agent gets a worktree, and a week of that leaves a dozen-plus entries in the list. Worktrunk tells me the state of each branch relative to main, which is the important part. But it does not know about uncommitted changes, a git operation that is half-finished, a process that is sitting in the directory right now, or a directory that churned in the last few hours. All of that is exactly what decides whether a delete is safe. I wanted one surface that combines all of it into a single answer.

The four collectors

The Electron main process runs four collectors, each a small Effect that shells out to a CLI, and merges their output into one snapshot per refresh.

• Worktrunk runs wt list --format=json --full and normalises across the two schemas worktrunk has shipped, the bare array and the envelope with items.
• Git discovers each worktree’s common directory with git rev-parse --git-common-dir, then reads dirty-file mtimes and in-progress git operations from it.
• Activity polls directory mtimes, breadth-first and capped at 16000 directories. I deliberately do not use inotify, because the per-user kernel watch budget is permanently exhausted by editors, dev servers, and agents.
• OMP reads ~/.omp/agent/sessions/**/*.jsonl, associates sessions with worktrees through cwd and additionalDirectories, and correlates the live ones with /proc. That part is Linux-only, which is where I run it.

The renderer is a single SvelteKit page around one table. That is all the UI is, and it is why the app feels instant.

The readiness model

The verdicts are a deliberately conservative four-state set, ordered by how much I trust my own judgment:

• Main is never a candidate.
• Keep means at least one blocker is present, an unsafe worktrunk state, a dirty tree, a lock, a git operation in progress, a live OMP process, or a branch/worktree mismatch on a non-detached worktree.
• Probably done means no blockers, but at least one caution, activity within the last 24 hours, a worktrunk marker that says an agent is working or waiting, or a recent OMP session.
• Ready to delete means none of the four collectors saw anything that would make the delete a mistake.

The two middle states exist because my first version was binary and I kept overruling it. A 24-hour activity window and an agent marker are not proof that work is in flight, so the app says ‘probably’ and leaves the call to me.

The safety model

The app deletes worktrees, so I built it to match. The renderer runs with contextIsolation: true and a sandboxed preload that exposes a single typed API. Every command goes through spawn(command, argv) with shell: false. When I click delete, the renderer sends the worktree ID, and the main process resolves it against a snapshot it collects fresh at that moment, then runs a plain wt remove. There is no rm -rf, no git branch -D, no force flag, and no free-text path input anywhere in that pipeline.

Where it stands

It is v0.1.0, MIT licensed, one page and one table. I use it daily on the machines where my agents work. The next steps are boring and obvious, a multi-repository view, and per-worktree memory so the table is useful before the first refresh completes.

License

Worktree Atlas is MIT.