LayerFS for AI coding agents: what the agent filesystem adds over git worktrees, and what v1.0.0 ships

LayerFS is an open-source filesystem for coding agents that records every change an agent's tool calls make as a commit in one shared store, and gives each shell command its own writable workspace over that history. Ephemeral AI Lab tagged v1.0.0 on 21 October 2026, and by 23 October the repository had 1,966 stars. Version 1.0.0 runs its store only on Linux, keeps no crash-safe history, and has one official agent integration so far, a preview plugin for DeepSeek Harness.

What is LayerFS?

LayerFS is an MIT-licensed Rust project from Ephemeral AI Lab, a small lab whose founder, GitHub user yifanxuaaa, wrote 3,988 of the 4,025 commits at the v1.0.0 tag. It keeps a project's whole tree in one SQLite file, which the docs call the Store, and lets many agents work on branches of it at once. The tagline is "Ephemeral Workspaces. Durable Shared History."

The first import takes everything: "source, .git and its index, node_modules, build caches, symlinks and every ignored file. Git ignore rules don't filter LayerFS state" (concepts). That is the pitch against a git worktree, which starts with tracked files only and needs an install before tests run. It also means local .env files go into the Store, which the docs do not warn about.

LayerFS does not replace Git. The FAQ says .git "is part of the tree like any other file, so Git works inside a Workspace as usual."

LayerFS turns every change an agent makes into a commit

LayerFS handles two kinds of tool call. File tools call the SDK in process: each write or edit lands in the Store as one commit, and reads record nothing. A shell command mounts a FUSE workspace over a branch inside a Docker container, runs, commits whatever changed (sources, lockfiles, node_modules, build output) and unmounts. Mounting copies no files; content loads from the Store as it is read.

One frame of the animated "Ephemeral Computing" card from the LayerFS README. Image: Ephemeral-AI-Lab/layerfs by Ephemeral AI Lab, MIT.

The JavaScript SDK at the v1.0.0 tag shows the cycle (SDK README):

import { LayerFS } from "@layerfs/sdk";
const layerfs = new LayerFS("website", { storePath: "/layerfs-store/global/store.sqlite" });
await layerfs.project.init("./website");
await layerfs.branch.fork("feature");
await layerfs.fs.write("feature", "/README.md", "Hello\n", "Update introduction");
const page = await layerfs.branch.list_commits("feature", 20, 0);
const text = await layerfs.fs.read("feature", "/README.md", 1, 20);
const ws = await layerfs.workspace.mount("feature"); // { sandbox: "1", path: "/workspaces/1" }
await layerfs.workspace.exec(ws, "npm test", "Run tests");
await layerfs.workspace.commit(ws, "Save changes");
await layerfs.workspace.unmount(ws);

The docs site still shows the pre-1.0 sandbox.* calls that workspace.* replaced. Each container holds up to 16 workspaces and stops after two idle minutes, though an open issue reports an abandoned workspace keeping one "running forever". Commits hold files only, not processes or command output. And branch.publish "overwrites. It doesn't merge with Layers published since the Branch forked", so merge main into a branch before publishing it.

Two agents editing the same lines get a Conflict, not a race

LayerFS takes no file locks. Each commit runs a three-way merge against the branch head as it lands: changes to different files go through, edits to different lines of one text file merge, and overlapping edits are refused as Conflict, with nothing half-committed. In a workspace the refused commit writes <<<<<<< workspace marker blocks into the file, and LayerFS refuses to commit again until the agent resolves them.

The exception is a /.lww file of gitignore-style patterns, where "the side with the newer modification time wins (ours on a tie), with no conflict." The docs reserve it for regenerated files such as dist/: "never for code people write." Rust tests at the tag cover the cases: four workspaces writing four files all publish, edits to lines 1 and 5 of one file merge, and two edits to the same line conflict.

The README describes the rule more strictly than the code applies it: "Two Commits that change the same file are refused with Conflict, unless a .lww rule says the newest edit wins." The merge table in concepts and the merge code at the tag both line-merge text. Git worktrees, by contrast, give no warning at all until someone merges the branches.

LayerFS sits under the agent, beside git worktrees and the container

LayerFS fills the file-isolation slot that git worktrees fill in most parallel-agent setups: what each agent sees as its checkout. It also starts a Docker container per pool of workspaces, but it is not a security product. Its own benchmark table lists the container as needing /dev/fuse and CAP_SYS_ADMIN, and the file calls run in the agent's own process on the host.

Sources: LayerFS compare page, git-worktree, Claude Code worktrees, read 23 October 2026.

Claude Code runs claude --worktree and copies ignored files listed in .worktreeinclude; Cursor cleans up worktrees beyond 25 per machine by default. LayerFS has no official integration for any of them. Two third-party projects created on 22 October, a WSL setup that runs Claude Code on LayerFS and an MCP server for any MCP client, had no stars a day later. The comparison of multi-agent workspaces and the sandbox comparison cover the layers on either side.