Skip to main content

edit-guard

A tiny Claude Code hook that stops one agent session from editing a file another session changed underneath it.

The failure mode, quoted from a real-world report: "With several agent sessions on one repository, session A reads createSession, session B changes it, and A then edits on the old assumption." edit-guard watches every Read/Edit/Write through the hook, remembers what each session last saw, and blocks the write when the file moved on without you — telling the agent to re-read first.

Zero dependencies. Python standard library only. Everything stays local.

Two halves: block stale edits, inject old decisions

edit-guard is one tool with two complementary moves — defense and offense:

  • Defense (pre-edit): the PreToolUse/PostToolUse hook described above blocks a session from writing a file another session changed underneath it.
  • Offense (session-start): a new session re-reads the project's recorded architecture decisions at startup, so it doesn't violate choices made in a previous session. This half is inspired by uehara's ADR hook idea: at session start, re-read the ADRs instead of re-litigating them.

SessionStart hook setup

edit-guard inject --session-start prints a compact markdown summary of your project's docs/adr/*.md (or adr/) and DECISIONS.md — one bullet per decision: title, status, and the gist of the ## Decision section. Claude Code adds a SessionStart hook's stdout to the session context automatically, so merge this into ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "edit-guard inject --session-start" }
        ]
      }
    ]
  }
}

Tuning flags:

  • --adr-dir DIR — use this directory instead of docs/adr/adr
  • --decisions-file FILE — use this file instead of ./DECISIONS.md (pass an empty string to disable it)
  • --max-chars N — cap the output size (default 4000)

With no decision files present, the command prints nothing and exits 0 — a repo without ADRs gets no noise in its session context.

How it differs

The heavyweight answers to multi-session coordination are session buses and file-reservation servers (e.g. a worktree claim guard: a Mod-style, consultative tool — it asks who owns what, and never refuses a write). edit-guard takes the opposite stance on both axes:

  • Refusal instead of consultation. A stale write is blocked (exit 2), not warned about. Warnings get read, noted, and edited over anyway.
  • Proactive instead of only reactive. The session-start inject pushes recorded decisions into the new session before it acts, instead of only catching violations after the fact.

Block at write time, inject at start time. That's the whole design.

Install

pip install edit-guard
edit-guard install

Or from source:

git clone https://github.com/hahahahahahahahah6/edit-guard
cd edit-guard
pip install .
edit-guard install

install merges three hook entries into ~/.claude/settings.json (backing it up first, never clobbering your existing settings):

  • PreToolUse on Edit|Write|MultiEdit|NotebookEdit → edit-guard hook (may block)
  • PostToolUse on Edit|Write|MultiEdit|NotebookEdit → edit-guard hook --post-write (records the digest after your write, never blocks — this is what keeps your own consecutive edits from looking stale)
  • PreToolUse on Read → edit-guard hook --observe (records what you saw, never blocks)

Restart Claude Code afterwards. That's it — no MCP server, no daemon, no accounts.

How it works

Each hook invocation appends one line to ~/.config/edit-guard/writes.jsonl: {session_id, tool, path, digest_seen, timestamp}. When a session tries to write a file:

  1. Hash the file's current content (sha256; mtime+size for files over 50 MB).
  2. Compare against the digest that session last saw for that path.
  3. If it changed and another session touched the file in between → block (exit 2) with: "Stale edit blocked: '…' changed since you last saw it (last modified by session '…'). Re-read the file before editing."

Same-session rewrites, new files, and files only you touched are always allowed. The hook fails open: any internal error (corrupt log, unreadable file, malformed input) means "allow".

Inspect what's being tracked:

edit-guard log            # recent guarded file events
edit-guard status         # state dir / log / settings paths

Honest limitations

  • Write-after-write staleness only. The guard compares against what your session last saw through the hook. Edits made outside any hooked session (your editor, a script) are treated as your own session's drift and allowed.
  • Not a lock. This is advisory staleness detection, not mutual exclusion. Two sessions can still race within the same second; the loser is blocked, the winner wins.
  • Digest, not semantics. A reformat that changes bytes but not meaning still counts as "changed" and can block you. Re-read and retry.
  • Hook protocol is undocumented. The PreToolUse stdin shape (session_id, tool_name, tool_input) and the exit-2-blocks convention come from community documentation, not a stable API. If Claude Code changes the protocol, the hook degrades to fail-open allow.
  • Per-machine only. Sessions on different machines don't share the log.
  • The log is append-only with light pruning (keeps the last 10k of 20k lines); it is not a backup or audit trail.

Development

python3 -m unittest discover -s tests

Changelog

  • 0.2.0 — new edit-guard inject --session-start: summarize docs/adr/*.md / adr/ / DECISIONS.md into session context via a Claude Code SessionStart hook (offense to complement the pre-edit refusal hook). --adr-dir, --decisions-file, --max-chars flags.
  • 0.1.0 — pre-edit stale-write blocking across sessions.

License

MIT

Metadata

Release files for edit-guard 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for edit-guard 0.2.0
File Size Uploaded Provenance Actions
edit_guard-0.2.0.tar.gz 16.0 kB Without provenance Details for edit_guard-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for edit-guard 0.2.0
File Interpreter ABI Platform Actions
edit_guard-0.2.0-py3-none-any.whl Python 3 none any Details for edit_guard-0.2.0-py3-none-any.whl

Total release size: 28.2 kB

Release files / edit_guard-0.2.0.tar.gz

Download URL edit_guard-0.2.0.tar.gz
Size 16.0 kB
Tags Source
SHA-256 checksum
How to use checksums
ddcefccb6d55185e0b71829f6b397d96435e4cdeac3ca559893a3d3ffeecf42f
BLAKE2b-256 checksum
How to use checksums
a8a4d5f4e43b181c87550c8a9998d7628e4cde95a6b4124deb68a6725beaefbb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / edit_guard-0.2.0-py3-none-any.whl

Download URL edit_guard-0.2.0-py3-none-any.whl
Size 12.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9370b6da1703ffad7da6f193a803c8d28457615763bf727063579430b062a899
BLAKE2b-256 checksum
How to use checksums
bd0a9151e25f0dc679db2a085308a53ba08d952d4af4aa6f0798712108435a8d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for edit-guard 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page