Live worktrees
Give each agent its own worktree
- A single agentIt can work on a normal branch. The worktree starts to matter when you add the second agent.
- Several at onceEach one needs its own checkout, port, and environment, or they will step on the dev server and the files.
What you gain from a separate checkout
The working tree stops being a shared resource. Claude can rewrite the API while Cursor rewrites the screen, and git does not have to resolve a conflict every minute. Your branch, the one open in the editor, stays still until you decide to bring the result in.
doki keeps the record of those worktrees in ~/.doki. It is not a branch system beside git: they are git worktrees, visible to the tools you already use.
The port and .env, which is where they actually collide
The most common conflict is not a merge. It is port 3000 already taken, and a .env an agent just pointed at another database. doki reserves a port per worktree and copies .env into the new checkout, so each agent can start its own server.
Those ports show up in the app’s list and in the Mac’s notch: who opened it, how much CPU and memory it uses, and the URL. You can open it, copy it, pass it through an SSH tunnel if the process is on another machine, or stop it.
Merge, open a PR, or throw the work away
When the agent marks itself done, you have three clean exits. Merge, if you already trust the diff. Open a pull request with gh, if the change should go through the review you always do. Discard, if the experiment failed and you do not want the branch left hanging.
Before those exits there is room for automatic diff review: ready, review, or don’t merge, with risks and secrets. If the verdict is not clean, doki can send the findings back to the agent. The flow is in diff review.
Two worktrees that talk to each other
A combo puts one agent on building and another on reviewing, each in its own place, until the result is approved or they get stuck and call you. That is the natural use of two worktrees: the reviewer does not edit on top of the author.
Cursor over the API can take one of those roles without you opening the editor. The other can be Claude or Codex in the terminal. Those paths are compared in Cursor vs doki and several agents.
Practical limits
Each worktree is a copy of the files. In a huge monorepo, ten agents means ten checkouts and the disk notices. It is worth it for tasks that truly run together, not for every five-minute experiment.
The .env copy is one more secret. It lives in that folder, with the user’s permissions. Do not commit it in the PR. Secret review is there to catch exactly that mistake.
Frequently asked questions
Do I create the worktree by hand?
No. doki can create it when you assign the task, with the branch, the port, and the .env copy. If you prefer one you already made, the agent can still work there.
Can my editor see those files?
Yes. It is a normal checkout in another folder. You can open it in Cursor or any editor when you want to read the diff slowly.
Does doki or gh open the PR?
doki triggers it with gh. You need gh installed and authenticated, the same as opening a PR from the terminal.
Does this work on a remote server?
A remote agent can have its own checkout on that machine. The Mac’s Inbox shows the session. The worktree is not copied to the laptop just because you are connected.
