# 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 |