Preventing Concurrent Data Clobbering in GitNeural with Claude Handoff Guard

Practical Summary and Core Problem

Claude Handoff Guard is a technical solution designed to solve the problem of concurrent clobbering in AI coding sessions. When working across multiple machines or running background agents alongside interactive sessions, standard handoff files are often overwritten, leading to the loss of critical context. This tool implements a structural block on file mutations by embedding an ownership marker directly into the handoff file itself. By using a PreToolUse hook, the system compares the session ID of the current operation against the marker present in the file, ensuring that only the authorized session can modify the content. This approach moves beyond simple conventions, making unauthorized overwrites technically impossible rather than merely discouraged. It is specifically designed for developers who frequently switch between devices or maintain multiple concurrent AI sessions within the same repository, ensuring that session state remains consistent and protected from accidental data loss.

Prerequisites and Installation

To utilize this guard, you must be working within a Git-managed repository where handoff files are stored. The tool expects files to follow the standard Claude Code memory layout: ~/.claude/projects/<encoded-cwd>/memory/handoff-<branch>-<topic>.md. Installation requires copying the provided hooks, scripts, and rules into your local ~/.claude directory. You must also merge the provided settings into your ~/.claude/settings.json file to ensure the hooks are correctly wired. Finally, you must install the per-device git pre-commit hook to ensure that commits do not inadvertently mix handoff files from different sessions. The following command sequence is used for the initial setup:

# 1. Copy hooks/skills/rules into your ~/.claude
cp hooks/*.mjs        ~/.claude/hooks/
cp -r hooks/test      ~/.claude/hooks/
cp scripts/*          ~/.claude/scripts/
cp -r skills/handoff  ~/.claude/skills/
cp rules/*            ~/.claude/rules/

# 2. Merge settings.example.json into ~/.claude/settings.json (additive arrays)

# 3. Install the per-device git pre-commit hook (handoffs live in a git repo)
bash ~/.claude/scripts/install-git-hooks.sh

# 4. Verify
node --test ~/.claude/hooks/test/*.test.mjs

The Ownership Handshake Workflow

The system relies on a unique ownership marker, formatted as <!-- claude-session: 9e0d3802-... -->, which must exist as the first line of every handoff file. Because an AI session does not natively know its own session_id, the first write attempt for a new handoff file is intentionally designed to fail. When this failure occurs, the block reason provided by the guard will explicitly state the session's ID. The user or the model must then copy this ID, prepend it to the file as the required ownership marker, and retry the operation. This one-time handshake ensures that the file becomes self-identifying for all future interactions, effectively locking the file to that specific session. This mechanism ensures that ownership travels with the artifact through git, across devices, and through file moves, providing a robust defense against accidental overwrites.

Defense Mechanisms and Mutation Surfaces

To prevent a model from routing around the guard, the tool covers all primary mutation surfaces. The Write tool validates the marker in the new content, while the Edit tool validates the marker currently on disk, blocking edits to legacy files that lack the marker until ownership is claimed. Furthermore, the Bash tool monitors shell redirects such as >, >>, tee, and sed -i to ensure that unowned writes cannot bypass the file tools. The guard is designed to be client-agnostic, accepting both the Claude Code tool schema and the Gemini CLI schema to ensure that gating one does not inadvertently disable the protection for the other. By covering these three surfaces, the guard ensures that the ownership marker remains the single source of truth for session integrity.

Philosophy and Limitations

The tool follows a 'fail open' philosophy, meaning that every hook is wrapped in a try/catch block that exits with a status of 0 on internal errors. This ensures that a bug in the guard will not brick a session, but rather degrade to standard convention. Escape hatches exist, such as setting the HANDOFF_GUARD_BYPASS=1 environment variable or creating a bypass file in /tmp, though these actions are logged for auditability. It is important to note that while the tool prevents 'unaware' clobbering, it does not prevent 'chosen' clobbering; a user can still manually archive a file or bypass the guard if necessary. Additionally, there is a rare TOCTOU (Time-of-Check to Time-of-Use) race condition if two sessions attempt to create the same new filename simultaneously, which is not explicitly locked by the system. Users should be aware that the <branch> token in a filename is not checked against the actual git branch, as cross-device resume is intended to inherit the topic regardless of the current branch state. For more information, visit https://github.com/joshduffy/claude-handoff-guard.