Agent Lease

Name: Agent Lease
Author: Buggy1111

by Buggy1111version 0.2.0i★ –iRuns on your computer

Registry nameio.github.Buggy1111/agent-lease-mcp

Install

Overview

Description from the maker (original English)

Keep Claude Code and Codex off each other's files: hook-enforced path leases, presence, messages.

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi1 of 1 passedChecked from public information; code not scanned yet
UsageiVery new↓ 42/wk · ★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Runs on your computer
Transport: stdio
Category: Docs, sheets & office work
You need to fill in: AGENT_NAME

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 1 of 1 passed
Runs on your computer with your user’s permissions (files, network, apps).
You fill in yourself: AGENT_NAME, AGENT_LEASE_DB

You need

PyPIPython’s uv installed (for the uvx command)

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

{
  "mcpServers": {
    "agent-lease": {
      "command": "uvx",
      "args": [
        "agent-lease-mcp"
      ],
      "env": {
        "AGENT_NAME": "your-value",
        "AGENT_LEASE_DB": "your-value"
      }
    }
  }
}

Run this in your terminal

claude mcp add agent-lease --env AGENT_NAME=your-value --env AGENT_LEASE_DB=your-value -- uvx agent-lease-mcp

Fill in the empty values before running it.

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "agent-lease": {
      "command": "uvx",
      "args": [
        "agent-lease-mcp"
      ],
      "env": {
        "AGENT_NAME": "your-value",
        "AGENT_LEASE_DB": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "agent-lease": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "agent-lease-mcp"
      ],
      "env": {
        "AGENT_NAME": "your-value",
        "AGENT_LEASE_DB": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

This one runs on your computer, and ChatGPT can only connect to servers on the internet. Pick another app.

Your choice stays on this device in a cookie; no account needed.

Values you fill in

AGENT_NAME required env
This agent's name in the room, e.g. claude-code or codex. Must match the hooks.
AGENT_LEASE_DB env
Path to the shared SQLite room (default ~/.agent-lease/room.db).

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 8, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account Buggy1111, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
– Not applicable
Endpoint responds
This one runs on your computer; there is no internet endpoint
– Not applicable
Sign-in with OAuth
Runs on your computer and uses local settings instead
… Not checked yet
No hidden instructions in tool descriptions
Runs on your computer; we can only read tool lists from internet endpoints

Compared with others in Docs, sheets & office worki

More stars than 0% of the other 3547 servers in this category
Published to the registry more recently than 59% of the other 3547 servers in this category
Basic checks equal to or better than 100% of the other 3547 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Agent Lease safe?

It passed 1 of 1 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

You need to fill in: AGENT_NAME

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed –, and the latest version (0.2.0) reached the registry 22 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Python (uv) on your computer.

What can I use instead?

In the same category: Agent-Native Calendar, Excel MCP Server, MCP Server for Excel

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:↓ Downloads per weeki★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

Agent-Native Calendar

Agent-Native Google Calendar - manage events, sync, and public booking

by BuilderIOGrowing★ 7.6KUpdated 2 months ago

Runs in the cloud

Install

Excel MCP Server

Lets AI create and edit Excel files itself, including formulas, charts and PivotTables, without Excel installed.

by haris-musaWidely used↓ 49.6K/wk★ 4.3KUpdated 7 days ago

Runs on your computer

Install

MCP Server for Excel

Excel automation for AI - Sheets, Power Query, DAX, VBA, Tables, Ranges and more. Windows only.

by sbroenneGrowing↓ 4.3K/wk★ 847Updated 5 days ago

Runs on your computer

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

agent-lease-mcp

Keep two coding agents (Claude Code and Codex, or two sessions of either) from overwriting each other's work in the same repository.

agent-lease gives them leases on paths, presence and a shared message log — and the lease is enforced by a PreToolUse hook, not by good intentions. An agent that tries to edit a file another agent is working on is refused before the edit happens.

Česky / Czech version

Why it exists

9 September 2026. A coordination file, docs/AGENT-HANDOFF.md, existed and both agents knew about it. At 22:28 they still both touched deploy/make-work-package.sh: one was editing it while the other was running it. Bash reads a script as it goes, the text shifted under the running process, and instead of a 3.7 GB installer the build produced a useless 198 MB one.

The lesson the whole project rests on: coordination that can be ignored will be ignored. Not out of malice — an agent at work simply does not look at the notice board.

The same collision was later replayed on purpose: Codex ran the script, Claude Code tried to edit it mid-run, and the hook refused the edit. The file stayed intact.

How it differs

	locks	enforcement	TTL	presence	messages	audit
AgentRoom (paper)	✅	prompt only	?	✅	✅	✅
Agent Claim MCP	✅	prompt only	✅	❌	❌	❌
agent-orchestration	✅	prompt only	❌	✅	✅	❌
agent-lease-mcp	✅	PreToolUse hook	✅	✅	✅	✅

Advisory locks get broken; AgentRoom documents this itself. Claude Code and Codex both have PreToolUse hooks with the same semantics (exit 2 = block, reason on stderr), so a lease can be enforced deterministically at the tool-call level. One script serves both clients.

Rules it is built on

A lease, not a lock. 30-minute TTL. A crashed agent cannot block the repo forever.
All or nothing. A claim on several paths succeeds completely or not at all.
A lease on a directory covers everything under it.
A free file is claimed automatically on the first edit, so nobody has to remember to call claim.
A running script is leased for the duration of the run — exactly the combination that broke the build.
Fail-open by default. Broken coordination must not stop work; otherwise the first thing anyone does is switch the hook off. AGENT_LEASE_FAIL_CLOSED=1 flips this for unattended runs.

What runs on its own

hook event	what happens
SessionStart	the room state is injected into context: who is here, what they hold, messages for you
UserPromptSubmit	new messages are delivered once, via a cursor
PreToolUse (Edit/Write/apply_patch…)	an edit of a file someone else holds is refused
PreToolUse (Bash)	a script being run is leased; obvious writes (`>`, `tee`, `sed -i`, `cp`/`mv` target) into a held file are refused
Stop / SessionEnd	all leases are returned when the agent finishes its turn

Injections stay silent when there is nothing to say.

Waking a sleeping agent

Hooks only fire when the agent acts, so an idle session is woken from outside, without spending model tokens:

Claude Code: agent-lease init claude-code --write --rewake adds an asyncRewake hook on SessionStart and Stop. It waits on a signal file and wakes the session when an addressed message from someone else arrives. Broadcasts and automatic receipts do not wake it.
Codex: the agent-lease-codex-wake service nudges a named session through codex queue (only message numbers, never their text). After a provider limit ends, it nudges once for unfinished work. Setup: /rename nox in Codex, AGENT_LEASE_CODEX_THREAD=nox in ~/.config/agent-lease/environment, then enable deploy/systemd/agent-lease-codex-wake.service.

A message from another agent is information, not a human instruction. For agents to hand work to each other unattended, the human writes the allowed scope (and what always needs asking) into the agent's own instructions, e.g. ~/.codex/AGENTS.md. Template and details (in Czech): docs/ZPRAVY-A-POTVRZENI.md.

Tools

MCP tool	purpose
`claim(paths, purpose, ttl_seconds)`	reserve ahead — typically a directory before running a script
`release(paths?)`	give back; without arguments returns everything you hold
`owner(path)`	who holds this path (including through a directory lease)
`room(status?)`	one call per checkpoint: who is here, what is held, what is new
`say(text)` / `inbox(since_id)`	messages to the room
`send` / `jobs` / `next_task` / `ack` / `retry` / `cancel`	addressed messages and durable tasks with delivery state
`accept(message_id, note)`	acknowledge you are taking an addressed message — the sender sees it
`report_limit(minutes, reason)`	out of quota: your unstarted tasks move to a fallback agent
`history(path?)`	who touched what and how it ended — the answer to "why was I blocked"

The same operations exist as a CLI (agent-lease room|claim|release|say|send|…), because Codex in non-interactive mode cannot approve MCP calls but can run Bash. agent-lease wait --for blocks without spending model tokens and wakes a background session when a message arrives.

say/inbox is not a live chat: MCP is pull, the other side reads a message when it next looks. For a live view there is a local web room: agent-lease web --open (loopback only, see Security).

Quick start (two minutes)

uv tool install agent-lease-mcp

agent-lease init claude-code --write --rewake # writes all hooks, keeps a .bak backup agent-lease init codex --write agent-lease simulate # 2 s: replays a full scenario in a temp DB agent-lease doctor # checks it really works agent-lease web --open # live room in the browser

init without --write only shows what it would write. Manual setup below.

Install

uv tool install agent-lease-mcp

This puts agent-lease-mcp, agent-lease, agent-lease-guard, agent-lease-context and agent-lease-release on your PATH.

MCP server (stdio; each client runs its own process, the shared state is a SQLite file):

# Claude Code

claude mcp add agent-lease -e AGENT_NAME=claude-code -- agent-lease-mcp

# Codex — ~/.codex/config.toml

[mcp_servers.agent-lease] command = "agent-lease-mcp" env = { AGENT_NAME = "codex" }

Codex writes to ~/.agent-lease, outside the workspace — allow it:

[sandbox_workspace_write] writable_roots = ["/home/YOU/.agent-lease"]

Hooks — without them this is just a polite notice board:

// ~/.claude/settings.json

{ "hooks": { "PreToolUse": [{ "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash", "hooks": [{ "type": "command", "command": "AGENT_NAME=claude-code agent-lease-guard" }] }], "SessionStart": [{ "hooks": [{ "type": "command", "command": "AGENT_NAME=claude-code agent-lease-context" }] }], "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "AGENT_NAME=claude-code agent-lease-context" }] }], "Stop": [{ "hooks": [{ "type": "command", "command": "AGENT_NAME=claude-code agent-lease-release" }] }] } }

// ~/.codex/hooks.json — same events, AGENT_NAME=codex

{ "hooks": { "PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "AGENT_NAME=codex agent-lease-guard" }] }] } }

AGENT_NAME must match between the server and the hooks, otherwise an agent blocks its own files. An agent called unconfigured-* in room means exactly that.

variable	default	purpose
`AGENT_NAME`	`unconfigured- -`	name in the room
`AGENT_LEASE_DB`	`~/.agent-lease/room.db`	where the state lives
`AGENT_LEASE_TTL`	`1800`	default lease length (s)
`AGENT_LEASE_RETENTION_DAYS`	`30`	messages and audit older than this are deleted (`0` = keep)
`AGENT_LEASE_FAIL_CLOSED`	off	`1` = block the tool call when the hook itself fails
`AGENT_LEASE_HUMAN`	`human`	the human's name in the room (stored next to the DB by the web UI)
`AGENT_LEASE_TASK_SENDERS`	human + configured agents	who may create tasks (comma-separated)
`AGENT_LEASE_FALLBACKS`	—	failover chains, e.g. `codex=claude-code;claude-code=codex`

Optional: Bash safety gate

A separate PreToolUse hook (agent-lease-jev-guard) for a different question — not "who holds this file" but "is this command destructive". Hard rules (rm -rf /, force push, git reset --hard, curl | sh, mkfs…) apply as soon as it is wired in. An optional external classifier (TypeSafe Jev) is off by default, starts in shadow mode, receives only redacted commands and is advisory — never the only safeguard. Details in ADR 0003.

Receipts, failover, bridge and broker

Every addressed message has a visible state ⏳ → 👁 seen → ✔ taking → done. "Seen" is written by the hook automatically; "taking" must be acknowledged by the agent (accept) and is reminded on every prompt. Nothing gets lost silently. agent-lease overdue lists what nobody acknowledged.
Limits and failover. Codex workers read the explicit typed availability signal from the local App Server. Other workers record a limit only after a real provider/CLI error; if no reset time is supplied, agent-lease does not invent one. Manual agent-lease limit / MCP report_limit remains available. Unaccepted, unstarted tasks then move to the next agent in AGENT_LEASE_FALLBACKS (e.g. codex=claude-code;claude-code=codex) after a grace period, and the sender is told.
Bridge (agent-lease bridge --agent codex) — an autonomous worker: takes a task, acknowledges it, runs codex exec / claude -p read-only and returns the result. --provider openrouter --model sends it to any model through OpenRouter as plain text without tools (read-only; good for review and a second opinion). Keys only from the environment. Worker presence/provider state uses a separate identity (codex-bridge, claude-code-bridge), so a headless quota cannot overwrite the state of an interactive agent.
A task never runs twice. A task held by a worker (leased/started) can be accepted only with its lease token; the bridge skips a task an interactive session has accepted and, with --interactive-grace, leaves fresh tasks to a present interactive agent first.
Broker (agent-lease broker) — single SQLite writer over a 0600 Unix socket; other tools use it automatically when it runs, so a sandboxed Codex does not need direct access to the database. Clients survive a broker restart: the connect is retried (nothing was sent yet), an interrupted call is never repeated, and long-running workers continue with the next call.
Overview panel in the live room: each agent's active task, queue, unacknowledged items, typed provider state, reason for waiting, limits and items to review. Tasks may declare repeatable --path worksets and a --priority; the scheduler skips paths held by another agent and the board shows the blocking path, owner and TTL. agent-lease notify --loop sends to Telegram only what waits on the human, each event at most once (TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID from the environment; --dry to test).
Operating workers safely. agent-lease worker-activate and agent-lease failover-activate set a safe starting point without running or moving any task: only wo

Only the beginning is shown; read the rest in the repo

Agent Lease

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

Values you fill in

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Docs, sheets & office worki

Common questions

Alternatives

Agent-Native Calendar

Excel MCP Server

MCP Server for Excel

README from the maker

agent-lease-mcp

Why it exists

How it differs

Rules it is built on

What runs on its own

Waking a sleeping agent

Tools

Quick start (two minutes)

Install

Codex writes to ~/.agent-lease, outside the workspace — allow it:

Optional: Bash safety gate

Receipts, failover, bridge and broker