File Claiming

A Pi extension that provides a file-claiming mechanism to prevent conflicts when working with files. Tracks read, write, and exclusive claims on file paths.

pi install npm:@mikefreno/file-claiming

Features

• Three lock types: read (shared), write (exclusive write), exclusive (full exclusive)
• Auto-claim on edit: Automatically claims files on first edit/write operation
• Auto-release at turn end: Claims are automatically released when your turn ends
• TTL-based expiry: Configurable auto-release timeout (default: 5 minutes)
• Conflict detection: Clear error messages when locks conflict
• Diagnostics widget: Real-time lock status in the diagnostics footer
• LLM-callable tools: Tools for agents to claim, release, list, and check locks
• Interactive commands: Slash commands for manual lock management
• Cross-session awareness: Detects concurrent access across Pi sessions

How it works

Lock Protocol

1. Before editing a file, check if it has an active claim
2. Claim the file with the appropriate lock type
3. Edit with confidence — other tools will be blocked from conflicting operations
4. Release the claim when done (or let auto-release handle it)

Claim Types

Type	Behavior
read	Shared read access. Multiple read claims can coexist on the same file.
write	Exclusive write access. Only one write claim per file path.
exclusive	Full exclusive access. No other claim of any type allowed.

Conflict Resolution

If you try to claim a file that is locked by another tool, you will receive a conflict notification showing the blocker's claim ID, type, and owner. You can release conflicting claims manually or wait for auto-release.

Usage

Tools (LLM-callable)

Tool	Description
file_claiming_claim	Claim a file with read, write, or exclusive lock
file_claiming_release	Release a file claim by ID or path
file_claiming_list	List all active file claims
file_claiming_check	Check lock status for a specific file

Commands (interactive)

Command	Description
/file-claiming-config	View or update configuration at runtime
/file-claiming-locks	Interactive lock management

Configuration

Option	Type	Default	Description
autoReleaseTTL	number	300000 (5 min)	Milliseconds before a claim is auto-released
releaseOnTurnEnd	boolean	true	Release all claims at turn end
lockDir	string	~/.pi/agent/locks	Directory for lock persistence files
blockedTools	string[]	["edit", "write"]	Tools blocked while locks exist
showDiagnostics	boolean	true	Show lock status in diagnostics footer

Update config at runtime:

/file-claiming-config autoReleaseTTL=600000
/file-claiming-config releaseOnTurnEnd=false
/file-claiming-config showDiagnostics=false

Events

The extension emits events on the shared extension bus:

Event	Description
claim:acquired	A claim was successfully acquired
claim:released	A claim was released
claim:conflicted	A claim could not be acquired
claim:expired	A claim was auto-expired