The Two-Minute Gap

The root scan runs every two minutes. It walks the configured directories, finds repositories, resolves their worktrees with git worktree list, and ensures a history store for every one it has not seen. That is a reasonable cadence for finding projects. It is the wrong cadence for a worktree I just created.

The first version made me wait. I ran git worktree add, opened the UI, and the worktree was not there. Two minutes later it appeared, with its history store and copy rules. The recorder was not slow; the registry was. In the meantime the worktree had no .env, no snapshot, and no timeline.

Watch the Metadata, Not the Files

Git writes a directory per linked worktree below <common-dir>/worktrees. That directory is the registry. Tachograph polls it for every known project every two seconds, debounces a change by 600 ms, waits for any scan already running, and then triggers a full scan.

The debounce is not decoration. git worktree add creates the metadata before the checkout is complete. A scan that starts immediately can see a directory that is not yet usable. Waiting 600 ms and letting the existing scan finish turns a race into a registration.

A new worktree now appears with its history store, copy rules and recorder in about two seconds. Removing it disappears just as quickly: the next scan sees the missing path, removes the placeholder and the snapshot branch, and forgets the activity entry.

The Fallback Still Matters

The metadata watcher only knows about projects the app already has. A brand-new project—a repository created under a root—is still found by the root scan, and that is fine. The watcher is not a replacement for discovery; it is a short circuit for the case discovery is worst at.

Discovery and detection stay separate jobs: watchexec triggers the snapshots, the registry poll decides when a worktree becomes known, and the root scan remains the slow net underneath both.

The cost is one ReadDir per project every two seconds. That is cheap enough to run continuously and simple enough to reason about. It is the same pattern as the polling fallback: a small, boring loop that makes the visible behavior feel immediate.

The last entry is about what all of this costs, and what is still missing.

A timer is a promise about the worst case, not the typical one. Watching the registry makes a worktree part of the history in the minute it was created instead of the minute a scan happened to run, and leaves the root scan to do what it is good at: finding projects nobody told the app about.