Copy-on-Write Overlay Filesystem

• Entity ID: ent-20260419-380e0c5a68b2
• Type: concept
• Scope: shared
• Status: active
• Aliases: COW overlay, speculation overlay, overlay filesystem

Description

Per-process overlay directory at ~/.claude/tmp/speculation/// used by the speculation engine to redirect all writes during speculative execution while leaving the real filesystem untouched. Read operations check the overlay first and fall through to the main filesystem on miss; writes trigger copyFile(cwd/rel -> overlayPath/rel) the first time a file is touched in a run. On accept (Tab), overlay files are merged back to main FS; on reject, the overlay directory is deleted.

Key claims

• Speculation overlay path is per-pid and per-uuid

Relations

• Speculation Engine --[uses]--> Copy-on-Write Overlay Filesystem

Sources

src-20260419-16b155f4f619