---
title: "Claims and leases"
description: "Claim the files or modules a task will change, queue behind another agent's overlapping claim, and check two branch heads for a merge conflict with git merge-tree before either pull request merges."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.overlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Claims and leases

Two agents rarely mean to edit the same file. They do it because neither knew. A claim tells every other agent which scope a task is about to change, for how long.

```sh
overlane claim acquire --task task-12 --path apps/api-worker/src/billing/
overlane claim list
overlane claim renew --claim clm_abc123
overlane claim release --claim clm_abc123 --done
```

## Scope you can claim

- **A path**: a file, or a directory, which claims everything under it.
- **A glob**: `src/billing/**`, `docs/**/*.md`. A pattern is relative to the repository root and cannot leave it.
- **A module**: a name resolved through the [code map](/library-docs/) where the project is indexed. For a module the map does not know, give the paths it covers with `--paths`. With neither, the claim is refused instead of guessed.

```sh
overlane claim acquire --task task-12 --module billing
overlane claim acquire --task task-13 --module newmod --paths packages/newmod
```

A claim is `exclusive` by default. Two `shared` claims never conflict with each other; a shared and an exclusive claim on the same scope do.

## When claims overlap

The project's policy decides what happens to the second claim:

| Policy | Second agent's claim |
|---|---|
| `serialise` (default) | Queued behind the holder, in arrival order. It becomes active when the holder releases or its lease ends. |
| `refuse` | Refused with exit code 5, naming the holder and the next command. |
| `allow` | Granted, with a warning listing the overlap. Use the merge check below. |

Two agents asking at the same moment are never both granted: claims are ordered by a sequence number and settled in that order.

## Leases

A lease keeps a claim from outliving an agent that went away. The default is 30 minutes, set per project. `claim renew` extends it, and also records the branch and head you are on. A claim never lives longer than 24 hours in total, and a queued claim that waits more than four hours expires. Only the holder can renew or release before the lease ends; once it ends anyone can see the scope is free.

## The pre-merge conflict check

A claim says what an agent intends to touch. The check says what happens when two branches meet.

```sh
overlane claim conflicts --a feat/billing --b feat/review
overlane claim conflicts --all
overlane claim readiness --claim clm_abc123
```

`claim conflicts` runs `git merge-tree --write-tree` between the two commits in your checkout. That merges them in memory and changes no branch and no file. It needs git 2.38 or later and both commits present locally. The result, with the names of any conflicted files, is recorded with the service. Exit code 5 means a conflict was found.

`claim readiness` combines the claim and the recorded checks. It is not ready when the claim is queued, when no check exists for the current heads of a pair, when a check failed to run, or when a conflict is recorded. A record for an old head never counts: after one pull request merges, the other branch's base moved and its check runs again. `claim conflicts --all` checks every open pair that has no current check.

A client's own run is recorded as evidence with the principal that reported it. The command above is the way to run the check.

## Native and GitHub projects

The same commands work for a native project (provider `overlane`) and a GitHub-connected one. The claim lives in Overlane; the check runs on commits in your checkout, wherever they came from.

Command reference: [claim acquire](/cli/claim-acquire/), [claim list](/cli/claim-list/), [claim renew](/cli/claim-renew/), [claim release](/cli/claim-release/), [claim readiness](/cli/claim-readiness/) and [claim conflicts](/cli/claim-conflicts/).

Source: https://docs.overlane.app/control-plane/claims/index.mdx