Keep Your Coding Agent in Its Own Git Worktree
A coding agent can start in the right directory and still edit the wrong checkout. Shell commands can change directories, editor tools can receive absolute paths, and scripts can reach outside the repository. A Git worktree gives the agent a separate checkout and index, but it is not a security boundary. Use this walkthrough to make the intended boundary explicit and enforce it where possible.
1. Create a dedicated branch and worktree
From your existing repository, run these commands separately, replacing the paths and task name with your own:
git -C /work/repo status --short
git -C /work/repo worktree add -b agent/fix-parser /work/repo-agent HEAD
The status check makes existing changes visible. The new worktree starts from the current commit; it does not copy uncommitted changes. Give each concurrent agent its own branch and directory. Avoid options that force the same branch into multiple worktrees: that removes a useful guardrail.
2. Launch the agent from the verified root
Open a fresh terminal, change to /work/repo-agent, and verify the checkout before launching Claude Code, Codex, or Gemini CLI:
cd /work/repo-agent
pwd -P
git rev-parse --show-toplevel
git branch --show-current
The physical directory and Git root should identify the intended worktree, and the branch should be agent/fix-parser. Check for inherited GIT_DIR, GIT_WORK_TREE, or GIT_INDEX_FILE environment variables; unset unintended overrides before proceeding.
If your agent uses CodeRelay Hub, keep that API configuration separate from the checkout boundary. Routing requests through one endpoint does not restrict which local files the agent can access.
3. Write the agent a tightly scoped brief for this worktree
Put a short instruction in the agent's launch prompt or supported instruction file: “Work only in /work/repo-agent. Do not edit sibling checkouts, switch branches, remove worktrees, or change repository configuration. Ask before accessing paths outside this root.”
Also name the expected task, permitted test commands, and completion criteria. Instructions reduce accidental drift, but they are not enforcement. Repository content, generated output, and tool responses must not be allowed to redefine the approved root.
4. Enforce paths at the tool boundary
Configure the runner's filesystem sandbox or tool wrapper to permit writes only inside the worktree and explicitly approved temporary directories. For file tools, resolve relative paths against the fixed root, normalize them, and reject paths that escape it. Account for symlinks; a simple string-prefix check is insufficient.
For shell tools, set the working directory on every invocation rather than trusting a previous command's directory. However, setting the working directory does not stop absolute paths or commands such as cd ../repo. Use an operating-system sandbox or container for actual enforcement, including subprocesses and redirected output.
5. Handle Git's shared metadata deliberately
A linked worktree usually contains a .git file pointing to administrative data elsewhere. Worktrees share repository objects, refs, and some configuration, while retaining separate indexes and HEAD state. Consequently, allowing writes only under /work/repo-agent may prevent even normal Git operations.
Choose a policy explicitly:
- Edit-only agent: Let the agent modify files and run sandboxed tests. Have a trusted controller perform staging, commits, and other Git operations.
- Git-capable agent: Grant carefully scoped metadata access, understanding that shared repository state remains reachable.
- Untrusted execution: Use a disposable clone in an isolated environment instead of relying on a linked worktree for containment.
6. Review changes and clean up safely
Before accepting the result, inspect the branch, status, and diff from a trusted terminal:
git -C /work/repo-agent status --short
git -C /work/repo-agent diff --stat HEAD
git -C /work/repo-agent diff HEAD
Review untracked files separately because they do not appear in that diff. Run the relevant tests under the same isolation policy. Also check your original checkout against its initial status; it should have no unexpected changes.
After reviewing and preserving the work, stop the agent and remove the checkout with git -C /work/repo worktree remove /work/repo-agent. Do not force removal merely to bypass uncommitted changes.
Open a free workspace on CodeRelay Hub.