LayerFS is an agent workspace plane, not your source of record.

The useful abstraction is speculative custody

Parallel coding agents create a filesystem problem before they create a model problem. Each worker needs a complete project view. It needs dependencies and ignored build artifacts, not only tracked files. It needs to explore a bad idea without blocking another worker. The orchestrator needs to inspect exactly which tool call changed a file, compare candidates, reject conflicts, and promote one result. Copying a repository for every branch works at small scale, but it turns checkout time, dependency installation, disk use, and cleanup into the coordination substrate.

LayerFS packages copy-on-write, content-addressed storage, workspace overlays, branches, commits, and conflict rules around agent tool calls. A file operation can become an atomic Store operation. A Bash call can mount a Workspace, execute, commit its changed state, and unmount. The result is a dense history of machine work that can be branched and rewound without requiring an agent to remember when to run git commit.

That density is not the same as durable custody. The current 1.1.0 repository states that its Store runs in the Disposable profile and does not claim kernel, virtual-machine, or power-loss durability. The same README tells operators to use LayerFS for agent work and history, not as the only copy of data they cannot rebuild. That sentence should determine the architecture: LayerFS owns speculative work; a durable, reviewed system owns accepted work.

The project now has enough signal to test, not enough maturity to assume

LayerFS reached roughly 2,100 GitHub stars and 46 open issues when the project-mode API was checked on October 26. Its October 21 Hacker News discussion drew 76 points and 47 comments. Those are attention signals, not reliability evidence, but they justify a disciplined evaluation. The repository also exposes unusually detailed benchmark receipts, limitations, versioned documentation, and implementation guidance, which makes a falsifiable pilot possible.

The release boundary is moving. Version 1.1.0 split the JavaScript API into @layerfs/agent, @layerfs/backend, and @layerfs/runtime, and the project warns that it breaks code written for 1.0.0. The 2.0 roadmap discusses a Pi integration, external storage, PostgreSQL, native execution, cloud sandboxes, and visualization. Those are plans, not present guarantees. Pinning “LayerFS” without pinning the exact source identity is therefore not a reproducible integration.

The broader developer conversation explains the demand. In one current agent-reliability thread, a highly rated commenter argued that deterministic workflow code should own the process while agents handle bounded non-deterministic steps. Another said state falls apart as multi-step chains grow. LayerFS does not make agent reasoning deterministic, but it can make filesystem state and tool history observable enough to replay, compare, or discard.

Five primitives define the current contract

Content is chunked and stored once, so unchanged bytes can be shared across many states. The Workspace overlay absorbs writes during execution; Commit captures the result; unmount removes the overlay but not committed history. Because ignored files and dependencies are part of the tree, a new agent does not necessarily repeat a package installation. That is a meaningful difference from Git worktrees, which share Git object data but still present independent working directories and do not version ignored dependencies by default.

LayerFS also gives history finer granularity than ordinary source control. A model's edit call can be attributed to one Commit rather than folded into a later human-authored Git commit. That improves blame and rollback for agent behavior. It also produces far more history, so retention, secret scanning, object reclamation, and audit access become product requirements rather than housekeeping.

Put an explicit bridge between machine history and human history

task request + immutable base revision
                  │
                  ▼
        orchestrator forks Branches
          ┌───────┼────────┐
          ▼       ▼        ▼
      agent A  agent B  verifier
      Workspace Workspace read-only view
          │       │        │
     per-call Commits      tests + policy checks
          └───────┬────────┘
                  ▼
          candidate comparison
                  │
         human selects one result
                  ▼
      publication receipt + clean Git tree
                  │
          signed commit / reviewed PR
                  ▼
       durable remote + build provenance

The bridge is more than git diff > patch. It should bind the LayerFS Store identity, base revision, Branch, selected Commit, tool-call history digest, exact runtime versions, diff hash, test commands, test results, secret-scan result, policy verdict, reviewer, Git commit, and remote push receipt. If any identity changes after review, the approval expires.

