Agent Fridge
GitHub

Agent Fridge

Stop AI coding agents from overwriting each other's work.

Different agent harnesses coordinate their own workers - not each other. An agent team, a solo coding agent, an IDE agent, and a human can all be correct inside their own context and still collide in one checkout. Agent Fridge gives them one vendor-neutral path-ownership layer.

Install and try it See the coordination gap
  • No daemon
  • No cloud service
  • No database
  • No mandatory MCP server

The engineering problem

Every harness has a plan. The checkout has no shared owner.

A team lead can coordinate the agents it spawned through an internal task board. A second harness, IDE agent, or human terminal cannot see that board, and none of those private plans creates repository-wide path ownership.

The failure is larger than agent versus agent. It is coordination island versus coordination island. Terminal A can run a multi-agent team whose lead, reviewer, builder, and tester all agree on an internal task list. Terminal B can run a different harness with a different lead and a different list. Terminal C can hold a solo agent or a human. Every lane can look green locally.

The Git checkout sits outside those harness boundaries. Claude Code, GitHub Copilot, Codex, an IDE agent, tmux panes, and plain terminals can all target the same path without seeing one another's intent. Git records the final bytes after editing; it does not establish ownership before editing begins.

Terminal A Agent-team harness
lead reviewer builder
internal tasks: coordinated
Terminal B Different harness
architect author tester
separate plan: coordinated
Terminal C Solo agent + human
CLI agent IDE agent human
local context: coordinated
Repository boundary one shared Git checkout
src/checkout/routes.ts design/checkout/copy.md release.md
No universal path owner

Green inside one harness does not mean safe across the repository. Internal task boards coordinate their own teammates. Agent Fridge coordinates at the checkout boundary, where every harness and terminal can see the same claim.

Green insideEach harness believes its own team is coordinated.
Same filesEvery harness can still mutate the same checkout paths.
No shared ownerIntent is invisible until a cross-harness claim exists.
A team task board is not a repository lock. A shared_tasks.md file can coordinate teammates inside one harness and still be invisible to every other harness touching the same project.

The incident

Two well-behaved agents. About 128 lines gone.

The original failure was not a reckless edit. It was a correct read, correct work, and correct write performed concurrently against one shared Markdown file.

Terminal A - agent alpha

$ read shared-development-updates.md

212 lines loaded

$ implement checkout validation

tests: 18 passed

$ append progress and write file

227 lines written

Terminal B - agent beta

$ read shared-development-updates.md

212 lines loaded - stale copy

$ prepare release evidence

docs: complete

$ append progress and write file

214 lines written - alpha's update disappeared

  1. Both terminals read the same 212-line document.

  2. Terminal A writes its expanded 227-line version.

  3. Terminal B writes a stale 214-line version based on the earlier read.

  4. The file is valid Markdown. The missing work is not reported as a conflict.

No model instruction can make a shared writer safe. "Read first," "append carefully," and "do not erase other work" were all obeyed. The unsafe primitive was read-modify-write against one file. Safety has to come from the storage shape, not a stronger reminder.

The coordination layer

Claim paths first. Generate the board last.

Agent Fridge makes each participant authoritative only for its own records. The human-readable board is derived from those records and can be rebuilt at any time.

  1. ClaimTake the narrow paths needed for the task.
  2. CheckAsk before expanding into another path.
  3. PinWrite progress as a separate immutable note.
  4. HeartbeatRenew leases during long work.
  5. HandoffTransfer ownership without an unowned gap.
  6. ReleaseFree the path and record the outcome.
1

Stable refusal

An overlapping exclusive claim exits `10`. Scripts can branch on it and agents can stop before writing.

2

Sharded authority

Claims, leases, sessions, and notes are separate records. One participant never rewrites another participant's record.

3

Derived overview

`.fridge/DOOR.md` is generated, disposable, and never read as protocol state.

The invariant: authority is sharded; the overview is derived. No daemon, cloud service, database, or mandatory MCP server is required.

Only now, the metaphor

Think of it like a fridge door for the repo.

Every housemate pins their own note. One magnet claims a chore. Stale magnets fall off. Nobody rewrites somebody else's note to add their own.

The metaphor is memorable because the technical boundary is precise: separate writers, visible ownership, expiring claims, and one generated view of the room.

