worklease

Provider-neutral coordination for humans and coding agents.

Tell your agents to claim work with worklease to prevent them from working on top of each other or competing for the same resources and tasks. Compatible with whatever backlog or provider you're using.

Tell each agent to claim work before starting and release it when done:

sequenceDiagram
    participant A as Worker A
    participant W as Worklease
    participant B as Worker B
    A->>W: acquire task:demo
    W-->>A: claim granted
    B->>W: acquire task:demo
    W-->>B: already claimed
    A->>W: release
    B->>W: acquire task:demo
    W-->>B: claim granted

Loading

Worklease or a lockfile?

Choose	When
A lockfile	Processes on one host need a critical section. You do not need lease ownership, expiry, history, or recovery.
Worklease	Independent workers claim tasks or resources and need TTLs, waiting, status, history, guarded commands, or recovery. Use the local authority on one host or a remote authority across hosts.

Both coordinate cooperating workers. Neither stops arbitrary external work.

Install

Install the latest release with mise:

[tools]
"github:brettinternet/worklease" = "latest"

mise install
worklease version

Or build from source with Go 1.27.1:

mise run build
./bin/worklease version

Release archives are named worklease-vVERSION-{linux,macos}-{x64,arm64}.tar.gz. They contain bin/worklease and share/man/man1/worklease.1.

Checksums are in checksums.txt. Linux amd64 and arm64 server images are published to ghcr.io/brettinternet/worklease:vVERSION; see container deployment.

Set up with your agent

Point your agent to the agent setup guide and state the intended topology:

• Coordinate locally.
• Join an existing remote authority.
• Host a new remote authority.

The guide covers installation, scope, verification, and the small project instruction block to leave behind. Share remote invites privately, not in the prompt or repository.

Once Worklease is installed, start with worklease instructions setup. worklease instructions remote covers joining an authority; worklease instructions server covers hosting one, not the optional MCP server.

Shell completion

Add the matching line to your shell configuration:

# ~/.bashrc
source <(worklease completion bash)

# ~/.zshrc
source <(worklease completion zsh)

For Fish, generate its conventional completion file:

mkdir -p ~/.config/fish/completions
worklease completion fish > ~/.config/fish/completions/worklease.fish

Restart the shell or source its configuration after installing Worklease.

Quick start

Claim a resource, do the work, then release it:

worklease acquire -r task:demo
# do the work
worklease release

Add a stable session, TTL, wait, guarded command, and release reason as needed:

# Claim for 20 minutes; wait up to 2 minutes if busy.
worklease acquire -r task:demo -s loop-a -t 20m -w 2m
# Run only while loop-a holds the claim.
worklease exec -s loop-a -- worklease version
worklease release -s loop-a -m done

Local claims use owner-private SQLite. Give each concurrent loop a unique -s; its authority-bound handle stays private. -s is the contextual handle selector, not a resource namespace.

Worklease exposes non-secret claimant metadata:

• agentId — the claimant identity
• sessionId — ownership-epoch metadata (generated when no selector is set)
• workKey — what it says it’s working on
• claimId and expiry

Open the TUI with bare worklease to inspect, renew, and release local claims—no queue configuration needed:

See the CLI reference for provider, credential, replay, polling, coordination-only, and guarded-operation options.

Work queue

Browse and claim work from GitHub, Backlog.md, Beads, Linear, or an external adapter:

worklease queue init   # detect this checkout's source; --dry-run previews
worklease              # open the TUI
# Agent loop: select, claim, and mark the next ready item in progress
worklease --json queue next --view Ready --claim --start --session loop-a

See TUI and queue configuration.

Remote authority

Start an authority with local TLS and the coordination: prefix:

# Authority host
worklease server init
worklease serve

# Administrator: securely copy the bootstrap invite printed by server init
worklease enroll --invite-file PATH_PRINTED_BY_INIT
worklease invite issue

# Worker: securely copy the invite printed by invite issue
worklease enroll --invite-file PATH_PRINTED_BY_INVITE_ISSUE
worklease acquire --resource coordination:demo
worklease list
worklease heartbeat
worklease release

Invite files and credentials are bearer secrets. Keep them out of checkouts and logs, then remove one-time invites.

Bare worklease enroll uses a hidden prompt.

Remote

For a non-loopback listener, set the client endpoint explicitly:

worklease server init \
  --listen 0.0.0.0:8443 \
  --endpoint https://HOST:8443 \
  --confirm-non-loopback
worklease serve

Customize

