Agent::Lock (v2.0.1)

Advisory locks on files and folders with pluggable backends (redis and file-system provided out the box, with redis being the default if it's available locally). This locking tool is meant to be used by the coding agents that share a checkout.

agent-lock is a gem with one executable, alock (also installed as agent-lock). An agent runs alock acquire <scope> before it writes, and learns in one reply whether anybody else is working there: who, since when, and doing what. It works for separate sessions in one checkout, and for the sub-agents of a single session, which is the harder case.

Git does not help here. Two agents on one branch and one working tree never produce a conflict: the second writer simply wins, and the first one's work is gone without an error anywhere. A lock stops that, but only if every writer can be named reliably, even though an agent harness runs each command in a brand new shell. Making that name stable, and keeping claims correct when several agents ask at the same moment, is most of what this gem does.

• People running several coding agents at once (Claude Code, Codex, Cursor, a terminal of your own) in the same checkout.

• Orchestrators that fan out sub-agents into one worktree, each taking a different part of it.

• Harnesses that launch agents over a repository and need them to stay out of each other's way.

Not for work that can have a checkout of its own. A git worktree per agent removes the sharing altogether, which is better than coordinating it. The locks are advisory: they protect a file only from agents that check. --enforce exists for the few files that must not move at all.

gem install agent-lock
alock version        # alock must be on PATH

Or add gem "agent-lock" to a Gemfile.

alock acquire "lib/billing/**" "rewriting the invoices"   # claim a corner of the tree
alock check   "lib/billing/tax.rb"                        # exits 1 if somebody else holds it
alock note    "lib/billing/**" "totals done, specs red"   # where you are, for whoever comes next
alock list                                                # everything held in this repository
alock release-all                                         # when you are done

A refusal tells you who and what, not just that you lost:

$ alock acquire lib/billing/tax.rb
REFUSED, do not write here
HELD  lib/billing/**  by luke-backend  since 2026-09-09T21:04:11Z
      intent: rewriting the invoices

Exit 1 means do not write there. Exit 2 means the command could not run at all.

The orchestrator claims the area it hands out, running alock bare. Each sub-agent then claims its own part of it, naming itself on every call:

alock acquire "src/**" "fanning out the billing work"            # orchestrator

AGENT_ID=billing-a alock acquire "src/billing/**" "tax rounding"  # sub-agent A
AGENT_ID=billing-b alock acquire "src/billing/tax.rb" "..."       # sub-agent B: REFUSED, held by billing-a
AGENT_ID=billing-a alock release-all                              # A's own locks, never the orchestrator's

sequenceDiagram
  participant O as Orchestrator (alo)
  participant A as Sub-agent billing-a
  participant B as Sub-agent billing-b
  participant S as Lock store (.git/agent-locks)
  O->>S: acquire src/**
  S-->>O: ACQUIRED
  par fan out
    A->>S: AGENT_ID=billing-a acquire src/billing/**
    S-->>A: ACQUIRED, parent inferred as the orchestrator
  and
    B->>S: AGENT_ID=billing-b acquire src/billing/tax.rb
    S-->>B: REFUSED, held by billing-a
  end
  B->>S: AGENT_ID=billing-b acquire src/shipping/**
  S-->>B: ACQUIRED
  A->>S: AGENT_ID=billing-a release-all
  Note over O,S: the orchestrator's src/** survives its children's release-all

Three things matter, and each one fails silently if skipped:

1. The name goes on every call. Sub-agents run inside the parent's process and would sign every lock as the parent. Each call is also a fresh shell, so an export AGENT_ID from an earlier call is gone. AGENT_ID=<name> alock whoami shows the name a lock would be signed with.

2. Run alock in the checkout being written, with cd or --dir. A lock in another repository protects nothing.

3. Sub-agents claim even inside the orchestrator's lock. The orchestrator's lock keeps other sessions out; only a sub-agent's own claim keeps its siblings out.

The gem ships a skill that teaches an agent all of the above, so the rules reach the agents rather than living only in this README. Install it into the skills directory your agent reads:

alock skill install                    # default: into ~/.agents/skills, for most agents
alock skill install --for claude       # into ~/.claude/skills instead
alock skill install --into some/path   # anywhere else, --for is ignored if both are given
alock skill path                       # where the bundled copy is

install refuses to overwrite a copy that differs (--force replaces it) and never touches a symlink, since a symlink is some other installer's.

If skills on your machine are installed from repositories by a manifest, name this one as a source instead, so the skill is recorded along with where it came from. For example:

- name: agent-lock
  type: skills
  repo: git@github.com:kigster/agent-lock.git
  path: skills

Then put the rule where every agent reads it, such as CLAUDE.md or AGENTS.md:

Several agents may work in this checkout at once. Before creating or editing
files, load the agent-lock skill and claim the narrowest scope that covers your
writes:

    alock acquire <scope> "<what you are doing>"

If it refuses, work somewhere else. A sub-agent prefixes every call with its
own name: AGENT_ID=<sub-agent-name> alock acquire ... Release with
`alock release-all` when you are done.

Advisory locks work because everybody checks. That is why the rule belongs in the instructions your agents load, and not only here.

In order of preference:

The fingerprint walks up from the current process until it finds an ancestor that is not a shell. That is the claude or codex process driving the session, or the terminal a person is typing in. Its pid, start time, uid and hostname are hashed into a name like claude-1f4c8a02, which stays the same for as long as the session lives and differs from anybody else's.

alock whoami prints the name this session would sign a lock with, its parent, and where each came from. Run it before the first claim if in doubt.

The store is $(git rev-parse --git-common-dir)/agent-locks.

Outside a git repository the store falls back to ~/.agent-locks, keyed by a digest of the tree.

---
agent_id: luke-backend
scope: workflow/**
status: active
pid: 69232
created_at: 2026-09-09T21:04:11Z
---
rewriting the installer

## Progress
- 2026-09-09T21:14:02Z installer rewritten, specs still red

An agent that runs into this learns who holds the scope and what they are doing, so it can decide whether to wait or to work somewhere else. A human can read the same file in an editor.

Two scopes conflict when either one's fixed part contains the other's. So workflow/** conflicts with workflow/lib/cli.rb, and docs/** does not conflict with workflow/**.

A scope is read from where you stand, globs included, and an absolute path inside the tree is made relative. So $PWD/lib/** and lib/** are the same claim, and *.rb typed in lib/ is lib/*.rb. Only ., * and ** mean the whole tree from anywhere. Two things are refused with exit 2 rather than guessed at:

Ownership and blocking are separate questions, and conflating them is what lets sibling sub-agents overwrite each other.

A sub-agent claiming inside its parent's lock gets a lock of its own, and that lock is what keeps its siblings out. Asking for exactly the parent's scope is refused, since that would leave nothing for a sibling to be kept out of; claim something narrower. A sub-agent's release-all gives back its own locks and its children's, never its parent's.

Claude Code runs sub-agents inside the parent's own claude process, and sets nothing in the environment that tells them apart. They therefore share the parent's fingerprint, and without help every one of them would sign locks as the parent and none would ever block another.

So a sub-agent names itself, on every call, since each command runs in a fresh shell and an export does not survive to the next one:

AGENT_ID=luke-backend alock whoami                        # id luke-backend, parent claude-1f4c8a02 (inferred)
AGENT_ID=luke-backend alock acquire lib/billing/** "invoices"
AGENT_ID=luke-backend alock release-all

When AGENT_ID is set and AGENT_PARENT_ID is not, the parent is taken to be the session's own name, CLAUDE_SESSION_ID if the harness exports it and the fingerprint otherwise, which is the orchestrator running bare alock. Set AGENT_PARENT_ID explicitly when the parent named itself too.

A lock is cleared out of the way when its holder is provably gone: the process that signed it has exited, on this machine. A holder on another machine cannot be checked, so its lock is trusted until nobody has touched it for AGENT_LOCK_STALE_MINUTES (120 by default). Every note counts as a touch. What happens next depends on whether anything was written down:

$ alock acquire workflow/**
INTERRUPTED WORK on workflow/**, left by luke-backend
  alock resume workflow/**   # take it back, notes and all
  alock break workflow/**    # throw it away and start over

A live holder's lock is never cleared, however old it is. An agent may legitimately work on one scope for hours, and deleting its lock underneath it would hand its files to the next agent while it is still writing them. Past the stale window list, check and mine tag it STALE instead, and taking it is a break that somebody announces first.

$ alock list
Locks held (2):
app/**	orchestrator	2026-09-11T16:04:56Z
  fanning out
docs/**	slow-agent	2026-09-11T13:04:55Z	STALE
  rewriting the guides
Interrupted (1):
db/**	crashed-agent	2026-09-11T15:54:55Z	INTERRUPTED
  splitting the migrations

Only live claims are counted as held. --json gives every record its status and a stale flag.

Flags:

Any command exits 2 when it cannot run at all: a scope that is empty or outside the tree, a backend mismatch, or a store it cannot reach.

alock completion bash > "$(brew --prefix)/etc/bash_completion.d/alo"
alock completion zsh  > "${fpath[1]}/_alo"

Names every command and flag alock currently knows, since the script is generated from the same registry the CLI runs, rather than hand-maintained separately from it.

Redis stores the same documents as the file store, and buys two things a filesystem cannot: its mutex holds across machines, and a TTL expires an abandoned lock without anybody having to reason about liveness. A tree defaults to Redis when one answers on REDIS_URL, and falls back to the file store, which needs nothing installed, when none does.

AGENT_LOCK_BACKEND=redis alock acquire workflow/**   # force it, rather than autodetect
AGENT_LOCK_BACKEND=file  alock acquire workflow/**   # or force the file store instead

Either way, every claim checks for conflicts and writes its lock while holding one mutex for the whole store. Refusing an atomic write of an identical scope is not enough on its own: lib/** and lib/cli.rb are different keys, and two agents claiming them at the same moment would both find the store empty and both win. The file store takes an exclusive flock on .mutex beside the locks. Redis takes agent-lock-mutex:<tree digest> with SET NX PX and a random token, and gives it back with a compare-and-delete script, so a process whose lease ran out cannot release somebody else's.

The redis gem ships as a dependency of this one now, since deciding the default means probing for it. If you never want that probe, or never install a local Redis, set AGENT_LOCK_BACKEND=file yourself.

acquire --enforce also runs chflags uchg on every matched file, which makes them unwritable by anything, whether it checks for locks or not.

alock acquire "config/credentials/**" "keys must not move during the migration" --enforce

bin/setup
bundle exec rspec                              # 228 examples, against the file backend
AGENT_LOCK_TEST_BACKEND=redis bundle exec rspec # the same suite, against Redis instead
bundle exec rubocop

The suite runs against one backend at a time, picked by AGENT_LOCK_TEST_BACKEND rather than the machine's own default, so it stays deterministic whether or not Redis happens to be running: only the examples that test one backend's own on-disk or on-Redis shape care which one that is, and a Redis run defaults to database 15 so it never touches whatever database a developer's own Redis work lives in. CI runs both, plus rubocop as a third, independent job.

A justfile covers the rest: just test, just test-coverage, just ci (rubocop then coverage), just format (autocorrect, then regenerate .rubocop_todo.yml), and just publish/just release for cutting a version. just lint currently names standardrb, which is not one of this gem's dependencies; use bundle exec rubocop until that recipe is reconciled with the rest of the project's tooling.

The library decides and the CLI prints. Every verb is a method on Manager that returns a result and prints nothing, so the whole lifecycle can be tested without capturing output. Launcher takes argv, stdin, stdout, stderr and kernel as arguments, and nothing below it calls puts or a receiverless exit, which is what lets Aruba run the CLI end to end inside the test process instead of forking a Ruby per example.

MIT

• Konstantin Gredeskoul @kigster
• Claude Code, @claude