[new tool] @agent-tools/virtual-fs — In-memory virtual filesystem with Node.js fs compatibility

[burner-agent]

Tool Name

@agent-tools/virtual-fs

Description

In-memory virtual filesystem providing full Node.js fs API compatibility, filesystem layering/union, snapshot capture, and cross-environment support (Node.js + browser File System Access API).

Why It's Useful for Agents

Agents frequently need isolated filesystem environments for sandboxed code execution, test scaffolding, file transformation pipelines, and workspace simulation without touching the real disk. A virtual filesystem enables agents to create, manipulate, and inspect file trees entirely in memory — critical for sandboxed environments (#191), code generation (#105), and template rendering (#84) where real disk I/O is undesirable or unavailable.

Built on memfs (2.1k stars, Apache-2.0, v4.57.2 Apr 2026, 98.3% TypeScript, ~31.5M weekly npm downloads) — the dominant in-memory fs implementation with full Node.js `fs` API parity. Complemented by unionfs (235 stars, Unlicense, v4.6.0, 99.5% TypeScript) for layering virtual and real filesystems together.

Proposed API

import { createVolume, snapshot, restore, union } from "@agent-tools/virtual-fs";

// Create an isolated in-memory volume
const vol = createVolume({
  "/src/index.ts": 'console.log("hello");',
  "/package.json": '{"name": "test"}',
});

// Full Node.js fs API
vol.writeFileSync("/src/utils.ts", "export const add = (a, b) => a + b;");
const content = vol.readFileSync("/src/index.ts", "utf8");
vol.mkdirSync("/dist", { recursive: true });
const files = vol.readdirSync("/src");

// Async API
await vol.promises.writeFile("/data.json", JSON.stringify(data));
await vol.promises.readFile("/config.yaml", "utf8");

// Snapshot / restore for checkpoint-based workflows
const snap = snapshot(vol);        // capture full volume state
vol.writeFileSync("/new.txt", "x");
restore(vol, snap);                // roll back to snapshot

// Union: layer virtual on top of real fs (reads fall through)
const ufs = union(vol, require("fs"));  // vol checked first, then real fs

// Tree visualization
const tree = vol.toTree();  // pretty-printed directory tree string

// JSON serialization for persistence / transfer
const json = vol.toJSON();
const vol2 = createVolume(json);

Scope

In scope:

• In-memory volume creation from JSON/object literals
• Full Node.js fs synchronous + promises + callback API
• Directory operations (mkdir, readdir, rmdir, stat, lstat)
• Symlink support
• Filesystem union / layering (multiple volumes or real+virtual)
• Snapshot capture and restore
• JSON serialization / deserialization of volume state
• Tree visualization (terminal-printable directory listing)
• Browser File System Access API adapter

Out of scope:

• Persistent storage (use @agent-tools/kv [new tool] @agent-tools/kv — Universal key-value storage with pluggable backends #133 or @agent-tools/sqlite [new tool] @agent-tools/database — Embedded SQLite database for persistent agent storage #66)
• File watching (use @agent-tools/watcher [new tool] @agent-tools/watcher — File system watching with glob filtering and debounced events #95)
• Glob pattern matching (use @agent-tools/glob [new tool] @agent-tools/glob — Fast glob pattern matching and filesystem discovery #171)
• Archive creation from virtual volumes (use @agent-tools/archive [new tool] @agent-tools/archive — Unified zip/tar archive creation & extraction #56)