Skip to content
PowerpBoxCaptainPublic

About

Stop two live Claude Code sessions from editing the same file at once. Three hooks, one file, no dependencies.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

edit-heat

Two agents, one file, one of them loses.

Run more than one Claude Code session on the same working tree (two terminals, a session resumed twice, a fleet of agents side by side) and sooner or later both edit the same file. One overwrites the other, or commits the other's half-finished work. git log cannot warn you: the other writer has not committed yet.

edit-heat is three hooks and one file. Every Edit/Write is recorded with the session that made it. An edit to a file that another live session touched in the last 30 minutes is refused, and the agent is told to ask you who owns it.

[edit-heat] BLOCKED (EH-001): /home/me/app/src/api.ts was edited 4 min ago by ANOTHER live Claude Code session
3f9c2a1b (pid 48211). Do not edit it now and do not work around this block. Tell the user which session is in this
file; if they rule it yours, they (or you, on their word) run: node ".../guard.mjs" release "/home/me/app/src/api.ts"
and you retry.

A session that has exited no longer holds anything: liveness is checked against the running process, not a timer.

Install

git clone https://github.com/PowerpBoxCaptain/edit-heat ~/.claude/skills/edit-heat

Then merge hooks.json into ~/.claude/settings.json (SessionStart, PreToolUse and PostToolUse on Edit|Write|NotebookEdit). Node 18+. Linux is tested; macOS should work through ps but is not tested yet; Windows is not supported.

Rules

Id What What the agent does
EH-001 BLOCKED another live session edited this file within the window stops and asks you; release only on your word
EH-002 HOLD the file changed on disk minutes ago and no session recorded it (script, editor, other agent) re-reads the file, then releases and retries
node guard.mjs status            # live sessions, hot files
node guard.mjs release <path>    # you ruled it: mute the guard for that file for one window

Settings: EDIT_HEAT=off (disable) · EDIT_HEAT_HOLD=off (EH-002 only) · EDIT_HEAT_WINDOW_MIN (default 30) · EDIT_HEAT_DIR (default ~/.claude/edit-heat).

Headless runs (claude -p, --print, --output-format, --input-format) are workers, not sessions, and are never registered. Generated paths (node_modules, dist, build, .next, coverage, .git, ...) are never guarded.

What it does not cover

Writes made outside Edit/Write/NotebookEdit are not recorded (EH-002 is a speed bump for recent ones, not proof). One machine and one user only. It does not lock files, merge, or stop git: it refuses an edit at the moment it is made, nothing more.

Tests

node test.mjs (Linux) runs 14 cases with real processes standing in for sessions, each with its own pid, including the positive controls (a block must happen before a pass means anything), a session that exits, a headless worker, a write nobody recorded, and the hook launched exactly as installed above. That last one is a regression test: a guard that looks for "claude" anywhere in a parent's command line mistakes the hook's own sh -c "node ~/.claude/..." for the session, and then never blocks anything.

Install as a plugin (preview)

Claude Code (this repository is a one-plugin marketplace):

claude plugin marketplace add PowerpBoxCaptain/edit-heat
claude plugin install edit-heat@edit-heat

Cursor (local plugin): git clone https://github.com/PowerpBoxCaptain/edit-heat ~/.cursor/plugins/local/edit-heat, then run Developer: Reload Window.

GitHub Copilot: copy .github/agents/edit-heat.agent.md into the same folder in your repository.

What has been tested: in Claude Code, the plugin was loaded and given a real task in an isolated session, its tool calls were checked against SKILL.needs.json, and the two commands above were run. The Cursor and Copilot files are checked against those clients' documented formats only; they have not been run in Cursor or Copilot yet. The plugin carries the skill only: it installs no hooks, so any hook described in this README is still set up by hand.

License

AGPL-3.0-only. See LICENSE.

About

Stop two live Claude Code sessions from editing the same file at once. Three hooks, one file, no dependencies.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages