# 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](https://github.com/unjs/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.       |