
agent-deconfliction
Coordinates two agents sharing one repository by agreeing file ownership and git operations before conflicts.
- version
- 1.0.0
- GitHub stars
- 32
What it does
- Adds the
agent-deconflictionskill for when two Claude Code sessions or a Claude Code session and another agent share one working tree - Covers messaging the other agent with
ListAgentsandSendMessage, then splitting files, shared-file owners, path-only commits, or separate worktrees - Records the agreed plan in
.git/agent-deconfliction.md, which is never committed and is visible to both agents across worktrees - Provides a manual fallback for non-Claude agents such as Codex, Gemini CLI, or Cursor, using a shared file and a pasteable prompt
Two agents in one repo? Message the other, agree who owns which files and git ops before anything collides.
Add marketplace
/plugin marketplace add danielrosehill/Claude-Code-PluginsRun it inside Claude Code once, then install the plugin below.
Install
/plugin install agent-deconfliction@danielrosehillRun it inside Claude Code after adding the marketplace.
Files
Discovered from sourceAgent deconfliction
Two agents in one repository share one working tree, one git index and one branch unless they arranged otherwise. Left alone they overwrite each other's edits, commit each other's half-finished work (git add -A), or run a checkout, stash, reset, rebase or pull under the other's feet. This skill is the safeguard: as soon as anyone notices a second agent in the repo, stop, say hello, swap what each is doing, and agree a split before anything collides.
It is manual and short. It assumes agent-to-agent messaging (in Claude Code: ListAgents + SendMessage). Without it, use the fallback at the end.
Both sides run this skill: the initiator (the agent the user invoked it in) and the responder (the agent that receives a deconfliction message). If you received a message whose first line starts DECONFLICTION, you are the responder: go to "Responder".
Initiator
1. Freeze writes
From now until an agreement is in place, make no file edits and run no git command that changes state (add, commit, checkout, switch, stash, reset, rebase, merge, pull, push). Reading is fine. If you were midway through a multi-file edit, finish the file you are in only if leaving it half-written would break the build, and say so in the message.
2. Snapshot your own state
Run, from the repo root:
git rev-parse --show-toplevel --abbrev-ref HEAD
git rev-parse --git-common-dir # same value for both agents = same repo, even across worktrees
git worktree list
git status --short
git diff --stat
git log --oneline @{u}..HEAD 2>/dev/null # unpushed commits
From this and your own context, write down:
- Task: one sentence on what you are doing for the user.
- Files: the files you have changed (uncommitted), and the files or directories you expect to touch next. Be specific; "src/" is not a plan.
- Git state: branch, worktree path, uncommitted changes yes/no, unpushed commits yes/no.
- Next git step: what you were about to do (commit, push, rebase, branch switch, nothing yet).
- Hot spots: shared files likely to be touched by anyone (lockfiles,
package.json,pyproject.toml,README.md,CHANGELOG, generated files, migrations, config).
Note: git status cannot tell you which uncommitted changes are yours and which are the other agent's. List only the files you know you changed. Unexplained changes in git status are probably the other agent's: list them separately as "not mine".
3. Find the other agent
Call ListAgents. Candidates are sessions whose working directory is this repo or a worktree of it (same --git-common-dir). Then:
- Exactly one: that is the peer.
- Several: send to each, or ask the user which one in one line.
- None, but the user says one exists: it may be a different tool (Codex, Gemini CLI, Cursor, Aider) or a session that cannot receive messages. Use the fallback.
4. Send the deconfliction message
Send with SendMessage. The first line is all the receiving user sees until they expand it, so it must stand alone. Use this shape:
DECONFLICTION: <your name> is also working in <repo name> on <branch>; pausing writes, please reply with your scope.
Hello, I'm <your name>, working in <worktree path>. We are in the same repository, so we may collide. I have paused edits and git operations until we agree a split.
My task: <one sentence>
Files I have changed (uncommitted): <list or "none">
Files I plan to touch: <list>
Changes in git status that are not mine: <list or "none">
Git state: branch <b>, unpushed commits <yes/no>, next git step <...>
Hot spots I may need: <list or "none">
Please reply in the same shape (task, files changed, files planned, git state, next git step), and pause your own writes and git operations until we agree.
Proposed split: <your opening proposal from step 6, or "proposal once I see your scope">
Ask for an idle notice only if you need it to know when the peer has replied (notify_when_idle: true works only for sessions on the same machine). Never ask the peer to do something your own session was denied permission to do.
5. Wait for the reply
Do not resume writing while you wait. If the user wants you to keep going meanwhile, limit yourself to reads. If no reply arrives, tell the user and ask whether to go on (they may relay it, or the other session may be awaiting its user's approval of cross-session messages). Silence is not agreement.
6. Compare and choose a split
Classify the overlap and pick the lightest arrangement that removes it:
| Overlap | Arrangement |
|---|---|
| None: different files, neither needs git ops soon | Partition. Each owns its file list. Each commits only its own paths. |
| Different files, but both will commit | Partition + path-only commits. git add <explicit paths> and git commit -- <paths>; never git add -A, git add . or git commit -a. Agree who pushes, and that the other pulls only once told it is safe. |
| Shared hot spot (lockfile, manifest, README, changelog) | Single owner for the hot spot. One agent makes all edits to it; the other sends what it needs added. |
| Same files, or one task depends on the other | Sequence. One goes first and finishes and commits; the other waits, then pulls in that work. Usually the one closer to done goes first. |
| Long, broad or risky work on both sides | Separate worktrees. One agent moves to its own git worktree add ../<repo>-<task> -b <branch> and merges back later. Only the agent that has nothing uncommitted should move; never move uncommitted work by stash while the other agent is in the tree. |
| Conflicting goals (one is refactoring what the other is fixing) | Escalate. Do not resolve it between the agents. Tell both users and stop. |
Branch-switching rule for every arrangement: in a shared working tree, nobody runs checkout, switch, stash, reset --hard, rebase or pull without telling the other first and getting an OK back, because it changes the files the other is editing.
7. Agree and record it
Send the proposed arrangement as a short list: who owns which paths, who owns each hot spot, who commits and pushes and in what order, any sequencing. Ask the peer to reply "agreed" or with changes. The plan is in force only once both sides have said "agreed".
Then write the plan to $(git rev-parse --git-common-dir)/agent-deconfliction.md. It lives inside .git, so it is never committed, and both agents can read it (including from separate worktrees). Overwrite it with the current plan; include the date, both agent names and the arrangement.
8. Resume and report
Resume within your share. Tell the user in two or three lines: who the other agent is, what it is doing, and the split.
Responder
When a message arrives whose first line starts DECONFLICTION:
- Freeze writes (initiator step 1). Reply even if you are mid-task.
- Snapshot your state (initiator step 2).
- Reply to the sender (
to= the message'sfrom) in the same shape: task, files changed, files planned, changes not yours, git state, next git step, hot spots. Then accept the proposed split, propose another, or say you need your user's input. - When both have said "agreed", read
agent-deconfliction.mdin the git common dir to confirm it matches, resume within your share, and tell your user the split in two or three lines.
While the agreement is in force
Send a short message to the peer, without being asked, when:
- your scope grows to a file the other owns, or to a hot spot: ask first, and wait;
- you are about to commit, push or pull, if the plan said to coordinate those;
- you finish: "DECONFLICTION: done, released , pushed ". The peer can then take over released files.
If you find the other agent's change in a file you own, do not revert it. Message the peer and sort it out.
Fallback: no agent-to-agent messaging
If the other agent cannot be messaged (another tool, or a session that does not accept cross-session messages):
- Freeze writes and snapshot your state as above.
- Write the message from step 4 to
$(git rev-parse --git-common-dir)/agent-deconfliction.md. - Ask the user to tell the other agent to read that file, answer in the same shape and append its reply. Give the user one line they can paste, e.g. "Read .git/agent-deconfliction.md and reply in it before editing anything."
- Read the reply from the file, then continue from step 6, using the file as the channel.
Readme
Agent Deconfliction
A one-skill plugin for when two AI coding agents end up working in the same repository at the same time: two Claude Code sessions, or Claude Code alongside another agent.
They share one working tree, one git index and usually one branch. Left alone, they overwrite each other's edits, commit each other's half-finished work with git add -A, or switch branches under each other. The moment you notice ("wait, I've got another agent in here"), invoke the skill in either session, before anything collides.
Skill
agent-deconfliction: the agent stops writing and takes stock of its own state (task, files changed and planned, git state, next git step). It finds the other agent withListAgentsand sends it a structured deconfliction message withSendMessage. Both agents compare scopes and agree a split: separate file lists, a single owner for shared files such as lockfiles and READMEs, path-only commits, going one after the other, or separate git worktrees. Each then works within its own share. The agreed plan is written to.git/agent-deconfliction.md, which is never committed and is visible to both agents, even across worktrees.
The skill covers both sides. The agent you invoke it in is the initiator. The agent that receives a message whose first line starts with DECONFLICTION follows the responder steps.
Requirements
- Agent-to-agent messaging. In Claude Code this is built in (
ListAgents,SendMessage). - Without it, for example when the other agent is Codex, Gemini CLI or Cursor, the skill falls back to a shared file in the git directory and gives you one line to paste to the other agent.
Installation
claude plugins marketplace add danielrosehill/Claude-Code-Plugins
claude plugins install agent-deconfliction@danielrosehill
Then, in the session that should start the exchange: "run agent deconfliction" or "there's another agent working in this repo".
License
MIT
Details
- Marketplace
- danielrosehill/Claude-Code-Plugins
- Source
- danielrosehill/Agent-Deconfliction
- Author
- Daniel Rosehill
- Category
- QA & Agent Sessions
- License
- MIT
More from danielrosehill/Claude-Code-Plugins
All 264- agent-exchangev1.0.1
- agent-ready-websitev1.0.0
- agentic-dev-workflowsv0.6.1
- ai-attributionv0.1.0
- ai-engineeringv1.0.0
- ai-evalv0.13.0
- ai-model-researchv1.4.0
- ai-toolsv1.0.0
- ai-video-producerv1.4.1
- air-quality-toolkitv1.0.0
- aliexpress-israel-skillsv1.14.0
- aliexpress-shopperv0.1.0
- amazonv2.2.0
- anonymisation-assistantv0.1.0
- audio-editingv1.0.0
- audio-productionv1.11.3
- audio-voice-idv0.1.0
- avp-music-videov0.1.0
- background-removalv1.0.0
- backup-plannerv1.0.1
- batch-inferencev1.5.0
- batch-optical-archivistv1.0.0
- bh-photov1.0.0
- bios-tuningv1.1.0
Similar to agent-deconfliction
More AI Agents & Orchestration
eccaffaan-m/everything-claude-code308.6K starsHarness-native ECC operator layer - 72 agents, 328 skills, 99 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready work
mattpocock-skillsmattpocock/skills304.3K starsMatt Pocock's agent skills for real engineering (grilling, spec/ticket flows, TDD, code review, domain modelling and more).
agent-sdk-devanthropics/claude-code156.1K starsDevelopment kit for working with the Claude Agent SDK
agent-skillsaddyosmani/agent-skills119.6K starsProduction-grade engineering skills covering every phase of software development: spec, plan, build, verify, review, and ship.
agentdbruvnet/ruflo82.2K starsAgentDB (external: maintained in ruvnet/agentdb, pinned to commit 27678c3, plugin 3.6.0): agentdb's own standalone MCP server pinned to agentdb@3.6.0 (vector me
last30daysmvanhorn/last30days-skill72.2K starsResearch any topic across Reddit, X, YouTube, TikTok, Instagram, Hacker News, Polymarket, GitHub, and 5+ more sources. AI agent scores by upvotes, likes, and re