AI coding agents are excellent at writing code and terrible at committing it. Ask an agent to commit two changes separately and it cannot do what a human does instinctively: open an interactive prompt, pick some hunks, and leave the rest. Git's interactive tools assume a person is sitting at the keyboard, and agents are not. Git-surgeon fixes that mismatch. It is an open source CLI that gives AI agents surgical control over git changes without interactive prompts, and as of October 26, 2026, the repo raine/git-surgeon has 186 stars and 7 forks on GitHub under the MIT license.
Key Takeaways
>
Git-surgeon replaces interactive git prompts with non-interactive commands an AI agent can run safely: list hunks, stage them, commit them, or discard them by ID.
Every hunk gets a stable 7-character ID derived from its file path and content, so an agent can refer to a change precisely instead of guessing at file names.
It can split a commit that mixes concerns, fold a fix into an earlier commit, reword or reorder commits, and commit to another branch without checking it out.
Installation takes one command via a shell script, Cargo, or Homebrew, plus an agent skill for Claude Code, OpenCode, or Codex.
The honest limit: history rewriting still uses rebase under the hood, so conflicts still need a human, and
discardpermanently deletes uncommitted changes.It is a small, focused tool, not a git replacement, and that focus is exactly why it works for agents.
The problem: agents cannot use git add -p
The core problem is simple, and the git-surgeon README states it plainly. AI agents cannot use interactive git commands like git add -p (git-surgeon README). When asked to commit changes separately, an agent has no good move. It can commit everything together, producing a messy commit that mixes unrelated changes, or it can try destructive workarounds, like resetting and checking out files, which risk destroying work. The README shows exactly that failure: an agent about to run git checkout on a file to separate two changes, a command that would have thrown away the very changes it was trying to organize.
This is not an edge case. Agents routinely touch many files in one session: a feature here, a logging tweak there, a formatting fix somewhere else. A human reviews the diff, picks hunks, and writes focused commits. An agent that can only commit whole files ends up with commits titled "various changes" or, worse, a history that nobody can review. Clean history is not cosmetic. It is how reviewers understand what changed, how bisect finds regressions, and how reverts stay safe. When agents write most of the code, the commit step becomes the bottleneck for reviewability.
Watch the 30-second repo signal: Fix messy AI commits with git surgeon.
What git-surgeon actually is
Git-surgeon is a Rust CLI built around one idea: give every hunk a stable ID, then let agents operate on those IDs. A hunk is a contiguous block of changed lines in a diff. Run git-surgeon hunks and you get a list like ac34353 internal/bot/listing_handler.go (+6 -3), one line per hunk, with the file, the function context, and the added and removed line counts. From there, the agent can inspect, stage, commit, or discard exactly that hunk.
The IDs are the clever part. Each ID is a 7-character hex string derived from a SHA-1 hash of the file path and the hunk content, meaning the actual added, removed, and context lines, not the diff header. That makes IDs stable when lines shift above a hunk, and deterministic, so the same content always produces the same ID. If two identical hunks collide, later ones get a -2 or -3 suffix. An agent can therefore say "commit ac34353 and 15baf94" and mean something precise, instead of describing a change in prose and hoping the tool interprets it right.
The tool ships as a single binary, installable three ways: a shell install script, cargo install git-surgeon, or Homebrew via brew install raine/git-surgeon/git-surgeon. It also installs an agent skill for Claude Code, OpenCode, or Codex, so the agent learns the commands and reaches for them on its own. Requirements are modest: Git 2.0 or newer, plus Rust only if you build from source.
The commands, in plain language
Git-surgeon has a focused command set, and its commands fall into four groups that mirror a normal git workflow.
Group | Commands | What the agent can do |
|---|---|---|
Inspect | hunks, show | List hunks with IDs, or show the full diff for one hunk with line numbers |
Stage and commit | stage, commit, commit-to, unstage, discard | Stage hunks by ID, commit them in one step, commit to another branch without checking it out, unstage, or discard |
Rewrite history | fold, amend, squash, reword, split, move, undo | Fold commits into earlier ones, squash a range, change a message, split a mixed commit, reorder commits, or reverse-apply hunks |
Maintain | update | Update to the latest release, with a SHA-256 checksum check |
The inspect commands are the foundation. hunks lists unstaged hunks by default, with flags for staged hunks, a single file, or hunks from a specific commit, plus a --blame mode that shows which commit introduced each line and a --full mode for the complete diff. show prints one hunk with 1-based line numbers, which matters because the next step often needs line ranges: stage a1b2c3d --lines 5-30 stages only part of a hunk, for the case where git groups two unrelated changes into a single hunk.
The commit commands are where the tool earns its name. commit stages the named hunks and commits them in one step, and if the commit fails, it unstages them to restore the original state. It refuses to run if the index already has staged changes, which prevents half-staged confusion. commit-to goes further: it commits hunks directly to another branch without checking it out, using git plumbing, which is useful in worktree setups where the target branch is checked out elsewhere. If the patch cannot apply cleanly, it fails without modifying anything.
The history commands handle the cleanup agents usually skip. split breaks a commit that mixes concerns into focused commits, even retroactively, using --pick groups of hunk IDs with messages and an optional --rest-message for the leftovers. fold merges existing commits into an earlier commit, while amend folds staged changes into an earlier commit. squash combines a range into one commit, reword changes a message without touching content, move reorders a commit, and undo reverse-applies selected hunks from a previous commit back into the working tree.
A typical agent workflow
The README's typical workflow is short enough to quote in spirit: the agent makes changes across files, runs git-surgeon hunks to review, commits the hunks for feature A with one command, then commits the rest for feature B. That is the whole loop, and it replaces a paragraph of agent reasoning with three commands.
A more realistic example from the README shows why line ranges matter. A file has two changes grouped into one hunk: pagination for one function and soft-delete filtering for another. The agent runs show to see line numbers, stages only lines 1-11 for pagination, commits that, then commits the rest separately. Without line-level control, those two changes would have stayed in one commit forever, because no whole-hunk operation could separate them.
The retroactive case is just as useful. An agent commits two unrelated changes together, the human asks for them separately after the fact, and split HEAD with --pick groups and a --rest-message produces two clean commits. This is the workflow that makes agent-generated history reviewable after the fact, not just at commit time, and it is the one most likely to save a real code review.
Git-surgeon versus plain git
It helps to be clear about what git-surgeon is not. It is not a git replacement, a hosting service, or a new version control system. Every operation goes through git itself, and history rewriting uses rebase internally. The table below keeps the comparison honest.
Aspect | Plain git for agents | Git-surgeon |
|---|---|---|
Interactive staging |
| Non-interactive hunk IDs the agent can pass as arguments |
Partial commits | Whole files, or risky reset and checkout workarounds | Hunks, or line ranges inside a hunk |
Splitting a mixed commit | Manual interactive rebase |
|
Folding a fix into an older commit | Manual rebase or amend with care |
|
Committing to another branch | Checkout, commit, switch back |
|
Safety guardrails | Few, by default | Refuses on a dirty index, restores state on failed commits |
What it cannot do | N/A | Resolve rebase conflicts for you, or undo a |
The guardrails deserve emphasis. A tool that lets an agent rewrite history needs to fail safely, and git-surgeon does: it refuses when the index has staged changes, it autostashes dirty trees around rebases and restores them, and it fails without modifying anything when a patch cannot apply to another branch. Those are the behaviors that make it safe to hand to an autonomous agent, and they are easy to overlook in a feature list.
The honest caveats
Three limits are worth knowing before you hand this to an agent.
First, rebase conflicts still need a human. When fold, split, move, or amend hits a conflict, the repo is left in a conflict state for manual resolution with git rebase --continue or git rebase --abort. Git-surgeon makes history surgery scriptable, not conflict-free, and an agent that rewrites shared history can still create a mess that only a person can untangle. Do not let agents rewrite commits that others have already pulled.
Second, discard is permanent. It reverse-applies hunks to the working tree, which is the non-interactive equivalent of git checkout -p, and the README warns that it permanently removes those uncommitted changes. That is the correct behavior for a discard command, but it means an agent with discard access can delete work. Scope the agent's permissions, or at least review its discard calls, the way you would review any destructive command.
Third, the project is young and small. It was created in January 2026, has 99 commits and 18 releases, and 186 stars is modest next to the tens of thousands behind established git tools. That is normal for a niche agent tool, and the MIT license plus a small Rust codebase make it easy to audit, but it also means the community is small and the tool's long-term maintenance depends on one author and a handful of contributors. Try it on a scratch repo first, and keep your normal git skills sharp, because git-surgeon is a layer on top of git, not a substitute for understanding it.
Why this repo matters
Git-surgeon matters because it treats a real and growing problem as a tooling problem, not a prompting problem. Telling an agent "make clean commits" in a system prompt does not work when the agent literally lacks a non-interactive way to stage half a file. Giving it hunk IDs, line ranges, and one-step commit commands does work, because it turns a vague instruction into concrete operations with predictable results.
It also fits a wider shift. As agents write more code, the bottleneck moves from writing to reviewing, and reviewable history becomes infrastructure, not hygiene. Tools that make agent output reviewable, whether that is hunk-level commits here or worktree isolation elsewhere, are the ones that let teams actually merge agent work at scale. If you are already running coding agents and your commit history reads like a rough draft, git-surgeon is a small install with an immediate payoff: run hunks, pick the IDs, and let the agent commit like a careful human would.
The repo is worth reading in full, especially the examples section: raine/git-surgeon.
Read this article in Indonesian: Git-Surgeon: Beri Agen Coding AI Kendali Penuh Atas Riwayat Git.
If you are new to version control itself, our Git Explained post covers how commits, branches, and history work before you hand them to an agent.
FAQ
What is git-surgeon?
It is an open source Rust CLI at github.com/raine/git-surgeon that gives AI coding agents non-interactive control over git changes: list, stage, commit, split, fold, and discard hunks by stable IDs, without interactive prompts.
Why can agents not just use git add -p?
Because git add -p is interactive: it asks questions at a prompt and waits for a human to answer. Agents cannot answer those prompts, so they either commit everything together or resort to destructive workarounds like resetting and checking out files.
How do hunk IDs work?
Each ID is a 7-character hex string derived from a SHA-1 hash of the file path and the hunk content, excluding the diff header. IDs stay stable when lines shift above a hunk, the same content always gives the same ID, and collisions get a -2 or -3 suffix.
How do I install git-surgeon?
Use the shell install script from the README, cargo install git-surgeon, or Homebrew with brew install raine/git-surgeon/git-surgeon. Then install the agent skill with git-surgeon install-skill --claude, --opencode, or --codex.
Can git-surgeon split a commit that already exists?
Yes. git-surgeon split breaks an existing commit into multiple commits using --pick groups of hunk IDs with messages, and works on HEAD directly or on earlier commits via rebase.
Is git-surgeon safe to give to an autonomous agent?
Mostly, with two cautions. It refuses on a dirty index, restores state on failed commits, and fails cleanly when a patch cannot apply. But discard permanently deletes uncommitted changes, and rebase conflicts still need a human to resolve, so do not let agents rewrite shared history.