claim
Claim ownership of files, directories, or symbols before editing to prevent conflicts and bind edits to your actor ID.
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. |