# Agent Lease

> Agent Lease is an MCP server for developer tools. Hook-enforced file leases so Claude Code and Codex stop overwriting each other. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Platforms:** CLI, Linux, macOS
- **Repository:** https://github.com/buggy1111/agent-lease-mcp
- **MCP Registry name:** io.github.Buggy1111/agent-lease-mcp
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-16

## About

Agent Lease stops two coding agents working in one repository from clobbering each other. The author describes a September 2026 incident where one agent edited a deploy script while another ran it, producing a 198 MB installer instead of a 3.7 GB one, which led to the rule that coordination agents can ignore will be ignored.

Its answer is a lease enforced by a PreToolUse hook, so an edit to a file another agent holds is refused before it happens. Leases expire after 30 minutes, a claim on several paths is all or nothing, a directory lease covers everything under it, and a free file is claimed automatically on first edit. A running script is leased while it runs. Presence, a shared message log and durable tasks live in a SQLite file, and the hook fails open by default.

It includes a CLI, a local web room and wake-up helpers for idle sessions. The README says an optional Quality Gate is a candidate pending review.

## Features

- **Hook-enforced leases:** A PreToolUse hook refuses edits to held files.
- **Leases with expiry:** A 30-minute TTL prevents a crashed agent blocking the repo.
- **Running script leases:** A script being run is leased for the duration.
- **Presence and messages:** Shows who is in the room and delivers addressed messages.
- **Durable tasks:** Send tasks with delivery state and fallback when out of quota.
- **History:** Shows who touched what and why you were blocked.

## Good for

- Run Claude Code and Codex in the same repository safely
- Reserve a directory before running a long script
- Hand a task from one agent to another with acknowledgement
- See why an edit was refused

## Install

### Claude Code (Terminal)

```sh
claude mcp add agent-lease-mcp --env AGENT_NAME='<AGENT_NAME>' -- uvx agent-lease-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "agent-lease-mcp": {
      "command": "uvx",
      "args": [
        "agent-lease-mcp"
      ],
      "env": {
        "AGENT_NAME": "<AGENT_NAME>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "agent-lease-mcp": {
      "command": "uvx",
      "args": [
        "agent-lease-mcp"
      ],
      "env": {
        "AGENT_NAME": "<AGENT_NAME>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "agent-lease-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "agent-lease-mcp"
      ],
      "env": {
        "AGENT_NAME": "<AGENT_NAME>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "agent-lease-mcp": {
      "command": "uvx",
      "args": [
        "agent-lease-mcp"
      ],
      "env": {
        "AGENT_NAME": "<AGENT_NAME>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "agent-lease-mcp": {
      "command": "uvx",
      "args": [
        "agent-lease-mcp"
      ],
      "env": {
        "AGENT_NAME": "<AGENT_NAME>"
      }
    }
  }
}
```

## Tools

- `claim`: Reserve paths ahead with a purpose and TTL
- `release`: Give back held paths
- `owner`: Show who holds a path
- `room`: Show who is present, what is held and what is new
- `say`: Post a message to the room
- `inbox`: Read messages since an id
- `send`: Send an addressed message
- `jobs`: List durable tasks
- `next_task`: Take the next task
- `ack`: Acknowledge a task
- `retry`: Retry a task
- `cancel`: Cancel a task
- `accept`: Acknowledge taking an addressed message
- `report_limit`: Report quota exhaustion so unstarted tasks move to a fallback agent
- `history`: Show who touched what and how it ended

## FAQ

### Is the lease enforced or advisory?

Enforced by a PreToolUse hook; without hooks it is only a notice board.

### What happens if an agent crashes?

Leases expire after 30 minutes.

### Where is state kept?

In a shared SQLite file, by default ~/.agent-lease/room.db.

### Does it fail closed?

By default it fails open; AGENT_LEASE_FAIL_CLOSED=1 changes that.

### How do I add Agent Lease to Claude Code?

Run this command in your terminal: claude mcp add agent-lease-mcp --env AGENT_NAME='<AGENT_NAME>' -- uvx agent-lease-mcp

### What are the best alternatives to Agent Lease?

The closest alternatives to Agent Lease are Lanes, agent-custody, Cork, agent-config and Tower.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Lanes](https://ai-powered.com/mcp/lanes): Lanes is an open-source MCP server for developer tools.
- [agent-custody](https://ai-powered.com/mcp/agent-custody): agent-custody is a freemium MCP server for security.
- [Cork](https://ai-powered.com/mcp/cork-2): Cork is a freemium MCP server for developer tools.
- [agent-config](https://ai-powered.com/mcp/agent-config): agent-config is an open-source MCP server for developer tools.
- [Tower](https://ai-powered.com/mcp/tower): Tower is an MCP server for developer tools.
- [nattermatic](https://ai-powered.com/mcp/nattermatic): nattermatic is an open-source MCP server for communication.
- [Derbent](https://ai-powered.com/mcp/derbent): Derbent is an open-source MCP server for developer tools.
- [Rhizome MCP](https://ai-powered.com/mcp/rhizome-mcp): Rhizome MCP is an open-source MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/agent-lease
