agent-file-claim

Two coding agents on one machine, one file: the later edit quietly undoes the earlier one. This hook stops it. A session's first write to a file claims it; another session's write to that file is refused, with who holds it and until when, so the agent works on another file or waits. The holder's next write renews the claim, its session end frees its files, and an hour without a write frees them too. Nothing leaves your machine; it needs only Python 3.9 or later, on Linux or macOS.

pipx install agent-file-claim

Claude Code

Add to ~/.claude/settings.json (or install the plugin: /plugin marketplace add https://huggingface.co/memento-team/claude-plugins.git, then /plugin install agent-file-claim@memento-team):

{
  "hooks": {
    "PreToolUse": [{"matcher": "Edit|Write|MultiEdit|NotebookEdit",
                    "hooks": [{"type": "command", "command": "agent-file-claim hook"}]}],
    "SessionEnd": [{"hooks": [{"type": "command", "command": "agent-file-claim end"}]}]
  }
}

Codex

Add to ~/.codex/hooks.json; Codex asks you to trust the hooks at the next start:

{
  "hooks": {
    "PreToolUse": [{"matcher": "^apply_patch$",
                    "hooks": [{"type": "command", "command": "agent-file-claim hook"}]}],
    "SessionEnd": [{"matcher": "*", "hooks": [{"type": "command", "command": "agent-file-claim end", "timeout": 3}]}]
  }
}

What a refused write says

refused: /work/app/src/auth.py is held by session 3f9c2a1b in /work/app since 14:02 UTC, until 15:02 UTC unless it writes
again. Another live session is editing it: work on another file, or wait for that session to end.
Only if that session is gone: agent-file-claim release /work/app/src/auth.py

Commands

• agent-file-claim lists the files held and the count of writes refused.
• agent-file-claim release PATH frees one file.
• --minutes N sets the lease (default 60; 0 turns the hook off), --skip "*.lock,CHANGELOG.md" names files any session may write, --dir where the claims live (default ~/.memento).

Claude Code and Codex sessions share the same claims. Across machines, memento Team keeps one owner per file for the whole team: https://overflow.games/memento/?ref=pypi-claim

MIT license.