Keep main read-only to agents unless the orchestration policy explicitly performs a guarded publish. Give the verifier a separate read-only view. A worker should not be able to rewrite its evidence, its tests, and the final decision in the same authority context. This mirrors ordinary CI design: the process that proposes a change should not also own the protected branch and production credential.

External durability belongs outside the live Store. The simplest pattern is frequent export of accepted states to Git plus backup of release receipts and configuration. A later LayerFS roadmap may add cloud storage or another database backend, but future storage support should not be assumed to preserve today's identifiers, transaction semantics, or recovery guarantees.

Choose LayerFS for state density, not because familiar tools disappeared

A team with three agents and a fast monorepo checkout may gain little from another filesystem. A team exploring hundreds of candidates, retaining every intermediate state, or running search-style rollouts has a stronger case. The adoption threshold should be measured in total task latency, storage growth, cleanup cost, conflict rate, review time, and recovered failures, not in snapshot microbenchmarks alone.

Worked example: two agents edit the same release path

Agent A updates an API handler and its unit test. Agent B updates the same handler plus a generated lockfile. Both Branches begin at the same base. LayerFS can refuse the same-file conflict in the handler while a .lww rule lets the newer lockfile win. That is a mechanism, not a policy verdict.

1. The orchestrator records the common base revision and forks A and B.
2. Every edit and Bash call becomes a Commit with the agent, tool, arguments, exit code, and environment identity.
3. A verifier mounts each candidate and runs the same locked test plan.
4. Publishing both candidates detects the handler conflict. The orchestrator does not ask a model to “merge it somehow.”
5. A human reviews the semantic alternatives, selects A's handler, and decides whether B's generated lockfile belongs with it.
6. The selected tree is materialized into a clean Git checkout. Tests and secret scans run again outside the worker authority.
7. A publication receipt binds the selected LayerFS Commit to the Git commit and pull request.

Use last-writer-wins only for artifacts whose semantics genuinely permit replacement, such as a reproducibly generated cache or lockfile under an approved regeneration command. Do not use it for source, migrations, policy, access control, tests, or human-authored documentation merely to reduce conflict handling.

Encode the promotion rule outside the model

workspace_contract:
  layerfs:
    version: "1.1.0"
    source_commit: "PINNED_SHA"
    store_profile: "disposable"
    base_git_revision: "IMMUTABLE_SHA"
  branch:
    owner_task: "TASK_ID"
    ttl_minutes: 90
    secrets: "deny"
    lww_paths:
      - "package-lock.json"
  publish:
    require_clean_materialization: true
    protected_paths:
      - ".github/workflows/**"
      - "infra/**"
      - "migrations/**"
    checks:
      - "npm test"
      - "npm run lint"
      - "npm audit --omit=dev"
      - "secret-scan --diff"
    reviewers: 1
    destination: "git_pull_request"
    sign_commit: true
    invalidate_on_identity_change: true

The model may explain a failure, propose a repair, or generate a review summary. It should not be able to weaken the contract, remove a protected path, change the base revision, or substitute a different test command. Those inputs belong to the orchestrator and repository policy.

Secrets require special treatment because LayerFS includes ignored files and dependencies. Never initialize a Store from a developer directory that contains reusable credentials, cloud profiles, production .env files, signing material, browser state, or SSH agents. Build an allowlisted project image or sanitize the tree before Init. A later deletion does not prove the object vanished from append-only history.

Read the benchmark receipts as experiments, not purchasing claims

The repository reports 1.0.0 results including 5.20 seconds versus 8.88 seconds on a twelve-scenario filesystem benchmark, 100.1 MB versus 1,994.6 MB for 157 snapshots of a compressible project, zero unexpected failures across 8,798 POSIX assertions, and 3.06 million random filesystem operations without a byte miscompare. It also reports weak cases: sequential write, sequential read, and random write trailed the comparison FUSE passthrough in one fio suite.

The documentation is unusually careful about context. The measurements used one sample per case, a fixed seed, an arm64 Mac host, Docker Desktop Linux/arm64, eight CPUs, and recorded host load. The published numbers are release measurements, not a guarantee. The storage ratio depends heavily on repeated and compressible content. A repository dominated by already compressed assets, database files, or large rewrites will behave differently.

