git worktrees and agentmash: use both.
git worktrees isolate checkouts: each agent works in its own copy of the repository, on its own branch, so no two agents write into the same file on disk. agentmash tells your agent what your teammates’ agents are changing, on any branch and any machine, before it edits. it doesn’t warn your own agents about each other: keeping them apart is the worktree’s job.
what worktrees do
a git worktree is a second working directory of the same repository, with its own files and its own branch, sharing one history. Claude Code’s --worktree flag starts a session in a worktree of its own, and Cursor can run an agent’s task in a worktree too. either way, agents running side by side on one machine stop editing the same files on disk.
what worktrees don’t catch
- the same file, changed on two branches. your agent works in a clean checkout, so it isn’t told that a teammate’s agent is changing the same file on another branch. the conflict shows up at the merge.
- a break across files. your agent changes the signature of an exported function,
createUserinsrc/models/user.ts; a teammate’s agent, three files away insrc/api/handlers.ts, keeps building against the old one. no path is shared, so nothing about the files says they collide. - a teammate’s worktree. worktrees separate the agents on one machine. a teammate’s agents work in their own checkout on their own laptop, and nothing on your machine knows about their changes.
what agentmash adds, across branches
every edit from every developer’s agent goes to one room for the repository, and every worktree of it reports to that same room, each on its own branch. agentmash compares each developer’s edits with their teammates’, never with their own, so before an edit your agent is told about a teammate’s change to the same file, worded by where that change is:
- on another branch, or in a clone of their own,
PARALLEL EDIT: there’s nothing to re-read, so the agent keeps its edit additive, doesn’t reformat or reorder, and names any divergence in its reply. a teammate’s change on another branch reaches your agent before the edit instead of at the merge. - in the same checkout,
ACTIVE COLLISION, orSTALE READonce the teammate has gone: their write is already in your working tree, so the agent re-reads the file and rebuilds its edit against what’s there. each edit carries an opaque id of the checkout it came from, so the hook can tell a shared checkout from a clone on a branch of the same name; when it can’t, the advice says what to do either way. - across files: the hooks send the exported names an edit changed and what each file imports, so a teammate’s change to
createUserreaches every file that imports it, whatever directory it’s in. the server gets the names, never the code. - before anyone writes: an agent can claim the paths it’s about to change, and learns whether a teammate already has part of them, so it can take other work.
- after the fact: if your agent and a teammate’s changed the same file anyway, you’re told once, as the session finishes, with whose change it meets, before either change lands. nothing is merged, pushed or opened for you: a person decides.
side by side
| what happens | git worktrees | agentmash | both |
|---|---|---|---|
| two of your own agents writing one file on disk | can’t happen: each has its own checkout | can happen, and neither is warned | can’t happen |
| two of your own agents changing one file on two branches | found at the merge | neither is warned: both report as you | found at the merge |
| knowing what a teammate’s agent is changing | no | yes, before each edit | yes, before each edit |
| a teammate’s agent changing the same file on another branch | found at the merge | told before the edit | told before the edit |
| a teammate’s change to a function your file imports | found when something breaks | told before the edit, in JavaScript and TypeScript | told before the edit, in JavaScript and TypeScript |
| teammates’ agents on other machines | not seen | in the same room | in the same room |
| a teammate’s agent and yours changed the same file anyway | a merge conflict for a person | you’re told as the session finishes, before either change lands | you’re told as the session finishes, before either change lands |
keep your worktrees
nothing about a worktree flow changes. someone connects the repository once, each developer signs in once with npx agentmash login, and every worktree of the repository reports to its room from then on.
what it doesn’t do
- symbols are read from the JavaScript and TypeScript family only. python, go and rust files are matched by path alone, so a break across files in them goes unseen.
- an advisory is not a lock: it informs the agent, and the edit goes ahead (in Cursor and the tools like it, on the agent’s second try).
AGENTMASH_STRICT=1is the setting that blocks. - it warns about teammates’ agents, never your own. two of your agents, in two worktrees or in one checkout, both report as you, so neither is warned about the other, and a file both change raises no overlap notice.
- agentmash makes no checkouts. keeping your own agents out of each other’s files is the worktree’s job.
what counts as a conflict →the five levels →claims →reconciliation →known limitations →