Illustrative workspace

One checkout, four lanes, one visible refusal.

This fictional project runs four terminals on one machine against one checked-out integration branch. The PR numbers are work references, not four local branches.

Checkout coordination scene All data is fictional and sanitized.

Code review - PR #41Remote diff plus local read-only checks

shared claim
review-claude
$ fridge claim "src/checkout/**" --mode shared \
  --task "Review PR #41; read only"
Card clm_review is yours.

$ gh pr diff 41 -- src/checkout
$ fridge pin "PR #41: rounding path needs a boundary test"

Collision lab: change the second claim

Claim 1
$ fridge claim "design/checkout/**" --task "Design checkout UX"
Card clm_design is yours.
exit 0
Claim 2
$ fridge claim "src/api/checkout/**" --task "Build checkout API for PR #42"
Card clm_api is yours.
exit 0

The four original claims are disjoint.

Topology truth: these panes share one checkout, so they share live claims. Separate Git worktrees or clones do not share live `.fridge/` state. Worktrees provide real file isolation; coordinate scope between them through GitHub, issues, or a human plan. Agent Fridge can still coordinate several participants inside any one worktree.

Before, after, and underneath

The storage shape is the safety mechanism.

The old path has concurrent writers targeting one document. The new path gives each participant its own record and derives the overview.

Before and after diagram: shared Markdown loses about 128 lines, while sharded Agent Fridge notes lose zero.
Read-modify-write collision on the left; one-writer-per-record authority on the right.
Protocol flow from terminal participants through claim, check, pin, and release commands to sharded records and a generated DOOR.md.
The CLI is the integration surface. `.fridge/` records are authoritative; `DOOR.md` is the derived view.

Real command contract

A two-terminal transcript with machine-readable exits.

The important output is not the prose. It is the stable exit code that lets a person, shell script, hook, or agent stop before a collision.

