agentFS

01

The life of an edit

One edit, start to finish. AgentFS is the filesystem, so when an editor or an agent saves, AgentFS is what performs the write. It is in the store the moment it happens — nothing is watched, scanned or reconstructed afterwards. Staging is an attestation: "this state of the tree is one I stand behind", with a message and an id. Integrating puts that snapshot on main.

1. edit
   task-a · src/auth/session.rsclaude-code:7f3a91

     pub fn validate(&self, now: Instant) -> Result<(), SessionError> {
         if self.revoked {
             return Err(SessionError::Revoked);
         }
   +     if now > self.issued_at + self.ttl {
   +         return Err(SessionError::Expired);
   +     }
         Ok(())
     }

   An ordinary save from an ordinary editor. AgentFS is the thing that carried it out.
2. op
   The write itself — AgentFS did itafs ops task-a

   op

   write src/auth/session.rs

   by

   claude-code:7f3a91 · Edit

   when

   14:02:09.417

   before

   9834db81 8b7df01e …

   after

   04b6fa59 ebef7161 …

   payload

   splice @1204 +87 B −0 B

   stored: the delta — 87 bytes plus the row. Not a diff taken later: this is the write, with everything the filesystem knew when it made it. Already visible in afs diff task-a.
3. stage
   Your "commit"immutable snapshot

   $ afs stage task-a -m "add session expiry"
   staged snapshot: a91f3c2e

   Nothing new is written — the bytes were already in the store. Staging pins them: an immutable snapshot with a message, the unit that gets integrated, replayed, materialized and blamed. stored: the snapshot's index; session.rs's new version, once.
4. integrate
   Onto mainhead move

   $ afs integrate a91f3c2e
   main → a91f3c2e   # other workspaces see it when they advance
   $ afs push -m "add session expiry"           # optional: main → a git commit in your repo

   stored: 0 B of content — main now points at the snapshot.

If you think in git: write ≈ save, afs stage ≈ "commit", afs integrate ≈ fast-forward main. The difference is that nothing waits on the "commit" — the filesystem made every write, so every write is already durable and attributed; staging only says which state you vouch for.

02

Isolated, and on the record

Each workspace sees only its own changes; nothing reaches your repo or another workspace until it is integrated. And AgentFS does not track what changed after the fact — it is the filesystem, so it is the one doing the writing. It knows which workspace, which file, which harness and session, which command, and the bytes before and after, because it wrote them. There is nothing to notice and nothing to miss.

03

When workspaces race

Snapshots integrate one at a time. When several are waiting, the outcome depends only on whether they touched the same files — a fact, not a guess, since the filesystem made every one of those writes. Nothing ever merges on its own.

1. afs integrate <snap-a> Integrates First in, in. main moves.
2. afs integrate <snap-b> → afs replay Different files → replays automatically Stale head, so the snapshot is replayed onto the new one. Disjoint paths, no questions asked.
3. afs integrate <snap-c> → conflict → afs reconcile Same file → rejected → a merge workspace The integrate is refused. Reconcile makes a workspace from the new head with the snapshot merged in: clean hunks merged, collisions marked. Fix, build, test, stage, integrate. Nothing merges silently.

04

Your repo stays your repo

05

Using it

# once: your repo becomes an AgentFS workspace, in place
$ afs adopt myrepo . --mount

# per task: a fresh workspace, warm caches, agent memory inherited
$ afs new task-a
$ afs enter task-a            # or start an agent with cwd = /mnt/task-a

# when it's done: checkpoint, then put it on main
$ afs stage task-a -m "add session expiry"      # → snapshot id
$ afs integrate <snap>         # onto main; replay / reconcile if it bounces
$ afs push -m "add session expiry"   # main → your repo, as a git commit

Ships with Wigwam; wigwam sync replicates the record between your machines, end-to-end encrypted.

06

Platforms

The mount is what makes copies free; the filesystem underneath is what makes warm caches free. Isolation, the record, integration and replication are the same everywhere. What differs is how a workspace presents its build directories — target/, node_modules/, dist/ — and afs doctor tells you which you have.