pi-file-claiming/AGENTS.md

AGENTS.md

What this is

A Pi coding agent extension that provides a file-claiming mechanism to prevent conflicts when working with files. Not a standalone app — it runs inside Pi's extension host.

Type checking

npm run typecheck    # tsc --noEmit

No build step needed — Pi loads extensions via jiti, which compiles TypeScript at runtime. index.ts is the entry point directly.

Entry point

index.ts at repo root (not src/). Exports a default function receiving ExtensionAPI.

External dependencies

The extension imports from Pi SDK packages (not in package.json — provided by the host):

• @earendil-works/pi-coding-agent — ExtensionAPI, ExtensionContext, ExtensionCommandContext, etc.
• @earendil-works/pi-agent-core — AgentMessage, ToolResultMessage, etc.
• @earendil-works/pi-tui — TUI components (if needed)
• typebox — Type for tool parameter schema definitions

The extension has no external npm dependencies — all locking logic is self-contained.

Source structure

• index.ts — extension entry, registry implementation, event bus, command registration, config command
• src/ — all logic modules:
  • config.ts — typed configuration with defaults, file persistence, validation
  • diagnostics.ts — LSP-inspired diagnostic system for lock status
  • edge-cases.ts — crash recovery, race condition prevention, path resolution, lock migration
  • event-handlers.ts — Pi lifecycle event handlers (tool_call, turn_end, session_shutdown, etc.)
  • lock-acquisition.ts — lock acquisition, auto-claim, blocking, conflict resolution
  • lock-manager.ts — atomic file operations, cross-process coordination
  • lock-types.ts — all TypeScript interfaces and types
  • notifications.ts — notification system for lock events
  • system-prompt.ts — system prompt injection for lock claiming protocol
  • tools.ts — LLM-callable tools (file_claiming_claim, release, list, check)
  • user-interaction.ts — interactive lock query UI components
• tests/ — all test files

Lock types

Three lock types with increasing exclusivity:

• read — Shared read access. Multiple tools can hold read claims simultaneously.
• write — Exclusive write access. Only one write claim per file path.
• exclusive — Full exclusive access. No other claim of any type allowed.

Runtime state

All runtime state lives in memory within the registry (ClaimRegistry). Configuration is persisted to {lockDir}/config.json (defaults to ~/.pi/agent/locks/config.json).

Tools registered

The extension registers four LLM-callable tools:

• file_claiming_claim — claim a file with a lock
• file_claiming_release — release a claim by ID or path
• file_claiming_list — list all active claims
• file_claiming_check — check lock status for a specific file

Commands registered

• /file-claiming-config — view or update configuration at runtime
• /file-claiming-locks — interactive lock management

Events emitted

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