Help us improve
Share bugs, ideas, or general feedback.
From git-fs
Virtual filesystem over a bare git object store. Each Claude Code session works on its own agent/<session-id> branch; every edit is a commit; Stop hook merges to main and materializes to disk. Use when the project has a .git-fs/ directory and the git-fs MCP is registered. Triggers on file edits in such a project, on questions about session branches, sibling agents, mergeignore, or git-fs tool selection.
npx claudepluginhub yesitsfebreeze/git-fs --plugin git-fsHow this skill is triggered — by the user, by Claude, or both
Slash command
/git-fs:git-fsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Virtual filesystem over a bare git repository. Disk is read-only during a session. All file changes go through git-fs MCP tools and become git commits on a session-scoped branch. The Stop hook merges that branch into `main` and materializes the result to disk.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Creates, reads, edits, and analyzes .docx files using docx-js for new documents, pandoc for text extraction, Python scripts for XML unpacking/validation/changes, and LibreOffice for conversions.
Share bugs, ideas, or general feedback.
Virtual filesystem over a bare git repository. Disk is read-only during a session. All file changes go through git-fs MCP tools and become git commits on a session-scoped branch. The Stop hook merges that branch into main and materializes the result to disk.
This skill is for projects that use git-fs as their file backend. Signs:
.git-fs/ directory exists at project root..mcp.json or a Claude Code plugin registers a git-fs MCP server.Branch: agent/<session-id>.If those signs are absent and the user wants this behavior, install the plugin:
/plugin marketplace add yesitsfebreeze/git-fs
/plugin install git-fs@git-fs
The plugin's SessionStart hook auto-initializes any git repo it lands in.
Never use the native Edit or Write tools. They are denied in .claude/settings.json on git-fs projects by design (the plugin writes the deny rule on auto-init). All edits flow through the MCP tools below. Read is allowed because the PreToolUse hook materializes git-fs content to disk first.
| Need | Tool | Notes |
|---|---|---|
| Read full file | git_fs_read ref:<branch> path:<file> | |
| Read line slice | git_fs_read ref:<branch> path:<file> start_line:N end_line:M | 1-indexed inclusive |
| Edit existing (preferred) | git_fs_replace branch:<branch> path:<file> old_str:"..." new_str:"..." | Text-match, drift-immune; include enough context to make old_str unique |
| Edit by line range | git_fs_patch branch:<branch> path:<file> start_line:N end_line:M content:"..." | Use when old_str cannot be made unique |
| Create file | git_fs_write branch:<branch> path:<file> content:"..." | Overwrites if exists |
| Delete file | git_fs_rm branch:<branch> path:<file> | |
| List files | git_fs_ls ref:<ref> path:<prefix> recursive:true | |
| Diff two refs | git_fs_diff ref_a:<a> ref_b:<b> | |
| Branch history | git_fs_log branch:<branch> | |
| Materialize to disk | git_fs_checkout ref:<ref> dest:<dir> | Usually automatic on Stop |
| 3-way merge | git_fs_merge ours:<a> theirs:<b> base:<c> into:<branch> | Usually automatic on Stop |
| List sibling sessions | git_fs_branch_list | |
| Create branch | git_fs_branch_create name:<name> from:<ref> | |
| Delete branch | git_fs_branch_delete name:<name> |
The agent branch for the current session is injected at session start in the banner as Branch: agent/<uuid>. Use it as the branch argument for write/edit/rm.
git_fs_read first.git_fs_replace (text-match). Falls back to git_fs_patch only when the target text isn't unique.git_fs_write.Multiple Claude Code sessions can run against the same git-fs repo in parallel.
agent/<session-id> branch — full isolation.git_fs_branch_list.git_fs_read ref:agent/<other-id> path:.git-fs/session/intent.md.main. Hard defaults: .agent, CONFLICTS.md. Project-configurable extras: .git-fs/mergeignore.Sibling agents commit to their own agent/<id> branch, not to main. The Stop hook merges at session end, not mid-session. So main does not reflect work that sibling agents have already shipped.
git_fs_branch_list — enumerate active agent/* branches.git_fs_log branch:agent/<sibling> + git_fs_diff ref_a:main ref_b:agent/<sibling>git_fs_read ref:agent/<sibling> path:<file> to see their current version.main.When you need a sibling's work visible mid-session (not at Stop), merge their branch into yours explicitly with git_fs_merge or via the /merge skill. Don't assume main is the integration point during a live session.
Spec: https://github.com/yesitsfebreeze/git-fs/blob/main/docs/multi-agent-session.md.
The Stop hook does, in order:
<.git-fs>/merge.lock (serializes concurrent Stop hooks).agent/<id> into main using the base OID stored at session start.main to disk.CONFLICTS.md on the agent branch; do not merge.If you see CONFLICTS.md referenced in a sibling, that session ended in a merge conflict — pick it up or rebase.
git-fs works across git worktrees in two modes.
.git-fs/. Sessions are isolated per worktree — git_fs_branch_list only shows agents in this worktree.GIT_FS_REPO env var to one absolute path. All worktrees see the same branch graph; git_fs_branch_list returns every active agent across every worktree. The merge lock is global. Stop still materializes main into each session's own cwd, so disk contents stay per-worktree even though history is shared.