Parallel worktrees

A worktree is a separate checkout of your repository, on its own branch, inside the same workspace. Worktrees let several people and agents change the same codebase at once without editing the same files under each other.

#One agent per worktree

CoDev never runs two agents in the same worktree: two agents in one checkout would overwrite each other's changes. If you send a message while another agent is working in the worktree your chat uses, CoDev keeps your draft and asks where it should run:

• Create a new worktree (recommended) makes a branch named after your message and sends the message there right away.
• Stay on this worktree puts your message in line. It waits and starts by itself, as you, when the other agent finishes, even if you close the tab.
• Cancel keeps your draft in the message box.

While it waits, the chat shows where it is in line, for example Queued · next in line. Each chat can have one message waiting. You, or the workspace owner, can Cancel a waiting message, and if it can't start, your draft comes back with the reason.

#Create and switch worktrees

The main checkout is the repository as you cloned it. Every other worktree has its own branch and its own files, while sharing the repository's history.

• Create one: choose New worktree from the worktree switcher or the Board, or New branch… from the branch menu in the top bar. Pick a new or existing branch, what to start from, and optionally a folder name, then choose Create worktree.
• Switch: pick a worktree from the switcher, or use Switch to … in the command palette (⌘ K). The file tree, editor, terminals, and chat follow the worktree you pick. Terminals you leave behind keep running.
• Agents can create worktrees for their own tasks, too.

CoDev keeps the worktrees it creates in a hidden .codev-worktrees/ folder, so they don't clutter the main checkout's file tree or search results.

#Your own worktree

Workspaces with live main (on unless the owner turned it off) give each owner and editor a worktree of their own, made from main the first time they open the workspace, and open it for you unless your link names another. Nobody edits main there.

• The switcher lists Your worktree first, then your teammates' worktrees by name, then Live main (everyone's work combined) and main (GitHub). A lock marks the ones you can only read.
• Read-only worktrees say whose they are, with Open your worktree. You can browse, search and review them, but saves, new files, commits and terminals go in your own worktree. Live main's terminal runs everyone's work together; anything you change there is thrown away at its next rebuild.
• Agents start from your work. A message runs in your worktree, a follow-up continues in its chat's worktree, and Create a new worktree starts from your branch. From your own Claude Code or Codex, the connector's file, Git and command tools also default to your worktree, and when you ask it for agents in the workspace, each one starts in a worktree of its own cut from your commits, so several can work at once (Codex on your ChatGPT sign-in runs one turn at a time, so those wait in line and start one after another).
• Their work comes back to you. When an agent working in a worktree cut from yours finishes a reply, CoDev commits what it changed and brings it into your worktree, and the chat says so. If your worktree changed the same lines, or has uncommitted changes in the same files, the work stays in the agent's worktree and the chat says why; a follow-up there brings it in once that's sorted. Work from a worktree that syncs from your computer stays in the agent's worktree for now.
• Viewers don't get a worktree; they open live main when there is one.

#The Board

Choose Board in the top bar (or /board in the chat) to see every worktree as a card in one of five columns: Needs you, Agent working, To review, Idle, and Merged. Its header sums the board up in one line, such as "1 needs you · 2 agents working · 3 idle", and stays live: cards move as agents start and finish, and each says when it last changed. With live main, each card is headed by whose work it is (you, your laptop, a teammate) over its branch; you can open a teammate's worktree to read it, but not prompt there. From a card you can stop its agent or remove the worktree.

While the workspace runs, each card also says where its branch stands against main: Up to date, Ready to merge (it has commits main doesn't), or Behind main; Taking in main while CoDev merges main into it; Conflicts with main and Agent resolving while an agent fixes a conflict; then Fixed · tests pass (or Fixed · tests fail) until main moves again; and Merged into main.

#Agents coordinate with each other

Worktrees stop agents from overwriting each other, but on their own they also hide agents from each other. Coordination closes that gap:

• Before an agent starts, CoDev compares your new task with the ones already running in the workspace. If it looks like a duplicate, you can choose Open session to see the one already doing it, or Start anyway.
• While agents work, CoDev tracks which files and functions each worktree changes and tests whether the branches would merge. Each agent hears once what the others are working on (their member, agent, branch and a few files), and again when that changes. When two agents' changes would conflict, or an agent's change would conflict with what has already merged into main, each one is told which function conflicts and to fix it now, while it's small. Changes that would merge cleanly aren't reported as conflicts. Your teammates' local agents count too: see Use CoDev from Claude Code or Codex.
• In the workspace, an agent's row shows overlaps and a count. Its menu lists the other agents' branches, agents, and owners with the shared files, and Open branch. Board cards say which branches they overlap, and the Changes view marks files with Also changed by and the other branch.

An agent working alone is never interrupted, and coordination never gives one member's agent access to another member's chat or files.

#Merge a worktree into main

With live main and a GitHub repository, main matches GitHub and nobody merges into it: ship your work instead. Otherwise, when a worktree's work is done, commit it, open the Review tab, and choose Merge into main, then Merge. CoDev creates a merge commit on main; uncommitted changes in the worktree aren't included. Owners and editors can merge.

• Both the worktree and main must be idle: wait for any agent working in either one to finish.
• Main must not have uncommitted changes. Commit or discard them first.
• If the merge would conflict, nothing changes: both checkouts stay exactly as they were, and CoDev lists the conflicting files. Where it can, CoDev also starts an agent in a new chat on the worktree to merge main in and resolve the conflicts; choose Open chat to follow it. When it's done, review its merge in Review and choose Merge into main again.
• Whenever main moves (a merge, GitHub's default branch, or a commit on main), CoDev brings the other worktrees up to date with main when that merges cleanly and no agent is working in them, so later conflicts stay small. A worktree with uncommitted changes main would touch is left as it was. A worktree that would conflict gets an agent that merges main in, resolves the conflicts and runs the tests, so you only review it; the workspace owner can turn that off with Let agents resolve conflicts with main in the workspace's settings.
• The board and your workspace home show how many conflicts CoDev caught before anyone merged: the ones agents were told to fix while they worked (here or on your machine with codev), and the ones met when main moved into a branch.

After the merge, everyone looking at main sees the changed files update. Merging into main happens inside the workspace; to get work onto GitHub, push the worktree's branch and open a pull request. See Git, GitHub, and pull requests.

#Remove a worktree

On the worktree's Board card, choose Remove worktree (the branch is kept). If it has uncommitted changes, CoDev asks before discarding them.

#Tips

• Give each agent a focused task, such as "write the tests for session refresh", rather than a whole feature.
• Start independent tasks in separate worktrees, and keep main for merging and reviewing.
• Merge finished worktrees often, so later work starts from the latest code.