No. 10 devlog
One Robot per Worktree
My team is several copies of the same robot, and they all work in one repository.
Where the code comes from told the story: two AI sessions once collided in the same folder, and the fix was one working folder per stream of work. This is how that is set up. If you run more than one agent in a repository, or one agent and a human, it is the part worth stealing.
One history, many folders
Git's answer is the worktree. git worktree add attaches another
working folder to the repository you already have. It shares the history,
the branches, and the objects on disk, and keeps its own checked-out files
and its own idea of which branch it is on. A clone would give you that too,
with a second repository to keep in sync. A worktree is more like a second
desk in the same office: everything permanent is shared, and only the papers
on the desk are yours.
Two sessions, one folder
An AI session edits fast, switches branches freely, and does not know another session exists. Two of ours managed to commit one stream's half-written notes onto an unrelated branch. Nothing was lost that time.
The four things git will not do for you
A new worktree holds exactly what git tracks, and what a project needs to run is usually untracked on purpose. Here there are four things, and each one fails in a way that does not point back at its cause.
- The secrets. The app reads its keys from an env file that never touches git. The type checker resolves those imports, so a worktree without the file reports type errors in code you never touched.
- The dependencies. Installed with
npm ci, nevernpm install. A newer npm rewrites the lockfile, the file that pins every dependency's exact version, and that rewrite has broken the production deploy twice.npm cireads the lockfile and never rewrites it. - The safety net. The pre-push hook that runs the tests does not follow you into a new worktree. Nothing fails and nothing warns. The net is simply not there on the day you need it.
- The Python environment. The content pipeline's private folder of Python packages is gitignored, so a fresh worktree falls back to the system Python and the pipeline's tests fail on a missing package. It gets linked from the main checkout instead of rebuilt.
So a small script does the git part and then all four, every time. It finds the main checkout by asking git where the shared history lives, so running it from inside a worktree cannot nest worktrees or copy secrets from the wrong place. And it reuses a branch that already exists, because work usually starts in the main checkout and only later earns its own desk.
Name tags
Parallel copies make it hard to tell three dev servers apart. Each worktree's dev server gets its own port, and a clash fails loudly instead of quietly serving the wrong branch. During development the footer also wears a name tag.
The footer, on a dev server
The version is there because of an older, dumber bug: it used to be typed by hand and drifted a patch behind. Now it is read at build time from the one file that knows it.
The habits
One stream of work per worktree, never two. The main checkout stays on main, clean, and is used only for merging and for cutting new worktrees. A merged stream's worktree gets deleted, because the history was never in the folder. All of it is in the repository's house rules, so the robot reads it too, and it now refuses to build things in my main checkout.