A Worktree Is More Than a Branch
Orca’s central design choice is to make each task a real Git worktree, not merely a different branch name. This chapter examines how that choice creates an independent place for an agent to edit, how the starting reference gives its diff meaning, and what must happen to ignored files and setup state before the checkout is genuinely usable. The practical result is a way to run competing agents without asking Git to constantly switch one directory between incompatible working states.
Creation: from a starting reference to an independent checkout
A branch is a name for a line of Git history. A worktree is a directory attached to that history. The distinction is small in Git’s vocabulary and decisive for parallel agent work. With only one checkout, switching from one branch to another changes the files under the feet of the process using that directory. An agent may be reading a file while another operation replaces it, or a developer may stash changes simply to make room for a second attempt. Separate worktrees give each attempt its own files on disk, so the first agent can keep working while the second inspects a different implementation.
Orca begins with a repository and two related reference decisions. The repository has a base ref, usually the branch from which new work normally starts. A particular workspace has a start-from ref: the point from which that attempt should branch. Most tasks use the base ref, but an engineer may instead start from another local branch, an existing remote branch, or a specific commit. This makes the starting point an explicit property of the attempt rather than an assumption hidden in whichever branch happened to be checked out.
That explicit choice matters when alternatives must be compared. Suppose three agents are asked to fix the same bug. If all three worktrees start from the same commit, differences in their diffs mostly reflect their approaches to the prompt. If one starts on top of a branch containing an unrelated change, a difference in the final patch may come from the starting state instead. Orca does not eliminate that possibility; it gives the operator a place to state the choice and a worktree against which the result can be inspected.
The creation path therefore does more than make a directory. It resolves whether the requested base exists locally or as a remote-tracking reference, refreshing it when necessary. It chooses a workspace path and branch name, asks Git to create the worktree, and records the effective base for later context. For a new branch, Orca uses Git’s worktree creation mechanism without automatically inheriting the base branch’s upstream relationship. That prevents a new, not-yet-published attempt from looking as though it is already behind or ahead of a remote branch it does not yet represent.
The absence of an inherited upstream is a truthfulness decision, not just a Git preference. Before the first push, the branch may have no meaningful remote counterpart. If the new worktree automatically borrowed the base branch’s tracking relationship, status displays could describe the wrong comparison. Orca can configure push behavior so a first ordinary push establishes the appropriate upstream later, while the initial work remains legible as an unpublished attempt.
That small distinction prevents a common category error. “Behind” can mean behind a branch that this task is actually based on, or it can merely reflect a tracking setting copied from somewhere else. The first statement may call for a rebase; the second is configuration noise. In a multi-agent race, status noise is especially costly because the operator is already comparing several branches. A worktree should make the state of one attempt clearer, not add an invisible relationship that has to be mentally subtracted.
This is also why a worktree can be a useful review unit. The operator can compare it with its start-from ref, stage changes by file or hunk, and later commit or push the branch. Git remains the authority for history. Orca’s metadata adds the context needed to answer “what did this task begin from?” without replacing Git’s answer to “what commits exist?” The result is a clean division of labor: Orca remembers the task context, while Git continues to tell the truth about the files and commits.
The separation is especially valuable when the attempts are not all going to survive. A winning worktree can become the branch that receives review and a pull request. The other worktrees can be archived or deleted, with their branches removed when Git confirms that doing so will not discard unmerged commits. If Git preserves a branch because it may contain work that has not been merged, that is a useful interruption: cleanup has reached a history boundary that deserves an explicit decision.
A worktree also preserves ordinary escape hatches. Developers can open a terminal in it and use git status, rebase, cherry-pick, or other familiar commands. Worktrees created outside Orca can be shown in the application as well. This matters for adoption because the coordination layer does not require the repository to become an Orca-only environment. The more important the code, the more useful it is to know that the underlying workspace can still be understood and repaired with standard Git tools.
Usable isolation: what must cross the worktree boundary
A new worktree is clean with respect to tracked files. That cleanliness is the source of its independence and the reason it may not run immediately. Modern repositories often keep dependencies, build caches, local configuration, and environment files out of version control. A second checkout can therefore have the right source code and still fail at the first install, test, or development-server command. Orca treats this as an environment policy that must be made explicit rather than pretending that Git can copy what Git intentionally ignores.
There are three different answers to the ignored-state problem. A directory such as a dependency tree or cache may be shared from the primary checkout, often through a link or platform-specific sharing mechanism. That saves space and setup time, but the agents then see a common mutable resource. A local configuration file may instead be copied into each worktree so each attempt owns its version. That avoids direct file sharing, but changes made in the primary checkout will not automatically appear in existing copies. A setup hook may recreate the environment on demand, which favors repeatability but spends time and can fail for reasons outside the agent’s code change.
Consider a repository with a large dependency directory, a generated build cache, and a local file containing a service endpoint. Sharing the dependency directory may be sensible if installing it three times would dominate the experiment. Sharing the build cache may be less sensible if agents can invalidate or rewrite entries in incompatible ways. Copying the endpoint file preserves each attempt’s local configuration, but it can also copy credentials or stale assumptions. Recreating the environment through a hook may be the most repeatable choice, yet a hook that requires a missing tool or a private package registry becomes a separate failure surface. The right answer depends on whether speed, independence, or repeatability matters most for that task.
Orca’s repository and user settings separate those choices. Per-repository shared paths can materialize selected directories in new worktrees. A checked-in configuration can declare ignored directories that should be shared for the project, such as dependencies or caches. A separate include file can name literal ignored files or directories to copy, such as local environment configuration. The distinction between “share” and “copy” is not cosmetic. It tells the operator whether two agents will observe the same mutable directory or receive independent material.
The constraints protect the meaning of the feature. Shared-directory entries must be directories that exist in the primary checkout and are actually ignored; tracked or missing paths are skipped. Include entries must also be ignored and literal; wildcard and negation patterns are not treated as a hidden path language. These rules limit surprise, but they also mean that a repository cannot assume every local file will follow the worktree. Teams still need to decide which state is safe to regenerate, which belongs only to a developer, and which must never be copied casually.
Setup hooks address the other half of the problem. A repository can ask Orca to run a command after a worktree is created—for example, installing dependencies, activating an environment, or restoring a local configuration. Agent-specific conventions remain in place as well: Orca reads the repository’s agent configuration and leaves instruction files such as CLAUDE.md or AGENTS.md under the agent’s ownership. This lets the new workspace inherit project guidance without turning that guidance into an Orca-specific copy of the repository’s rules.
The hook is useful because it puts environment preparation close to the moment of creation. It is also a boundary that deserves attention. A setup command is executable behavior supplied by the repository or its configuration. It can take time, require network access, depend on machine credentials, or fail after the Git worktree itself has been created. Orca can surface setup progress and warnings, but the operator must still distinguish “the checkout exists” from “the development environment is ready.” A failed setup should not be silently interpreted as an agent failure, and a successful setup does not prove that the code is correct.
For a three-agent race, this distinction helps localize a failure. If one worktree cannot install dependencies while the other two can, the first question is about environment parity, not necessarily about the agent’s proposed fix. If all three pass setup but only one test suite fails, the evidence points somewhere else. Conversely, a shared cache can make all three appear healthy while masking a common environmental assumption. Orca exposes the lifecycle around these steps; the developer still has to compare like with like.
Sparse checkout introduces a related trade-off. Selecting only particular repository-relative directories can reduce the material an attempt needs, but it also changes what the agent can see. That may be appropriate for a large repository or a focused task, yet it can hide a dependency that the agent would otherwise discover. The narrower the checkout, the more important it becomes to know what the task requires and to treat an apparently clean result with appropriate caution.
These choices show why a worktree is an isolation boundary, not a security sandbox. Git separates tracked files and branch histories. It does not prevent an agent from accessing other paths, using available network resources, reading credentials, or modifying a shared cache. Nor does it isolate a test database or remote service merely because the source code lives in a separate directory. Orca’s own agent documentation warns that permission-bypass launch defaults can let a trusted agent act without individual confirmations. File separation reduces accidental interference; it does not define what the process is allowed to do.
That distinction is important when a worktree contains copied local configuration. Copying a file can make a test runnable, but it can also replicate a credential or a connection to a shared service. A link can avoid duplication, but it makes the dependency visible to every attempt. Neither choice answers whether the agent should be allowed to use that service. Permission settings and environment design remain separate controls, and the safest choice for an exploratory task may be to use manual approvals or a disposable service rather than to rely on the worktree boundary.
The same precision applies to deletion. Removing a worktree can clean up an experiment, but deleting a directory is not the same as proving that its branch is disposable. Orca removes the on-disk workspace and lets Git’s unmerged-history checks determine whether the branch can also go. A preserved branch is not a failure of isolation; it is the system refusing to turn workspace cleanup into silent data loss. In other words, lifecycle cleanup has two objects to account for: the files that occupy space and the history that may still contain knowledge.
The durable lesson is that Orca’s parallelism starts with a very ordinary Git object used carefully. A worktree gives each agent an addressable, inspectable filesystem and a branch whose ancestry can be named. The cost is that dependencies, local state, permissions, and setup must be designed rather than assumed. Once that independent checkout exists, a new problem appears: the files are separate, but how does the operator know whether the agent inside each worktree is working, waiting, or gone? That is the role of the next layer, the observable agent session.