---
{
  "n": 61,
  "title": "Worktrees across a folder of repositories",
  "abstract": "Proposal: launching with a worktree from a folder that holds several git repositories gives each repository its own worktree, side by side in one working folder.",
  "refs": [],
  "seen": [
    "agent"
  ],
  "data": {
    "revision": 1,
    "change": "written; added What you asked for; added How a worktree is made today; added The idea: one working folder, a worktree per repository; added How the agent gets there; added What the journal does with it; added Steps; added Open points"
  },
  "created": 1790332603.3383539,
  "updated": 1790332604.4626298,
  "deleted": 0.0,
  "completed": 0.0,
  "outcome": "",
  "type": "doc"
}
---
Proposal for to-do 1817, from message 10957. Not built yet.

## What you asked for
worldwatchmarket is a folder, not a git repository, holding four: chronos, dullahan, help-center and site. Starting the journal there with a worktree should give every one of them a worktree of its own, on one branch name, so an agent works across all four the way it works in a single project's worktree today. The same should hold for a folder that is a repository itself but carries other repositories inside it.

## How a worktree is made today
journal claude -w NAME hands --worktree NAME to Claude, and Claude runs git worktree add in the folder it starts in. That needs the folder to be one git repository, so in worldwatchmarket it fails. Around it the journal keeps each worktree's branch under refs/journal/worktrees/NAME, links the worktree's .journal to the project's, links the skills in, and for tickets branches from the board's branch and merges back. All of that assumes one repository.

## The idea: one working folder, a worktree per repository
A worktree NAME of a folder of repositories is one working folder, .claude/worktrees/NAME, that mirrors the parent: for every repository in it (found by its .git, one level down, and deeper only when asked), a git worktree of that repository on the branch worktree-NAME, at the same place it has in the parent (NAME/chronos, NAME/dullahan and so on). Everything the agent reads at the top, such as CLAUDE.md, AGENTS.md, .mcp.json and the skill folders, is linked in, and .journal is linked to the project's journal as for any worktree. When the parent is a repository itself, it gets its worktree first and the inner repositories are placed inside it, kept out of the parent's git through its exclude file.

## How the agent gets there
Claude has two hooks for exactly this: WorktreeCreate, which makes the working folder and prints where it is, and WorktreeRemove, which takes it away. The journal registers both. In a single repository they do what git would do, so nothing changes there. In a folder of repositories they build the working folder above. Codex has no such hook, so for Codex the journal makes the working folder before the launch and starts Codex in it.

## What the journal does with it
One engine function lists the repositories of a worktree, and everything that touches git goes through it: keeping each branch's last commit (refs/journal/worktrees/NAME in each repository), bringing a removed worktree back, and for tickets: branching every repository from the board's branch, checking whether the ticket is merged (every repository that changed must be merged, and one with no commits on the branch counts as done), and journal ticket merge merging each repository in turn and stopping at the first conflict, naming the repository. A board's branch is then the branch name used in every repository.

## Steps
1. The engine finds the repositories of a folder and makes, keeps and removes a worktree across them. 2. The WorktreeCreate and WorktreeRemove hooks, and the Codex launch, use it. 3. Tickets branch, check merged and merge per repository. 4. The viewer shows a worktree's repositories and each one's branch state on the ticket and the environment. 5. One test in the worktrees feature: a folder with two repositories gets a worktree in each, kept and removed together.

## Open points
- Every repository in the folder, or only the ones you pick at launch? My pick: every one, and a setting that leaves some out.
- A ticket that changes two repositories: merge both or neither? My pick: merge one by one and stop at a conflict, since git has no merge across repositories; the ticket stays open until every one is merged.
- Repositories deeper than one level: only when a setting names them.