Terminal A - initialize and claim 
fridge init
export FRIDGE_ACTOR=claude-review
fridge join --agent "$FRIDGE_ACTOR" --vendor claude
fridge claim "src/api/**" --task "Refactor the router" --ttl 30m
fridge pin "Router split started; baseline tests pass"
fridge heartbeat
Terminal B - overlapping claim 
export FRIDGE_ACTOR=copilot-fix
fridge join --agent "$FRIDGE_ACTOR" --vendor copilot
fridge claim "src/api/routes.ts" --task "Fix route copy"
Somebody already has that chore.
  who     claude-review
  scope   src/api/**
  doing   Refactor the router

E_CONFLICT: overlapping paths.
exit 10
Owner hands off or releases 
fridge handoff clm_... --to copilot-fix \
  --note "Routes done; error path and docs remain"

# Or, when complete:
fridge release clm_... --outcome done \
  --note "Router split complete; focused tests pass"

Where it works

If it can run a command, it can use the board.

There is no vendor SDK. Participants invoke `fridge`, read plain ASCII output, and branch on exit codes.

Coding agents

Claude Code Codex Pi GitHub Copilot Cursor Any CLI agent

Terminal layouts

Herdr tmux screen Zellij Plain shells

Operating systems

macOS Linux Windows PowerShell WSL

People and automation

Humans CI jobs Shell scripts Hooks Makefiles

The operating model

A collaboration loop, not just a lock command.

`COLLABORATE.md` defines how a real team joins, reports progress, expands scope, recovers stale leases, and hands unfinished work to another owner.

  1. JoinUse one unique actor identity per terminal.
  2. ReadOpen the board and inbox before choosing work.
  3. ClaimTake the narrowest writable paths.
  4. CheckVerify every expansion before editing.
  5. PinRecord durable progress and proof.
  6. HeartbeatRenew ownership during long work.
  7. HandoffTransfer or release without ambiguity.

The handoff contract

  1. What changed
  2. Proof and tests
  3. Remaining work
  4. Risks and uncertainty
  5. Affected paths
  6. Pull request or issue link
Copyable handoff 
fridge pin "HANDOFF PR #42: checkout validation changed; focused tests pass; retry test and docs remain; timeout behavior is the main risk; paths: src/api/checkout/**"

fridge handoff clm_... --to release-pi \
  --note "PR #42; proof pinned; retry test and docs remain"
Read COLLABORATE.md Read terminal interop

Honest comparison

Use the stronger or simpler tool when it fits.

Agent Fridge solves one narrow case: cooperating participants editing one checkout at the same time. Several alternatives are better outside that case.

Approach Where it wins Where it stops
Git worktrees Real physical isolation, separate branch and index, no advisory trust needed. Live claims do not cross worktrees; builds and dependencies may be expensive to duplicate.
Git branches Review, revert, cherry-pick, remote sharing, and independent lines of work. Two branches cannot be checked out concurrently in one working tree; merge cost arrives later.
Shared Markdown Excellent when one human is the only writer and everyone else reads. Concurrent read-modify-write is lossy and has no conflict exit.
`flock` or lockfiles Simple, battle-tested protection for one short critical section on one machine. No path-set overlap model, owner task, handoff, durable history, or native Windows story.
SQLite or a local database Transactions, queries, constraints, and strong serialization for a purpose-built coordinator. Requires a schema and client surface, is awkward in Git, and still needs a universal integration contract.
MCP coordination server Tool calls are ergonomic and reliable when every participant is an MCP client. A server must be configured and kept alive; shells, humans, hooks, and CI are not all MCP clients.
Agent Fridge Portable path claims, leases, handoffs, attribution, and write-once history with no service. Advisory only, local to one checkout, and not a replacement for branch or OS isolation.
The default recommendation: use worktrees when independent branches and duplicated build state are acceptable. Use Agent Fridge when several participants intentionally need the same uncommitted checkout.

Try it locally

One binary. Sixty seconds to the first refusal.

The primary Go binary is self-contained. A complete zero-runtime-dependency Node implementation passes the same conformance vectors.

macOS and Linux

Download the latest binary and verify its checksum.

POSIX installer
curl -fsSL https://github.com/RagnarPitla/agent-fridge/releases/latest/download/install.sh | sh

Windows PowerShell

Install the native Windows binary.

PowerShell installer
irm https://github.com/RagnarPitla/agent-fridge/releases/latest/download/install.ps1 | iex

Go toolchain

Go 1.21 or newer, standard library only.

Go install
go install github.com/RagnarPitla/agent-fridge/cmd/fridge@latest

Node implementation

Node 20.11 or newer, zero runtime dependencies.

npm install
npm install -g github:RagnarPitla/agent-fridge
60-second quickstart 
fridge init
fridge join --agent claude --vendor claude
export FRIDGE_ACTOR=claude
fridge claim "src/api/**" --task "Refactor the router"
fridge board
Reproduce shared-file loss, then prove zero notes lost 
git clone https://github.com/RagnarPitla/agent-fridge.git
cd agent-fridge
npm run demo
Download a release Full quickstart GitHub repository

Scope and trust boundary

Coordination for cooperating writers, not a security sandbox.

Agent Fridge trusts every process that can write to `.fridge/`. That is the same boundary as the working tree itself.

What it solves

  • Invisible path ownership inside one shared checkout.
  • Silent overlap between cooperating participants.
  • Shared Markdown status-file races.
  • Stale ownership through expiring leases.
  • Unattributed progress and incomplete handoffs.

What it does not solve

  • A hostile or careless process that ignores exit `10`.
  • Merge conflicts between separate worktrees, clones, or branches.
  • Cross-machine coordination on network filesystems.
  • Git staging, branch switching, review, or deployment policy.
  • Secrets management, authentication, or filesystem isolation.

Security properties

Path traversal and symlink escapes are refused. Records are atomic. There is no network, telemetry, shell concatenation, or mutating Git command.

Operator responsibility

Only a human should authorize force recovery. Notes are durable and may be committed, so never pin credentials, customer data, or private source text.

Read SECURITY.md Read the full comparison Read protocol wcp/0.1

Open source, Apache-2.0

Try the race. Inspect the records. Challenge the protocol.

The repository ships the incident demo, two independent implementations, conformance vectors, parity tests, real multi-process tests, and the full on-disk protocol.

Star or fork on GitHub

Choose the right starting point

Use `COLLABORATE.md` to bring Agent Fridge into a real project. Use `CONTRIBUTING.md` when you want to change Agent Fridge itself.

Collaborate Contribute