Metadata-Version: 2.5
Name: agent-file-claim
Version: 0.1.0
Summary: Two coding agents, one file: the second write is refused with who holds it. Claude Code and Codex hooks, no server.
Project-URL: Homepage, https://huggingface.co/memento-team/claude-plugins
Project-URL: memento Team, https://overflow.games/memento/?ref=pypi-claim
Author: memento
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,claude-code,codex,file-lock,hooks,parallel-agents
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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`):

```json
{
  "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:

```json
{
  "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.
