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/PostToolUsehook 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 ofdocs/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):
PreToolUseonEdit|Write|MultiEdit|NotebookEdit→edit-guard hook(may block)PostToolUseonEdit|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)PreToolUseonRead→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:
- Hash the file's current content (sha256; mtime+size for files over 50 MB).
- Compare against the digest that session last saw for that path.
- 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: summarizedocs/adr/*.md/adr//DECISIONS.mdinto session context via a Claude CodeSessionStarthook (offense to complement the pre-edit refusal hook).--adr-dir,--decisions-file,--max-charsflags. - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.