Coordinate with files

A shared folder can hold tasks, messages and handoffs for Claude Code, Codex, other agents and people. The folder layout is a convention you choose. flockfs provides shared files, permissions, atomic operations and history.

For example:

tasks/todo/12-fix-login.md
tasks/doing/
tasks/done/
inbox/codex.md
inbox/claude.md
notes/contracts.md
AGENTS.md

Each task is Markdown: describe the work, its dependencies and how to check it. Keep the task's filename unique. Put the team's working rules in AGENTS.md.

Take a taskCopy Anchor Link

Create a claim file exclusively before starting work. Through a live mount:

cd ~/WorkLive
mkdir -p claims
python3 -c 'open("claims/task-12.md", "x").write("Codex: fixing login\n")'

Start work only if exclusive creation succeeds. Concurrent creators have exactly one winner; the others receive an existing-file error. The claim and its history show who took the task. Move the task into tasks/doing/ for organization after claiming it, and into tasks/done/ after recording the outcome.

Create claims/ once during setup before launching agents. Without a mount, use the same strict file operation through CLI or MCP:

printf '%s\n' 'Codex: fixing login' | flockfs put claims/task-12.md --exclusive

MCP: use a server whose write tool advertises exclusive, with path, content and exclusive: true. An existing file is never replaced. CLI mv and MCP move also provide strict revision-checked moves, so either can take a task directly from tasks/todo/ into a unique agent-specific destination.

If an agent stops, a person can inspect its work and clear its claim. This file convention has no automatic lease expiry or dependency scheduler.

Reserve a resourceCopy Anchor Link

Use an exclusive file such as claims/database-migration.md for a shared port, database or other resource. Write the owner and purpose in it. Remove the file after releasing the resource. If its owner stops, inspect the resource before clearing the claim.

On macOS NFS mounts, do not infer ownership from a successful mkdir or mv: the kernel can translate a competing operation's error into success to handle retransmissions. Our 20-mount tests confirmed this behavior. Use exclusive file creation, or strict CLI/API operations, for reservations. Apple's NFS source shows the rename handling; the directory handling is at line 5433.

Send messages and share changesCopy Anchor Link

Append messages through flockfs's atomic append operation:

flockfs append inbox/codex.md 'Alice: the login response now includes expires_at.'
flockfs append notes/contracts.md 'Codex: changed the login response; update callers.'
flockfs watch --prefix tasks/

MCP offers append and changes for the same purpose. Include enough context for another agent to act: the file, change, affected callers and next step. Use history and the activity timeline to see which credential made each change.

Use a live operation for reservationsCopy Anchor Link

Make task claims and resource reservations through the mount, CLI or MCP. A flockfs sync folder is a local copy: offline operations can race before they reach the server. It remains useful for notes, editor access and offline work, but a local move in that copy does not establish a global reservation.

Keep permissions scoped to each agent's work. File operations reserve paths; they do not enforce who is allowed to use an external port or database.

Give each agent its own tokenCopy Anchor Link

Run each agent with its own token, limited to the folder it works in, so its changes carry its name and it can't touch anything else:

flockfs run --agent-token-name pricing --scope research/pricing -- claude

The token lasts one day and is revoked when the agent exits.

Shared context and memory are foldersCopy Anchor Link

Instead of passing long transcripts between agents, have each subagent write its result to a file the orchestrator reads, for example research/findings/pricing.md. Notes an agent keeps between runs work the same way: give it memory/<agent>/ with edit access, and read access to the others'. People can read and fix all of it in the app, and history keeps every version.

When an agent says "I'll do X", have it append that to commitments.md with its name. The file outlives the chat, and history shows whether the promised files changed.

Freeze a section while you rewrite itCopy Anchor Link

Before a multi-step change, an agent can lock a whole file, a range of lines or a Markdown section with the MCP lock tool. Others' edits to that part are refused while the lock lasts, and everyone keeps editing the rest. Locks expire on their own (10 minutes by default), so a crashed agent never leaves anything frozen.

Undo one agent's runCopy Anchor Link

flockfs timeline shows what each agent did, including reads, searches and refused edits. If one run goes wrong, undo just that run and keep everyone else's later edits:

flockfs sessions                 # recent runs: who, when, how much changed
flockfs undo --session <id>

Hear when files you read changeCopy Anchor Link

Agents working in parallel go wrong when they act on a file someone else has since changed. When an agent reads files through MCP (read or fetch), flockfs remembers what it saw. If someone else changes one of those files, the agent's next tool result says so, once:

Heads-up: files you read were changed by someone else since then. Read them again before relying on them:
- specs/api.md (you read it at 2026-10-06T10:02:11Z): changed by codex (2 changes, last at 2026-10-06T10:04:40Z)

The changed_since_read tool lists all of them until the agent reads them again. Within a flockfs run session this follows that run; otherwise the agent's own reads from the last two hours.