Core ideas

Core idea 1 Ephemeral Computing

An agent spends most of its time thinking, and a sandbox held for the whole task sits idle through all of it. LayerFS makes a complete Workspace cheap enough to mount for a single command, so compute exists only while a command runs.

How it works

• File calls need no computer. fs.read, fs.edit, fs.write and the rest run in your own process, straight against the Store. A write is one atomic operation and one Commit.
• Bash calls get a fresh Workspace. Mount the Branch, run the command, commit what changed, unmount. The mount copies and installs nothing; unmounting deletes the overlay and keeps the Commit.
• Nothing happens on its own. LayerFS never commits, times out or unmounts by itself, so a Workspace can also live for a whole task.

Core idea 2 Decentralized Agents

There is no server. All of a project's history is one SQLite file, the Store, on a volume the agents share, and every agent opens it directly.

How it works

• One Sandbox per agent. Each agent's container runs its own LayerFS daemon, which serves its Workspaces and reads and writes the Store in-process.
• The SDK opens it too. fs, branch and project calls run in your process against the same file; only Workspace calls go to a daemon.
• One writer at a time, briefly. Writers take turns through a short publish step (check the head, merge, publish). Reads never wait for it.

Today: every opener must share one Linux kernel, with the Store on a local ext4, xfs or btrfs filesystem. Elsewhere Store calls fail Unsupported.

Core idea 3 Multiagent Coordination

One project has many Branches, and one Branch can have many agents. Nobody locks files or takes turns: each tool call is a Commit that merges with the Branch as it is when the Commit lands.

How it works

• Different files land on top of the newer head as Committed.
• The same file is refused as Conflict, with the paths and the head it met. Nothing is committed; the agent reads the new head and edits again.
• In a Workspace, a conflict writes marker blocks into the files and the Workspace follows the new head; fix them and commit again.
• Blame and diffs name the Commit, and so the tool call, behind every line and change.

Core idea 4 Recursive Filesystem

A fork records where it starts and copies no files, so forking is cheap enough to use freely: from main, any Branch, any Commit or Layer, and from forks of forks at any depth.

How it works

• A fork is one record. branch.fork(name, fromRef) points a new Branch at its start. Its files are the start's files until it changes them.
• Changes are stored once. Each change a fork makes is shared with everything that already has it, so a losing fork costs only the bytes it changed.
• Keep the winner. branch.merge folds it back (a fast-forward when one side holds the other), and branch.publish makes it main's next Layer.

Core idea 5 Ultra Storage Optimization

Agents make copies: a Branch per attempt, a Commit per step, the same node_modules in each. Copies of the same content cost almost nothing, and what the Store keeps is compressed.

How it works

• Content addressing. Every object is named by the hash of its bytes, so identical content is stored once.
• Chunking. Files under 128 KiB are kept whole; larger ones are cut by content into chunks of about 8 to 32 KiB, so an edit changes only nearby chunks.
• Deltas and compression. A file or chunk can be stored as a delta against its last version, and everything is packed and compressed with zstd.
• Measured per Store. The operator API's store.stats reports both ratios: dedupe (logical ÷ canonical) and compression (canonical ÷ stored).

Core idea 6 Instant Bootstrap

A fresh Git checkout isn't ready to run: ignored files like node_modules and caches are missing, so every new workspace installs first. LayerFS keeps them.

How it works

• Init takes everything, once. project.init captures source, .git, dependencies, caches, symlinks and every ignored file as main's first Layer.
• A mount binds the whole tree. No scan, copy or install. The only file it creates is the Workspace's small overlay database.
• Content loads on demand. Files are read from the Store as they're opened, so the first read still pays real I/O.
• Installs are just changes. An install that changes node_modules is committed, and every later mount has it.

Supporting ideas · they back the core ones

Supporting idea 1 Auto Checkpoints

You don't save checkpoints by hand. Every change an agent makes is already a Commit, so every step is a point to inspect, compare or start again from.

How it works

• File calls commit as they write.
• Bash calls commit when the orchestrator calls sandbox.commit after the command. It saves the whole Workspace, background processes' writes included.
• No change, no Commit. A call that leaves the tree as it was ends UpToDate.
• Every Commit is a ref. Read any file at it, diff any two, or fork from one to carry on.

Checkpoints hold files only, not running processes, memory, sockets or command output.

Supporting idea 2 Append-only Objects

Nothing the Store has saved is ever rewritten. Chunks, file trees, Commits and Layers are written once and then only read.

How it works

• Named by content. Every object's id is the hash of its bytes; a Commit's id comes from its tree, parents and message.
• Sealed packs. Objects are written into packs, and the Store refuses to update or delete a written pack.
• Safe sharing. Forks, merges and other agents point at the same objects without copying them, and readers never wait for a writer.
• History stays true. Deleting a file only stops later Commits from naming it; older ones keep it.

Immutable isn't durable: the Store runs WAL with synchronous=OFF, so a host crash can lose recent work. There's no garbage collection yet, so the Store only grows.

Supporting idea 3 Conflict Rules (.lww)

Lockfiles, generated code, build output and caches are rewritten wholesale by tools, and a line merge of them is useless. A /.lww file names them, and for those paths the newest edit wins.

How it works

• Rules at the root. /.lww holds gitignore-style patterns; %include <file> pulls in more.
• Newer wins. When a matched path changed on both sides, the side with the newer modification time wins (ours on a tie), with no conflict. Other paths merge line by line.
• Whose rules. A Workspace Commit reads the Branch head's; branch.merge(a, b) reads a's.
• Recorded. Every decision is listed under lww in the result and kept on the Commit.

A rule drops the older side's change. Use it for files a tool can regenerate, never for code people write.

Supporting idea 4 Big File, Small Edit

Editing a few bytes of a large file shouldn't cost the whole file. An overwrite, append or truncate costs about the size of the change and the depth of the file's tree, not the file's size.

How it works

• Files are trees of extents over their content chunks.
• The overlay keeps only what was written, not a copy of the file.
• The Commit edits the tree in place, rebuilding only the changed extents and their path to the root; the rest is shared with the previous version.
• Ordinary writes, by any program on the mount. No special call, and no file size limit.

An insert or delete in the middle has no POSIX write, so most programs rewrite everything after it, and that rewrite is what gets saved.