claim
Reserve files and symbols to prevent editing collisions and bind changes to your actor ID. Specify intent for conflict resolution and use wait or queue to handle denials.
Instructions
Reserve files BEFORE you edit them — a claim placed before editing is also what BINDS your external edits to your actor id, so claim whole files first as the default. Use a bare path for a whole file, a trailing slash for a whole directory (e.g. convex/_generated/ — right for codegen output), or path#symbol (e.g. utils.js#formatPrice) to reserve one function so others can edit other parts of the same file in parallel (a symbol that does not exist in the file is denied with a suggestion, since it would bind nothing). Pass a short intent (the why) so an actor you block can resolve the collision from it. A denied target is held by another actor — its holderIntent tells you what they're doing, so reconcile from that instead of just waiting.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | seconds to BLOCK waiting for holder-denied targets to free up (holder releases, commits, or their lease lapses) instead of polling yourself. Returns as soon as everything grants. Capped at 120 per call — re-call to keep waiting. Denials that waiting can't fix (bad path, missing symbol) return immediately. | |
| actor | No | actor id to act as. Auto-derived per connection when omitted (from the client name, e.g. cursor-3fa2), so naming is optional for a single agent. Pass an explicit id (your role/task name) when several subagents share one server — they have no ambient identity to tell them apart — or when you want a stable id across runs. | |
| paths | Yes | ||
| queue | No | ASYNC alternative to wait: if denied by a holder, register interest and return immediately — you are AUTO-GRANTED the target when it frees. Do NOT block. Keep working; the grant appears in get_status as `grantedWhileWaiting`. Best when you have other work to do meanwhile. | |
| intent | No | a short why for this claim, e.g. the ticket/task | |
| creating | No | allow symbol claims for symbols you are ABOUT TO ADD to an existing file (they bind at write time). Without it, a symbol missing from the file is denied. |