A copy-on-write overlay over your working directory, backed by a dedicated bare
git store. Agents edit inside the overlay; nothing touches your real files until
you accept it — and even then, only the files they actually changed.
Plain ESM .mjs, Node ≥20. No build step. Zero runtime npm dependencies —
every object/ref/tree/merge op shells out to the system git binary.
Why
Letting an agent loose on a repo usually means trusting it not to scribble
everywhere. git-fs removes the trust: edits land in a per-session git branch, you
see exactly what changed, and you merge it in — or throw it away — on your terms.
- 🛡️ Sandbox agents. Edits live in an overlay branch. Your real files only
change on
stop, and only the touched ones. Don't like it? Delete the branch.
- 🌿 Run agents in parallel. Each session is its own branch in one shared
store. Fan out N agents on one checkout, then
merge the winners — clean
merges auto-commit, conflicts come back as a file list.
- 🧪 Speculate freely. "Try this refactor, show me the diff, toss it" —
without touching disk or polluting your project's git history.
- 📂 Edit anywhere. Reads fall back to live disk for any path your main git
tracks. Ignored/untracked files (secrets, deps, build junk) are kept out of the
store unless you opt them in with a
.gitfsallow file at the repo root.
- 🧾 Audit everything. Every edit is a commit tagged with its
Session-Id.
Per-session, per-file history of exactly what an agent did, in order.
How it works
agent writes ───▶ overlay branch gitfs/<session-id>
(starts EMPTY — touched files only)
│
agent reads ──▶ tracked? ──▶ YES ──▶ branch blob (read-your-writes)
│
└──────▶ NO ──▶ live disk bytes (fallback)
│
on stop ─────────────────────────────▼─────────────────────
materialize touched files ──▶ working dir
(your project's .git is NEVER written)
- The store is a bare repo at
.git-fs/ (gitignored, publishable as a subrepo).
Your project's own .git is never written.
- Each session works on
gitfs/<session-id>, which starts empty.
- A file enters the branch only when an agent writes/edits it (touched-only deltas).
- Reads fall back to the working tree — touched paths read the branch blob
(read-your-writes), untouched paths read current disk bytes. Disk fallback is
gated to paths your main git already tracks; ignored/untracked content
(secrets, build junk, deps) stays out unless re-permitted via
.gitfsallow.
- Stop materializes only touched files back to disk.
Three-way merges run in memory via git merge-tree --write-tree — no worktree,
no checkout. git-fs never hard-fails a session: no git on PATH ⇒ silent no-op.
Layout
| File | Role |
|---|
bin/git-fs.mjs | single entry; argv[2] selects mcp | hook <action> | <cli> |
src/store.mjs | git wrapper + overlay primitives (the core; readFile is the choke point) |
src/mcp.mjs | hand-rolled stdio JSON-RPC MCP server |
src/hooks.mjs | session-start / post-edit / read / stop |
test/store.test.mjs | node --test |
Usage
node bin/git-fs.mjs mcp # run the MCP server (stdio)
node bin/git-fs.mjs hook <action> # session-start | post-edit | read | stop (JSON on stdin)
node bin/git-fs.mjs ls|read|log|init # tiny CLI over the store
npm test # node --test
Env: GIT_FS_REPO (store dir, default .git-fs), GIT_FS_DISK (worktree,
default cwd), GIT_FS_BRANCH (override the branch). With no override, the MCP
server and CLI default to the branch session-start pinned for the active
session (.git-fs/CURRENT), falling back to main only outside a session.
As a Claude Code plugin, .claude-plugin/plugin.json wires the MCP server and the
four lifecycle hooks. For a standalone MCP config, see mcp.config.example.json.
Good to know
