Two agents, one file
Every agent on the machine takes the files it is about to edit, so a second one queues instead of writing over an hour of the first one's work.
Two agents are working in the same checkout. One rewrites lib/parse.go. The
other, four minutes later, writes its own version over the top. An hour of work
is gone, nobody sees it happen, and the commit looks fine.
Hold files while editing is the switch that stops that, and it is on by
default.
It is the machine's, not one chat's
This is not a crew feature and it is not a setting on a chat. It is a
lock table on the machine, and every agent on that machine is in it —
Claude Code, Codex, Grok Build, Kimi Code, every chat you have open,
every piece of work a crew has handed out, and a chat that was reopened after a
restart.
Nothing in that table leaves the box. Claims are per folder: two agents in the
same project meet, and agents in two different projects never do.
What it does
Before an agent's first edit it takes the files it is about to change. A
second agent reaching for one of them is told who is in there and what they said
they were doing, and waits.
It is not only the files it named. What those files import is held steady too,
and so is anything that imports them — an agent coding against an API should not
have that API move underneath it. Those neighbours are held for reading only, so
nobody is blocked for merely looking at a file.
What it catches that a lock cannot
An agent that dies mid-edit does not leave a file locked for ever. Its hold is
released within a minute, and the next agent to take that file is told the
contents may be half-written.
An edit made outside the protocol — you, in an editor, or a script — is
noticed too: the next agent to take the file is told it changed while nobody
held it. Holds are advisory, so nothing here can stop a write. What it makes
impossible is a write that is silent.
Seeing who is in what
There is a board for it — the same lock table the agents read, arranged for a
person. It answers one question: is anything on this machine busy right now,
and who is in it.
It is the machine and not the folder you happen to have open. Agents work in
several checkouts on one box, and a board that followed the project on screen
said "every file is free" about a machine with eleven files shut in the other
one. So every checkout the machine knows is on the one board, each under its
own name — the caption over a group of files begins with the repository, which
is also what tells two internal/webs apart.
What is drawn is what is actually claimed, folded back into folders: the files
somebody named, the files held steady around them because something imports
them, and anything that was edited outside the protocol. The rest of each
checkout is not listed.
The faces beside the count are the agents holding something. An agent that
merely has the machine open — a CLI sitting in a chat nobody has prompted — is
said at the foot of the board instead, on the line that begins "also here,
holding nothing", because it has taken none of the files the number counts.
It is not a tile on the home screen. It is where the question gets asked
instead:
- settings → this machine, as a row that is always there;
- the system screen, as a card under the agents whose holds it is showing —
and only when something is held.
The board refreshes every three seconds, because it is a screen somebody watches
while waiting for a colleague to come out of a file.
When you will notice it
Any time you have two chats open on one project — the same agent on two
jobs, or two different agents on one repository. That is the ordinary shape of
this machine, which is why the guard is on by default.
A crew is the sharpest version of the same thing: a lead
handing out pieces of one job is several agents in one checkout, all of them
reaching for the same files. The crew's own switch and this one sit in the same
sheet.
What it costs
Under a millisecond for a typical claim. The pause you might see is the other
agent still writing, which is a pause you wanted. There is nothing to configure
and nothing to install.
The switch, in three places
They are one switch and they move the same bit on the machine:
- the ＋ sheet, under how this chat runs — nearest to hand, and it still
changes the machine rather than that chat;
- settings → behaviour, as a row with the same words;
- settings → skills → built in, where it is the
hold-files page with a
switch on it.
The ＋ wears a mark when this is off, which is the other way round from
every other switch there. On is normal. The state worth interrupting somebody
for is four agents running with the guard turned off.
Turn it off when you are certain there is one agent on that machine and you
would rather it never paused. The hint under the row says which state you are
in: other agents queue instead of writing over each other, or nothing is held
— two agents may edit one file.
A machine running an older version of beafk has no row at all. Update it —
keeping machines updated.