Initial commit

README.md

@@ -0,0 +1,87 @@
+# 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.
+
+```bash
+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 |