Reproduce the exact upstream suite before changing it, then add your workload. Measure cold Init, warm fork, dependency-heavy mount, small edits, large generated files, concurrent writers, conflict handling, Commit latency, Store growth, cleanup, verifier mount, materialization, Git export, and end-to-end accepted-task latency. Report medians and tail latency across repeated runs, not a single best sample.

Failure modes that checkpoints can make look safer than they are

Pilot on rebuildable work and force the boundaries to fail

1. Choose a repository that can be rebuilt from Git and package registries. Exclude regulated data and production secrets.
2. Pin LayerFS, the DSH plugin if used, runtime packages, container image, source commit, Store schema, and base Git revision.
3. Initialize from a sanitized tree and prove excluded secrets cannot be retrieved from any Commit.
4. Reproduce upstream filesystem and benchmark suites without modifying their workloads or verdicts.
5. Run your own agent tasks at one, two, four, and eight concurrent workers. Measure Store contention and accepted-task latency.
6. Force same-file conflicts, generated-file conflicts, long-running Bash, process death, daemon death, VM termination, full disk, and corrupted export.
7. Confirm which failures preserve state and which require rebuilding from Git. Do not call VM recovery “supported” if it was not proved.
8. Materialize the chosen candidate into a clean checkout and rerun tests, policy checks, and secret scans outside the worker context.
9. Create a signed publication receipt and prove the Git commit and remote branch match the reviewed candidate exactly.
10. Set retention and deletion rules for losing Branches, tool history, dependencies, and generated artifacts.
11. Run restore and rollback drills before allowing production repositories.

FAQ

Does LayerFS replace Git or GitHub?

No. Its strength is high-frequency machine workspace history. Git remains the mature publication, remote collaboration, review, signing, and ecosystem boundary. The safest architecture uses both.

Is the current Store durable?

The released README says the active Store uses the Disposable profile. It may survive a process crash, but it does not claim kernel, VM, or power-loss durability. Treat accepted work as unsafe until exported to tested durable custody.

Is every tool call really a commit?

The intended integration maps file calls to Store operations and completed Bash calls to mounted Workspace commits. Verify the exact harness plugin and version because orchestration behavior is part of the integration, not a universal filesystem law.

When should a team keep using Git worktrees?

Keep them when you have a small number of long-lived checkouts, setup is cheap, ignored dependencies are not a bottleneck, and existing Git-native controls already meet the task. Added infrastructure must beat that baseline end to end.

Can .lww solve merge conflicts?

It can define newest-wins behavior for approved paths. It cannot decide whether one source change is semantically compatible with another. Use it for reproducible artifacts, not as a blanket conflict suppressor.

Sources and further reading

Sources were checked online on October 26, 2026. GitHub stars, open issues, and discussion scores are point-in-time attention signals. LayerFS benchmark numbers are first-party release measurements and are not independent guarantees.

• Ephemeral AI Lab: LayerFS repository - current status, architecture, limitations, benchmarks, source, activity, and MIT license.
• LayerFS release records - versioned source releases and compatibility notes.
• LayerFS documentation - setup, JavaScript packages, environment, runtime, and pinned integration instructions.
• LayerFS comparison documentation - positioning against copies, Git worktrees, and filesystem approaches.
• LayerFS AGENTS.md - current implementation authority, workstreams, and contributor constraints.
• LayerFS 2.0 roadmap discussion - proposed harness, storage, sandbox, and visualization work; not a released contract.
• Hacker News: LayerFS, a filesystem for AI coding agents - developer discussion from October 21, 2026.
• SQLite: Write-Ahead Logging - WAL behavior, concurrency, checkpointing, and durability background.
• Git documentation: git-worktree - worktree semantics used in the comparison.
• Linux kernel documentation: OverlayFS - layered filesystem mechanics and constraints.
• Related: Pi agent-harness durability contract.
• Related: coding-agent patch-size contract.
• Related: coding-agent sandbox escape boundaries.