Why use git-fs
Run 5+ AI agents on the same repo at once without them stomping each other.
Plain filesystem + multiple agents = stale reads, overwritten edits, lost work on crash. git-fs gives every agent its own git branch in a shared object store. Edits are commits. Sessions end with a 3-way merge into main, then materialize to disk. No locks, no coordination server, no clone-per-agent.
┌─ agent A ──┐
│ edit foo.ts│──┐
└────────────┘ │
┌─ agent B ──┐ ├──► merge.lock ──► 3-way merge ──► main ──► disk
│ edit bar.ts│──┤
└────────────┘ │
┌─ agent C ──┐ │
│ rm baz.ts │──┘
└────────────┘
What you get
| Plain FS + N agents | git-fs |
|---|
| Session startup cost | clone / worktree add (seconds–minutes) | git branch (~ms, 0 file copies) |
| Disk per extra agent | full working tree (~repo size × N) | 0 bytes — shared object store |
| Write atomicity | partial writes possible on crash | every edit = 1 git commit, atomic |
| Concurrent edits to repo | last-writer-wins, silent loss | isolated branches, explicit 3-way merge |
| Crash recovery | unsaved buffers gone | git reflog — every tool call is recoverable |
| Audit trail | filesystem mtime, no author | git log — who, what, when, which session |
| Cross-agent visibility | none | siblings read each other's .git-fs/session/ live |
| Merge race protection | none | proper-lockfile on merge.lock — serialized Stop hooks |
| Tooling for LLMs | shell out to git | first-class MCP: git_fs_read/write/replace/merge/... |
| Install footprint | — | pure JS bundle, no native binary, no platform matrix |
What it can do
- 🌿 N agents, 1 repo, 0 collisions — each session lives on
agent/<uuid>.
- ⚡ Edit-as-commit —
git_fs_replace / write / rm each produce one commit. Roll back with git reset.
- 🔀 Auto-merge on Stop — exclusive
merge.lock + 3-way line merge into main + checkout to disk.
- 🧹 Mergeignore — junk files (
.agent, CONFLICTS.md, your own globs) never reach main.
- 🪟 Worktree-aware — per-worktree by default, or share one bare repo across worktrees via
GIT_FS_REPO.
- 📜 Full audit —
git log agent/<id> answers "what did this agent do?"
- 🔌 MCP-native — works with any MCP client; ships as a Claude Code plugin.
Install (Claude Code plugin)
/plugin marketplace add yesitsfebreeze/git-fs
/plugin install git-fs@git-fs
That's it. On the next session start the plugin:
- Spawns bundled JS (
dist/cli.js and dist/mcp.js) via the Node already running Claude Code. No binary download, no architecture matrix, no PATH changes.
- Auto-initializes any git repo it lands in — creates
.git-fs/ and writes Edit/Write deny rules into the project's .claude/settings.json so all edits go through git-fs MCP tools.
- Registers the
git-fs MCP server and the SessionStart / Stop / PreToolUse(Read) / PostToolUse(Write|Edit) hooks.
- Exposes the
git-fs skill so Claude knows the tool-selection rules.
Verify: session banner shows Branch: agent/<uuid>, and git_fs_branch_list returns the active branches.
Runtime requirement: Node 20+. Claude Code already ships with a compatible runtime, so the plugin works on any OS Claude Code supports.
Other MCP-capable agents (Cursor, Windsurf, Cline, …)
Install from npm (when published) or clone + build:
git clone https://github.com/yesitsfebreeze/git-fs
cd git-fs/git-fs
npm install
npm run build
Then point your agent at the MCP entry:
// .mcp.json (or your agent's equivalent)
{
"mcpServers": {
"git-fs": {
"command": "node",
"args": ["/abs/path/to/git-fs/dist/mcp.js"]
}
}
}
Inside the target repo run node /abs/path/to/git-fs/dist/cli.js init-project to create .git-fs/. Non-Claude agents do not get the auto-merge Stop hook — use git_fs_merge manually at end of session.
Update
/plugin update git-fs@git-fs
Build from source
cd git-fs
npm install
npm run typecheck
npm test
npm run build # emits ./dist and ../dist (consumed by the plugin)
How it works
