free · open source · MIT · v0.6.1
Two AI coding tools, one repo. Each one quietly rewrites the other's work.
never-collide gives every tool that shares your repository one board to check before it touches a file. Claude Code, Antigravity, Codex, Gemini CLI and Copilot call dibs, work in parallel, and write down when they finished and when they tested.
no overwrites · no waiting in the dark · two tools or five
git clone --depth 1 https://github.com/malaysherasia-ai/never-collide.git && bash never-collide/install.sh .macos, linux, wsl and windows · git and python 3.7+ · no node, no service · the board lives in your own repo
how it works
Every tool runs the same short ritual: say who you are, read the board, claim the paths you are about to change. The board is one text file on a branch of your own repository, and a git push is the lock. A claim that overlaps another tool's is refused before an edit happens, and a hook asks about any edit or commit outside a claim. Done and tested are written down with the time, and a released claim frees the path for whoever was waiting.
in plain words
If you have never opened a terminal, this is the whole idea. Two AI tools build your site. One writes the logic, one designs the pages. They work at the same time, and they both save to the same place.
without it · today
Both open the same page and both rewrite it. Whoever saves last wins, and the other one's work is gone. Nobody tells you. You find out when the site breaks, or a week later when a feature you paid for has vanished.
with never-collide · before any edit
Before touching a page, each tool writes its name, the page and what it plans to do on a shared sheet. If the page is already taken, it is told no before it changes anything. It leaves a note for the tool that holds the page, and works on something else meanwhile.
when it's finished · nothing lost
The tool writes down when it finished and when it tested, then crosses its name off. The next tool sees the page is free, reads the note, and picks up exactly where it was asked to. Both pieces of work survive.
parallel coding on one repo, without the collisions
Whether you run Claude Code beside a design tool on a weekend project, or a fleet of agents on a production codebase, the failure is the same: two of them wanted the same file and neither knew.
vibe coding · two or more ai tools · no code background needed
You use Claude Code for the logic and another tool for the design, and every so often one of them wipes out what the other just built. You cannot see it coming, because you are not reading the code. never-collide makes them check a shared board before touching a file, and tells the second one no.
Ask Claude Code to install it and to give itself a name. The tools handle the rest.
ledger on an orphan branch · glob claims · ttl · any cli
Worktree isolation is the right answer for tasks that can be separated. Yours cannot: UI and logic meet on the same page files every day. never-collide is an append-only JSONL ledger on an orphan branch, fast-forward push as the lock, overlap checks on every claim, and a time limit on each one.
Enforced three times: a PreToolUse hook before the edit, a git pre-commit hook before the commit, a GitHub Action on the pull request. Warn first, deny when you say so. No service, no daemon, no Node. One Python script, and an AGENTS.md every tool already reads.
install
Open a terminal in the project the tools share, pick the column for your computer, and run the commands in order. The installer copies the ncl script, the hook dispatcher, the git runner and the skill into .claude/, adds starter AGENTS.md, OWNERSHIP.md and PROTOCOL.md files only where none exist, adds the pull-request workflow, registers the edit hook in Claude Code's settings without replacing them, installs the git pre-commit stub, and adds a marked block to CLAUDE.md. If never-again is already there, the two share the git hook. Run it again whenever you want a newer version.
requires git, bash, python 3.7+ · a remote named origin every tool can push to
# from your project root $ git clone --depth 1 https://github.com/malaysherasia-ai/never-collide.git $ bash never-collide/install.sh .
.claude/settings.json by the installer. In the clone another tool works in, run once:
$ python .claude/never-collide/ncl whoami --set antigravity
AGENTS.md, .agents/, .claude/ and the workflow are team knowledge. The board itself lives on its own branch and never touches your code.ncl status before planning, ncl claim before editing, then done, tested and release. Edits and commits outside a claim are asked about. When a week has passed without a false alarm, ncl enforce deny. If anything looks wrong, ncl doctor says what to fix.requires git for windows, python 3.7+
python -c "import sys" must exit 0. If Windows opens the Microsoft Store instead, that is the alias stub. Turn it off under Settings, Apps, App execution aliases.git clone --depth 1 https://github.com/malaysherasia-ai/never-collide.git & "C:\Program Files\Git\bin\bash.exe" never-collide/install.sh .
ncl.cmd is the PowerShell entry.
.claude\never-collide\ncl.cmd doctor .claude\never-collide\ncl.cmd status
auto mode off · it asks before each step · git and python 3.7+ still required
Paste this into Claude Code inside your project:
Install never-collide from https://github.com/malaysherasia-ai/never-collide into this project, run ncl doctor, and explain what it added and what each of my other tools needs.Claude Code's auto mode won't run an installer it has never seen, so turn auto mode off first. It will then ask before each step; say yes. It gets its own name from the installer. For each other tool, the one thing to do is run ncl whoami --set once in that tool's clone, and Claude Code can tell you the exact line.
What version 0.6.1 does, and what is not yet confirmed. The board and the ritual, the edit hook, the git pre-commit hook and the pull-request check all ship and have been exercised on the tool's own repository. The edit hook is wired and tested for Claude Code. The hook registrations for Antigravity, Codex, Gemini CLI and Copilot follow each tool's own documentation and have not yet been run against those tools; the commit hook and the pull-request check cover their work regardless.
why it exists
Seven reasons the design is this small, and why small is the point.
Every tool announces what it is about to touch, so the others learn a plan before it becomes a collision.
A merge conflict is the last possible moment to find out two tools wanted the same file, and by then both have done the work. A claim moves that moment to before the first edit. The refused tool has lost nothing but one command, and it knows who to ask.
There is no server deciding who goes first. Two pushes to the same branch cannot both be first, and git already knows that.
ncl fetches the board, checks every active claim by another agent for overlap, appends one line and pushes. If another tool pushed first, the push is rejected, the script fetches again, rechecks and either succeeds or fails cleanly. That is the whole lock, and it works from any machine that can reach your remote.
Nobody edits the board. Everyone adds a line at the bottom.
The ledger is one JSON object per line, and the newest line for a task is its current state. A rebase onto a newer board never produces a content conflict, because nothing above the last line ever changes. The full history of who held what, and when, comes free.
A tool that crashes mid-task cannot block everyone until someone notices.
Every claim carries a time limit, four hours by default and adjustable per claim. ncl status shows what is held, by whom, and when it lapses, in your local time. An expired claim stops blocking on its own; nobody has to clean up after a lost session.
The rules live in AGENTS.md. Antigravity, Codex, Gemini CLI and Copilot read that file on their own; Claude Code reads it through one line in CLAUDE.md.
So there is one ritual, written once, and every tool sees the same words. Adding a sixth tool is a name and one line in OWNERSHIP.md saying which paths it normally owns.
The ritual is written down, and a hook checks it anyway: before an edit, before a commit, before a merge.
The edit hook runs in Claude Code before any write and asks when the path is not covered by a claim this tool holds, naming the holder. The git pre-commit hook runs the same check over the staged files, from any tool or terminal, and flags a commit on main. The pull-request check refuses a merge whose changed paths are not covered by a claim marked done. Every hook starts in warn mode; ncl enforce deny is a human command, and ncl enforce off ends any trouble. Hooks read a local copy of the board refreshed at most every two minutes, so an edit never waits on the network.
No account, no service, no background call. The board is a branch in your repository, and you can read it with git log.
The installer asks once per machine whether to count you, anonymously, and Enter skips it. ncl feedback shows the exact payload and sends only on a yes. ncl upgrade asks GitHub for the newest release when you run it. That is the whole list. Delete the branch and never-collide is gone; your code was never touched.
comparison
Each of these solves part of the problem, and you should probably keep the ones you have. None of them tells a tool, before it edits, that another tool is already on that file.
| A branch per agent | CODEOWNERS | Worktree isolation | never-collide | |
|---|---|---|---|---|
| Knows who is on a file right now | noOnly at merge time | noSays who may, not who is | partlyPer task, in separate folders | yesncl status, with expiry times |
| Two tools want the same page | Merge conflict, after both did the work | A reviewer catches it at the pull request | Not allowed: it keeps them apart | The second claim is refused before an edit, with a handoff note |
| Tools that must share files daily | Conflicts every day | Review load every day | Cannot: the tasks are not separable | Coordinated: claim, work, release, next |
| Records done and tested times | no | no | no | yesWith the PR and the test evidence |
| Enforced before the edit | no | At review | By layout | yesEdit hook, commit hook, PR check |
| A crashed session | A stale branch | Nothing to clean up | A stale worktree | Its claim expires on its own |
| Needs | git | GitHub | git, plus the tool | git, Python, and a branch in your own repo |
| Best for | Everything. Keep it. | Saying who should review what | Tasks that never touch the same files | Tools that share files and need to know who is where |
Worktree isolation, such as Parallel Code, is the right answer when tasks can be kept apart, and it is not what never-collide competes with. Use both. It isolates the tasks that can be isolated; never-collide coordinates the ones that cannot, where a UI tool and a logic tool meet on the same page every day. Branch-per-agent stays too: never-collide expects every tool on its own branch, and real merge conflicts still surface at the pull request where a human sees them.
questions
Yes, if you build with more than one AI coding tool on the same project. You can ask Claude Code to install it. After that the tools follow the ritual themselves; your only job is to give each tool a name.
Before a tool touches a file, it writes its name, the files and what it plans to do on a shared board. If another tool already holds those files, the claim is refused before any edit happens. That is the whole idea: say what you are about to do, and check what others are doing, before you do it.
In your own repository, as one text file called ledger.jsonl on a separate branch named agents/ledger. There is no server and no account. Anyone with access to the repo can read it with git, and it never mixes with your code.
No. The tools run them. The installer adds an AGENTS.md that spells out the ritual, and Antigravity, Codex, Gemini CLI and Copilot read that file on their own. Claude Code reads it through one line in CLAUDE.md, and the installer writes its name into Claude Code's settings. For another tool you run ncl whoami --set antigravity once in that tool's clone.
Two tools in one folder share one checkout and one branch, so neither can work on its own branch and each sees the other's half-finished edits. Clone the repo once per tool, open each clone in its tool, and let the board on your remote do the coordinating.
Three checks catch it. An edit hook in Claude Code asks before any write to a path outside a claim the tool holds, naming the holder. A git pre-commit hook checks every staged file from any tool or terminal. A pull-request check refuses a merge whose changed paths are not covered by a claim marked done. Every hook starts in warn mode; ncl enforce deny makes them refuse instead of ask. In Claude Code's auto permission mode an ask already counts as a deny, so warn mode stops an unclaimed edit there and the agent claims and retries.
Every claim carries a time limit, four hours by default, and any update to the task restarts the clock. When it lapses the paths are free again. ncl status shows the expiry time while a claim is active, and lists expired claims for a day afterwards so the next tool knows to ask before reusing the paths. A claim can be given a longer or shorter limit when it is made, with --ttl.
Git does. Each claim is a commit pushed to the ledger branch, and two pushes cannot both be first. The second one is rejected, the script fetches the newer board, checks overlap again, and refuses cleanly. No server decides anything.
Each step of the ritual is one fetch and one push to your own remote, a second or two. The hooks read a local copy of the board refreshed at most every two minutes, so an edit never waits on the network, and offline they use the last copy and say so.
It asks; it does not stop you, until you choose deny. ncl enforce warn relaxes deny and ncl enforce off silences everything. ncl report shows what the hooks decided and why, ncl doctor checks the setup in plain words, and ncl uninstall removes the tool and keeps your AGENTS.md, ownership file and the board. It never edits your source files.
No. They are siblings with the same install pattern and the same site. never-again stops one tool repeating a mistake; never-collide stops several tools overwriting each other. Most repos that need one need both, and they share the git hook.
Nothing on its own. The board is pushed to your own remote. The installer asks once per machine whether to count you anonymously, and Enter skips it. ncl feedback shows the exact payload and sends only on a yes. ncl upgrade asks GitHub for the newest release when you run it. There is no account and no background call.
nc is netcat, a network utility on every Unix machine. Shadowing it would break things quietly. Three letters, no collision.
MIT licensed, no paid tier, nothing hosted to pay for later.