AgentFS

AgentFS is Agent Harbor’s cross-platform filesystem layer that provides copy-on-write snapshots and per-process isolation. It enables instant workspace branching, time-travel debugging, and parallel agent execution without filesystem conflicts.

Why AgentFS?

Linux provides native copy-on-write filesystems (ZFS, Btrfs) and mount namespaces for process isolation. macOS and Windows lack these capabilities. AgentFS provides a consistent experience across all platforms.

Key Capabilities

Copy-on-Write Snapshots

Create instant point-in-time snapshots of the entire filesystem state:

• No data duplication — snapshots share unchanged blocks
• Memory-efficient storage with transparent disk spillover
• Writable branches from any snapshot

Branch Directory Model

Each agent session gets its own filesystem branch:

/branches/
  ├── task-claude-1/    # First Claude agent's workspace
  ├── task-claude-2/    # Second Claude agent's workspace
  └── task-codex-1/     # Codex agent's workspace

• Path-based resolution (no kernel PID lookup)
• Different processes see different filesystem views
• No VFS cache pollution between branches

Overlay Mode

AgentFS operates as an overlay over your existing workspace:

• Pass-through reads — Unmodified files served directly from host filesystem
• Copy-up on write — Only modified files stored in the branch
• Whiteouts for deletes — Deletions mask files without altering the host
• Metadata overlay — Permission changes captured without copying file content

Materialization Modes

AgentFS supports three strategies trading off between performance and isolation:

Lazy Mode

Classic overlay behavior: reads pass through to host, writes trigger copy-up. Fast and efficient, but host filesystem changes after branch creation may be visible to agents that haven’t accessed those files yet.

Eager Mode

Copies all files at branch creation. Provides true point-in-time snapshot semantics — agents see exactly what existed when the branch was created, immune to subsequent host changes.

CloneEager Mode

Uses filesystem-native block cloning (APFS clonefile(), Btrfs/XFS reflink, ReFS block cloning) to create branches. Same isolation as Eager with minimal storage overhead.

Platform Implementations

Linux (FUSE)

Native FUSE filesystem with optional passthrough mode for maximum performance:

# Passthrough mode on Linux 6.9+
AGENTFS_FUSE_PASSTHROUGH=1 ah agent start --agent claude --fs-snapshots agentfs

macOS (FSKit)

FSKit-based filesystem extension with per-task overlay. Agents are chrooted into their branch to maintain original project paths.

Windows (WinFsp)

WinFsp filesystem providing the same CoW overlay. Per-process drive letter mapping creates a chroot-like environment.

Path Policies

AgentFS supports configurable policies for different path categories:

Usage

With ah agent start

# Auto-detect best provider (prefers native ZFS/Btrfs, falls back to AgentFS)
ah agent start --agent claude --fs-snapshots auto --prompt "Add tests"
 
# Force AgentFS
ah agent start --agent claude --fs-snapshots agentfs --prompt "Add tests"

Working Copy Modes

# Copy-on-write overlay (default with AgentFS)
ah agent start --agent claude --working-copy cow-overlay --prompt "Task"
 
# Git worktree isolation
ah agent start --agent claude --working-copy worktree --prompt "Task"
 
# In-place (no isolation)
ah agent start --agent claude --working-copy in-place --prompt "Task"

Performance

AgentFS provides several I/O optimization modes:

Kernel-Backstore Proxy (KBP)

Default mode where the adapter services I/O using hidden host filesystem handles. Provides good memory efficiency and works everywhere.

FUSE Passthrough

On Linux 6.9+, the kernel forwards read/write directly to backing files, completely bypassing the FUSE daemon for data I/O. Requires CAP_SYS_ADMIN.

Interpose Mode

For selected processes, AgentFS injects a syscall shim that receives real OS file descriptors from the daemon. Data I/O bypasses the adapter entirely while path operations still route through AgentFS.

Comparison with Alternatives