Set up a Git worktree for a coding agent.
A new worktree is a checkout with none of your local setup. Sort out dependencies, untracked config, ports and databases before an agent builds and tests there.
What a new worktree is missing
A worktree contains your repository's tracked files and nothing else. Everything Git ignores stays behind in the checkout it came from:
- Dependencies:
node_modules,.venv,vendor. - Local configuration:
.envand its variants. - Build output and caches:
target,dist,.next.
An agent started in that directory fails on its first build or test, and then spends tokens working out why. Fill these in before the agent starts. Worktrees share files only through Git, so anything running outside the directory, such as a dev server or a database, needs its own decision too.
Dependencies: install, clone or link
Install them again. Running npm ci, pnpm install or uv sync in the new worktree always gives a correct result. It costs time and network on every worktree, unless your package manager keeps a shared store: pnpm, for example, links packages from one store on disk, so a second install is quick.
Clone them copy-on-write. On a Mac's APFS volume, a copy-on-write clone shares the original's data on disk until either side changes a file, so it takes almost no extra space. cp -c clones file by file:
$ cp -c -R node_modules ../atlas-fix-flaky-poll/Each worktree then has its own copy, so an agent that installs a package in one doesn't touch the others.
Don't symlink them. A symlinked node_modules costs nothing, but every worktree shares it, and two agents running an install at the same time can corrupt it for both. Symlink only a directory nothing writes to.
Build output is usually better rebuilt than copied, since it can be large and the build puts it back. For Rust, CARGO_TARGET_DIR can point every worktree at one shared target directory; Cargo locks it during a build, so worktrees building at the same time take turns.
.env files: copy them on purpose
Copy the files your project needs to run, by name, from the main checkout into each new worktree. Avoid copying every ignored file: ignored files are where secrets live, and a broad copy can put one where you didn't intend. Keep them ignored in the new worktree too, so an agent's commit can't pick them up.
$ cp .env .env.local ../atlas-fix-flaky-poll/Ports: give each worktree its own
Worktrees all share the machine's network ports. If every worktree starts the dev server on port 3000, the second one fails or, worse, an agent tests against the first worktree's server and reads the wrong code's behaviour. Set a different port in each worktree's local config:
$ echo "PORT=3001" >> ../atlas-fix-flaky-poll/.env.localThen tell the agent which port belongs to its worktree, or put it in the project's agent instructions, so it doesn't reach for the default.
Databases: one per worktree
Two branches that migrate one shared local database interfere with each other: one task's migration breaks the other's tests, and rolling back undoes work the other depends on. Give each worktree its own:
- A separate database on the same server, such as
atlas_fix_flaky_poll, with itsDATABASE_URLin the worktree's.env.local. - A file database, such as SQLite, kept inside the worktree's directory.
- Containers per worktree. Docker Compose names its project after the directory by default, so worktrees get separate containers and volumes. Ports published to the host still collide, so set those per worktree as above.
Script it once
The steps above are the same for every worktree of a project, so put them in a script that creates the worktree, clones or installs dependencies, copies the .env files and assigns a port. Then a new task is one command, and an agent never starts in a half-ready directory.
How ket does this
ket calls this provisioning, and it runs the dependency and .env steps above for you, with no script to write or maintain. By default it clones node_modules, .venv and vendor from your primary checkout, skips target, and copies .env, .env.local and .env.*.local. ket never writes the contents of .env files to its logs. On macOS it clones each directory copy-on-write in one call, and falls back to a normal copy where that isn't available. On one Mac, cloning a 20,000-file, 78 MB folder this way took 293 ms, against 5.5 seconds for a full copy; your time depends on the folder and the disk.
Two caveats:
- Only the CLI provisions automatically.
ket worktree addprovisions every worktree it creates. ket doesn't provision worktrees made in the app, from the Create worktree dialog, the quick prompt, the backlog or a phone, until you run Re-run provisioning for a worktree from the command palette, orket worktree provision. - Ports and databases are yours to set. ket doesn't assign ports or create databases; use the steps above, or a setup command.
To change what's provisioned for one repository, add a .ket.toml at its root. Its [provision] section replaces the global one from config.toml entirely, and its post_command runs in the new worktree once the project's Automation setting is on:
[provision]
directories = [
{ path = "node_modules", strategy = "clone" },
{ path = ".venv", strategy = "clone" },
{ path = "target", strategy = "skip" },
]
files = [".env", ".env.local", ".env.*.local"]
post_command = ["pnpm", "install", "--offline"]You can clone, symlink or skip each directory. Provisioning in the docs and Files and settings have the details.
Related guides
Git worktree tutorial: work on two branches at once.
What a worktree is, when it beats stashing or a second clone, and the commands to create, list, move and remove one.
Run React Native and Expo apps in Git worktrees.
Give each worktree its own Metro port, and its own simulator once it changes native code or tests alongside another worktree.
Run multiple Claude Code sessions in parallel.
The commands for running Claude Code sessions in parallel, each in its own worktree.
Run coding agents in parallel without sharing a working directory.
How to split work between agents, watch them, and merge the results one at a time, smallest dependency first.