Configuration precedence is flags, then WORKLEASE_SERVER_CONFIG, then server.yaml. Common flags are --admitted-prefix, --tls-cert with --tls-key, --bootstrap-invite-file, and --server-config. Editor schemas for all five user-authored Worklease YAML files are in configuration schemas.

Cleartext requires both --transport http and --acknowledge-cleartext-credentials.

Remote mode is explicit. The default CLI opens no listener and makes no network request. Local reads remain setup-free. Remote failures do not fall back to local coordination. serve owns one namespace and SQLite writer; guarded commands and provider effects stay on clients.

Remote authority is experimental. It provides no high availability, provider fencing, or exactly-once execution. See the remote authority guide for test setup, profiles, administration, and recovery.

JSON and MCP quick start

Put --json before the command for one schema-version 2 envelope. Errors have a stable reason, exitCode, and details. Contention is a structured outcome, not a parsing failure.

worklease --json acquire --resource loop-a --session loop-a
worklease --json acquire --resource loop-b --session loop-b
worklease --json status --session loop-a
worklease --json status --session loop-b
worklease --json release --session loop-a --reason done
worklease --json release --session loop-b --reason done

Contention example:

worklease --json acquire --resource shared --session contender-a
worklease --json acquire --resource shared --session contender-b
# exits 2 with error.reason "already-claimed" and holder metadata, never a token
worklease --json release --session contender-a --reason done

Run the stdio server:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"server/discover"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","_meta":{"protocolVersion":"2026-07-28"}}' \
  | worklease mcp

Handles are private server-side references. MCP intentionally exposes a smaller surface than the CLI.

For the MCP tool boundary, see MCP tools.

Recovery and safety

Situation	Rule
New mutation	Omit --operation-id.
Lost response	Replay the exact request with its operation ID. A changed request conflicts.
Started guarded operation	Treat the outcome as unknown until you establish the effect and process cessation, then reconcile it.
Expired claim	Ownership ended. An external process may still be running.
Copied state	Handles and cursors stay bound to their original authority ID.

Resources match exact bytes within one authority. Repository and path identities are host-local.

Credentials come from a private handle, --token-file, or --token-fd, never an argv bearer token. Keep them out of output, logs, checkpoints, provider comments, and handoffs.

See:

• CLI reference
• Claim, operation, and recovery model
• MCP and JSON
• Setup and native hooks
• Container deployment
• Remote authority
• Work queue configuration
• TUI
• Work queue design record

Development

mise run ci

ci formats, vets, tests, race-tests, scans vulnerabilities, builds the binary, runs clean-checkout end-to-end smoke, and renders the manual.

Release process

1. Curate and order ## Unreleased in CHANGELOG.md.

2. Create the dated release section:

   go run ./cmd/worklease-release --version 1.2.0 --prepare-changelog 2026-09-13

3. Review and commit the new section, then tag that commit as vVERSION.

4. Prepare archives with mise run release -- --version VERSION.

The changelog command rejects empty entries, invalid versions or dates, duplicates, and existing releases. The tagged workflow publishes the matching changelog section verbatim.

Tagging and publishing require separate owner authorization. Experimental remote artifact jobs may build and smoke-test on matching runners without publishing, tagging, or pushing.

Prior art

Worklease builds on established task-claiming, agent-coordination, and distributed-locking patterns. The closest widely used projects differ mainly in what they coordinate and how much workflow they own. Worklease can claim exact resource names such as task:bd-a1b2, file:src/auth.go, port:3000, and deploy:staging.

Project	Coordinates	Claim model	Worklease advantage
Beads	Backlog tasks	Atomic assignment with expiring leases and heartbeats	Claims tasks, files, ports, deployments, or any other exact resource name.
Gas Town	Multi-agent workspaces and tasks	Agent assignment backed by Beads work state	Coordinates workers without owning their runtime, worktrees, or backlog.
MCP Agent Mail	Agent messages and files	Advisory TTL reservations for files and globs	Coordinates any resource and can run commands only while a claim is held.
Consul	Distributed processes and services	Session-backed locks and semaphores with guarded commands	Works locally without a service and can move to a remote authority when needed.
etcd	Distributed processes	TTL-backed mutexes with guarded commands	Provides an agent-focused CLI, JSON, MCP, history, and recovery model.

Worklease stays deliberately narrower than the agent platforms and task trackers above. It provides local or remote claims, expiry, waiting, history, guarded commands, and recovery without owning the backlog or orchestrating the agents.