# 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/web`s 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](https://beafk.app/docs/what-a-crew-is.md) 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](https://beafk.app/docs/keeping-machines-updated.md).

---

beafk documentation · Projects · https://beafk.app/docs/holding-files

In this section:
- Tasks — https://beafk.app/docs/tasks.md
- Git — https://beafk.app/docs/git.md
- Commands — https://beafk.app/docs/commands.md
- Two agents, one file — https://beafk.app/docs/holding-files.md (this page)

Every page, one line each: https://beafk.app/docs/llms.txt
All of it in one file: https://beafk.app/docs/llms-full.txt