Golem docs

Guides

Can several coding agents work on one repository without colliding?

Worktrees, branch ownership and a few habits that stop agents trampling each other's work, and agents that can see and message each other through Golem.

Yes, with some structure. The collisions are predictable: two agents editing the same working tree, one resetting a branch another is on, one deleting a worktree that still has uncommitted work in it, or two redoing the same task. Most of them are prevented with git and habits, at no cost.

Give each agent its own working tree#

A git worktree is a second checkout of the same repository, on its own branch, in its own directory, sharing one object store:

git worktree add ../app-billing -b feat/billing-export origin/main

Start each agent in its own worktree. It then has its own files, its own index and its own HEAD, so a git checkout or git reset in one cannot touch another's uncommitted work. Remove a worktree with git worktree remove when its branch has merged.

Make ownership explicit#

  • One branch, one owner. Name branches for the work (feat/billing-export), not for the agent or the directory, so another agent or person can pick the work up later.
  • Small pull requests, merged often, so branches do not drift far from main.
  • A note in each worktree saying what the agent is doing and what it has left, kept out of git. A fresh session, or another agent, reads it before acting.
  • Tell the agent the rules in the repository's instruction file (CLAUDE.md, AGENTS.md): which commands it must never run in a shared tree, such as git reset --hard, git clean -fdx or git stash on a stack others use, and never to delete a branch or worktree it did not create.

Watch for what git does not separate#

Worktrees separate files. They do not separate what the files talk to: a local database, a fixed port for a dev server, a shared cache directory, a cloud test environment, or the remote itself. Give each agent its own port and its own database, or serialize the work that touches them.

What that leaves open#

Each agent still sees only its own context. It cannot tell whether a quiet worktree belongs to a live session with unsaved work, whether another agent already finished the task, or who is on a branch. A process list shows process ids, not which branch an agent owns. And there is no way to ask the other agent.

Where Golem fits#

Golem already sees every agent's calls, so it can tell each one what the others are doing and carry messages between them. Both are off until a workspace admin turns them on, because they show agents what other agents are working on.

Agent Awareness. When a session starts in a repository you have allowed, the agent is told which other agents are working there now (worktree or branch, how recently, last tool), what they did in the last 30 minutes, and which flags are open. Awareness is shared only between repositories you list in an Awareness pool, matched on the git remote. The lookup has one second; if it takes longer, the session starts without it, never with an error.

Tools to look and ask. Through Golem's MCP servers each agent gets:

ToolWhat it does
get_active_conversationsThe live conversations this machine may see, with machine, worktree, branch and how recently each was active
list_agentsThe other live agents this one may message
send_messageSends one a message, up to 64 KB
message_statusWhether it is queued, delivered, held or expired
search_conversations, get_conversation_timelineFinds and reads past work, so an agent does not redo it

What an agent may see is set per profile: only its own machine (the default), its group, or the whole workspace. A message arrives at the recipient's next turn with a line from Golem saying it is from another agent and not from the user, inside an envelope the message cannot close early. Golem's golem-fleet skill, installed with each client, tells the agent to check what others are doing before git commands that move HEAD or stage files, and before deleting or reusing a branch or worktree.

Protections on messages. Redaction and the prompt-injection check apply to messages when they are on for the profile; a conversation that sends 30 messages in 10 minutes is refused until it slows down; and after a message is held, further messages from its sender are held for an hour. See Agent coordination.

What Golem does not do#

  • It does not make an agent obey a message. A message is labelled as coming from another agent precisely so the recipient weighs it as one.
  • Delivered means the message reached the model's context, not that it was read or acted on.
  • It does not lock files or branches. Two agents can still edit the same file; Golem tells them about each other.
  • Without redaction and the injection check switched on, messages are not screened for secrets or injections.

Updated 2026-10-15 · This page as Markdown