Work Across Environments and Worktrees

A modern project may exist as source in Git, one or more local checkouts, a running development process, a generated build, a shareable preview, an installed application, and a production deployment. A customer may be using yet another persisted version. These layers can drift. A change visible in one says nothing automatic about the others.

Name the layer in every task and receipt. 'The source contains the fix' is a source claim. 'The local page works' is a runtime claim. 'Version 123 is receiving production traffic' is a deployment claim. This vocabulary prevents a large class of false completion reports.

A local task works with files and tools on the user's machine, subject to its sandbox and permissions. It may rely on installed runtimes, local databases, environment variables, cached dependencies, or native applications. Record those dependencies rather than assuming every collaborator has the same setup.

Local convenience can hide production differences. A development server may use mock data, a permissive login, or a local port that does not exist after deployment. Verification must name which dependencies were real and which were substituted.

A cloud task runs in a hosted environment configured for that task. It can work independently of the laptop and is useful for isolated or longer-running work, but it does not automatically see local uncommitted files, local-only services, or credentials stored on the machine. Setup instructions must make required dependencies reproducible without exposing secrets.

Treat cloud output as a proposed change until it is reviewed and integrated into the intended branch. A successful hosted test proves the hosted setup and commit, not the state of a developer's local checkout or the production service.

A Git worktree is another working directory attached to the same repository history. It lets one task work on one branch while another task or human uses a different directory and branch. This is safer than having two agents edit the same files in one checkout and cheaper than repeatedly cloning the full repository.

In the desktop app, choose Worktree beneath the composer, select the starting branch, and submit the task. Codex creates a managed worktree, initially in detached HEAD state. Use Create branch here if the work should remain in that worktree, or use Hand off to Local when you want the chat and changes moved into the foreground checkout for your usual IDE or single-instance runtime. Do not try to check out the same branch in two worktrees; Git rejects it by design.

Isolation is not automatic coordination. Give each worktree a clear owner, file scope, and acceptance test. Shared external resources such as databases, ports, caches, or generated directories can still collide even when files do not. Assign separate test data or runtime ports where needed. If a managed worktree needs an ignored local setup file, `.worktreeinclude` can list it for copying, but every listed secret-bearing file widens exposure and must follow the project's credential policy.

Stay in the managed worktree when its dependencies and tools are reproducible there. Use Open to inspect that worktree in an IDE, run its own development process, and choose Create branch here before committing or opening a pull request. Keep the branch attached to that worktree while it is active.

Use Hand off to Local when you need the foreground environment: a running service that can exist only once, a native simulator, a local-only dependency, or the exact IDE setup already open. Handoff performs the Git movement and preserves the chat. Before and after handoff, compare `git status --short`, the branch or detached state, and the changed file list so the transfer itself has a receipt.

Before combining parallel work, compare each branch with its base, review every changed file, and rerun checks on the integrated result. Two branches can pass separately and fail together because they changed a shared contract, dependency, route, or schema.

Keep the original worktree until integration is proven or a clear recovery point exists. Removing an isolated checkout too early discards convenient evidence about what happened, even if the commits remain recoverable. Cleanup belongs after integration and receipts, not before.