In-repo .worktrees/ mode support discussion

[brennanb2025]

First off — thanks to @sasha-id for putting #388 together. It's a thoughtful contribution with a real design doc, and the underlying use case (co-located worktrees so tooling picks up repo config naturally) is legitimate. Moving the conversation here so we can decide whether to ship this feature, and so the tradeoffs are visible to the whole team rather than buried in PR review.

The PR proposes an optional mode where worktrees are created inside the repo at <repo>/.worktrees/<name> instead of the configured external workspace directory.

Arguments in favor

• Co-location. AI agents, linters, editors that walk up the directory tree automatically pick up repo-level config (CLAUDE.md, .prettierrc, tsconfig.json) without symlinks or re-configuration.
• Navigation. Keeps related work next to the repo instead of scattered across a shared workspace dir.
• Some user demand. A few external reports requesting this, though nothing with heavy traction.

Arguments against

1. Silent search failure (the serious one)

With .worktrees/ gitignored, any agent tool built on ripgrep at the main repo cwd silently returns zero results for strings that exist in sibling worktrees — while Glob still returns the files. That's logically impossible state from the agent's perspective, and it leads to confident wrong answers.

Reproduced locally:

Tool call at main repo cwd	Result
rg SENTINEL_FOO (string in a worktree)	no matches
Glob **/*.ts	returns the worktree file

The agent concludes the symbol doesn't exist and may duplicate it, skip a refactor it already did, or confirm a regression that didn't happen. Cursor users hit exactly this on the Cursor forums when indexing nested git repos.

2. Spawn-inside-worktree dodges it for routine work, but not everything

Orca spawns agents inside their worktree, and from there Grep works correctly. But the failure still bites:

• Users who run Claude Code / Cursor themselves at the main repo root
• Any Orca feature whose cwd is the main repo (global search, cross-worktree ops)
• A future orchestrator-style feature (agents coordinating across worktrees) — these by definition operate above any single worktree

3. Tooling leakage via upward config resolution

Config resolvers (prettier, ESLint, tsc, Node's require) walk up the directory tree. From inside a nested worktree, they walk into the main repo and resolve config/deps from whatever state main has checked out. This is usually desired for shared root config — but it means every worktree is implicitly coupled to main's state, including in-progress changes on main's current branch.

In external mode, walk-up hits the workspace dir (no config), so worktrees are hermetic.

Verified reproductions:

• Worktree without .prettierrc → resolves main's .prettierrc
• Worktree without node_modules → resolves from main's node_modules (possibly different versions than worktree's package.json)

4. git clean -ffdx footgun

git clean -dfx at the main repo is blocked from removing nested worktrees (shows "Would skip repository"), but git clean -dffx (two -f) recursively deletes them. Agents asked to "clean stale build artifacts" can and do run -ff. In external mode, worktrees are out of the repo's reach.

5. fs.watch storms

Recursive watchers at the main repo (tsc --watch, vite, jest --watch) fire on every file change in any active worktree, scaling with number-of-worktrees × change-rate.

6. Conductor shipped this, then moved away from it

Conductor used to place workspaces inside the repo and later moved them out. Their public Nested source directories doc cites:

• "Some dev tools have trouble with nested source directories."
• The external location helps "prevent agents from getting confused about where to edit files."
• "No more need to add .conductor to gitignore or exclude it from your build tools."

The first two are exactly the failure modes above. Worth knowing a direct competitor already walked this path and walked back.

Spawn-safety ≠ orchestrator-safety

Our current spawn-inside-worktree model keeps agents safe for single-worktree work, and the orca CLI covers cross-worktree needs without filesystem traversal. The problem is what happens when someone wants an orchestrator above multiple worktrees — or, further out, above multiple repos.

An orca-CLI-driven orchestrator is technically possible: an agent that never touches the filesystem outside its own worktree and coordinates everything through orca commands. But in practice that's a hard sell. Orchestrators are exactly the shape of agent most likely to reach for filesystem tools (Grep, Glob, find, tree walks) to explore what the worktrees or repos under them actually contain. Forcing everything through the CLI means either (a) the CLI has to grow surface area to cover every question an orchestrator might ask, or (b) we rely on agent priors to always choose the CLI path — which they don't.

In external mode, a god-view orchestrator can just traverse the workspace dir naturally — every worktree is a sibling directory, every repo is a sibling directory one level up. Grep and Glob agree. Config walk-up doesn't leak. In in-repo mode, the orchestrator's cwd sits at (or above) a repo whose .worktrees/ is gitignored, and the filesystem view it gets is silently wrong.

So: orchestrator stays possible with in-repo mode via the CLI, just harder to build well and harder to give agents tools that "just work" without precise instruction.

The question

Should we support in-repo worktrees at all?

• Ship as opt-in. External remains default. Accept the footguns for users who ask for it.
• Decline. Keep external-only until or unless the demand grows.

I lean toward declining given the silent-failure class of bugs, especially with orchestration potentially on the roadmap, or possible for users, who may have issues with this decision. Would love to hear what others think though, especially from @sasha-id on whether any of the failure modes above have mitigations I'm missing.

Thanks!

[hatton]

I just spent 20 minutes trying to figure out how to make Orca create new worktrees in my existing <project>.worktrees directory. So it'd be great if it was easier to find out that it's not possible. The major con for me that now I'm going to have this set of existing worktrees that is separate from the ones in Orca, which raises the cost a bit for experimenting with/getting started with Orca.

[nwparker]

@hatton could you give a few path examples of what directories you were trying? Just so can be sure we're 100% on the same page.

I can chat w/ @brennanb2025 to see what we can do here to improve things