Claude Code checkpoints vs Git commits for team workflows

<article> <p>You ask Claude Code to clean up a tangled module. It touches five files, runs a formatter, tries a test command, changes direction twice, and then you realize the first assumption was wrong. At that moment, the question is practical: do you reach for <code>/rewind</code>, or do you go back to Git?</p>

<p>The useful answer to <strong>Claude Code checkpoints vs Git commits</strong> is simple: checkpoints are local session undo. Git commits are team history. Use checkpoints to recover from a bad path inside one Claude Code session. Use Git for anything that must be durable, reviewable, shareable, protected by CI, or audited later.</p>

<p>That distinction sounds obvious until an agent starts editing real code. Claude Code checkpoints reduce the fear of local exploration, but they do not replace the discipline of clean commits, branch policy, and pull request review.</p>

<p><strong>Internal link anchor point:</strong> <a href="/guides/production-workflows-for-ai-coding-agents">production workflows for AI coding agents</a></p>

<h2>What Claude Code checkpoints actually do</h2>

<p>According to Anthropic's Claude Code checkpointing documentation, checkpointing captures code state automatically before each user prompt. When you open <code>/rewind</code>, or use the double <code>Esc</code> shortcut, Claude Code shows a menu of previous prompts in the session.</p>

<p>From there, you can restore code and conversation, restore only the conversation, restore only the code, or ask Claude to summarize the conversation from or up to that point. Code restore options appear only when the selected checkpoint has tracked file changes to revert.</p>

<p>This is stronger than a plain Git checkout in one important way: Git can reset files, but it cannot reset what the model has internalized in the conversation. If Claude spent twenty minutes building on a bad premise, restoring only the files may leave the assistant still thinking in the wrong frame. <code>/rewind</code> can take the conversation back too.</p>

<p>That is the best use case: you want to abandon a local line of agent reasoning, not merely undo a diff.</p>

<h2>What checkpoints do not cover</h2>

<p>The failure mode is assuming "checkpoint" means "everything that happened." It does not.</p>

<p>Claude Code's official docs frame checkpoints around direct file edits made through Claude's file editing tools. They specifically say files modified by bash commands such as <code>rm</code>, <code>mv</code>, and <code>cp</code> are not tracked by checkpointing. In practice, that gap matters because coding agents rarely stay inside one edit tool.</p>

<p>A normal agent run may execute tests, install packages, run codemods, generate files, apply migrations, call scripts, or use Git. A rewind can restore tracked source edits while leaving shell side effects behind. That can mean package lock churn, generated artifacts, local database state, service state, or Git history still sitting in your workspace after the code has been rolled back.</p>

<p>Checkpoints also have session boundaries. The docs say they normally do not capture manual edits outside Claude Code or changes from other concurrent sessions unless those sessions modify the same files as the current session. Subagent behavior has its own trap: except for foreground forked skills, official docs say subagent edits land outside the current session checkpoints. For background <code>/code-review --fix</code> style edits, Anthropic tells users to use Git to revert those changes.</p>

<p>There are file system edge cases too. Current Claude Code behavior skips symlinked and hard-linked paths during rewind and reports those skipped files. That behavior was changed in version 2.1.216 after earlier versions could write or delete through links.</p>

<p>So the working rule is narrow: checkpoints are for Claude-tracked file edits and session context. They are not a full workspace snapshot.</p>

<p><strong>Internal link anchor point:</strong> <a href="/guides/ai-coding-agent-env-protection">AI coding agent environment protection</a></p>

<h2>Why Git commits still own the team boundary</h2>

<p>Git has a different job. It gives the team a durable object: a commit hash, a branch, a diff, a pull request, a CI target, and a revert path. That object can be pushed, reviewed, protected, signed, bisected, deployed, reverted, and audited.</p>

<p>Claude Code checkpoints cannot do that. They are private recovery state tied to a session. The official checkpointing docs are explicit on this point: think of checkpoints as local undo and Git as permanent history.</p>

<p>This becomes obvious as soon as work leaves your laptop. GitHub protected branches can require reviews, status checks, resolved conversations, signed commits, linear history, merge queue, and deployment success before merge. Those controls attach to Git commits and branches. They do not attach to Claude checkpoint snapshots.</p>

<p>For teams, that is the decisive difference. A checkpoint can help the developer recover. A commit lets the organization decide whether a change is acceptable.</p>

<h2>Claude Code checkpoints vs Git commits in practice</h2>

<p>The clean comparison is not "which is better?" They solve different problems.</p>

<table> <thead> <tr> <th>Question</th> <th>Use Claude Code checkpoints</th> <th>Use Git commits</th> </tr> </thead> <tbody> <tr> <td>You want to abandon a bad prompt path.</td> <td>Yes. Restore code and conversation with <code>/rewind</code>.</td> <td>Only if the bad path was already committed.</td> </tr> <tr> <td>You want to undo tracked Claude file edits from this session.</td> <td>Yes, when the edits were made through Claude's file editing tools.</td> <td>Yes, if the change is represented in Git.</td> </tr> <tr> <td>You want to undo bash side effects.</td> <td>No. Checkpoints do not track shell-created changes.</td> <td>Partly. Git can restore tracked files, but not databases, services, remote pushes, or external effects.</td> </tr> <tr> <td>You want CI, branch protection, and review.</td> <td>No.</td> <td>Yes. This is Git's job.</td> </tr> <tr> <td>You want permanent history.</td> <td>No. Checkpoints are session recovery state with retention limits.</td> <td>Yes.</td> </tr> <tr> <td>You want to restore the model's conversational context.</td> <td>Yes. Git cannot do this.</td> <td>No.</td> </tr> </tbody> </table>

<h2>The safe workflow: explore with checkpoints, publish with Git</h2>

<p>In practice, the best workflow is a two-stage loop.</p>

<p>First, let checkpoints make exploration less brittle. Use Claude Code for local refactors, spike fixes, and trial implementations. If the agent gets anchored to a bad approach, rewind the code and conversation. If part of the code is useful but the discussion is polluted, commit the good code, then rewind the conversation to regain a cleaner frame.</p>

<p>Second, collapse the work into Git deliberately. Before you ask for review, inspect the diff, remove accidental changes, rerun the right checks, and create semantic commits or a clean PR branch. The commit should describe the change a human reviewer is being asked to accept, not the sequence of prompts Claude happened to follow.</p>

<p>This is where teams should be strict. Agent scratch work can be messy. Shared history should not be.</p>

<h2>The bash gap is the part that bites</h2>

<p>The most important checkpoint limitation is not obscure. It is the ordinary shell.</p>

<p>Suppose Claude says it needs to run a codemod. The codemod rewrites files outside the edit tool. Or it runs a package manager and changes a lockfile. Or it applies a local migration. Or it invokes a generator that creates files across the repository. A later <code>/rewind</code> may restore tracked edits, but it will not necessarily put the whole workspace back the way it was.</p>

<p>That is why a "commit-first" reflex still belongs in serious workflows. Before broad shell operations, migrations, dependency updates, code generators, or Git-mutating commands, create a clean Git point you can reason about. You may not keep that commit forever. You may squash it later. But it gives you an external recovery handle that is not tied to Claude's session mechanics.</p>

<p>For higher-risk work, use an isolated worktree or disposable environment as well. Anthropic's worktree docs note that worktrees isolate file edits into separate directories and branches, but share the repository's <code>.git</code> directory. That means Git commands from a worktree still write to shared Git metadata. Worktrees help, but they are not a substitute for Git discipline.</p>

<p><strong>Internal link anchor point:</strong> <a href="/guides/claude-code-worktree-database-isolation">Claude Code worktree database isolation</a></p>

<h2>What to do about checkpoint-looking Git commits</h2>

<p>Some community reports describe Claude Code workflows where checkpoint-looking commits appeared in Git history, with names such as timestamped checkpoint commits. Those reports are useful because they show a real team pain: temporary recovery points can pollute shared history if they are pushed as ordinary commits.</p>

<p>But treat that evidence carefully. The current official checkpointing docs describe file snapshots, not automatic Git commits, as the checkpointing mechanism. The research brief did not find official documentation for settings such as <code>autoCheckpointCommits</code>. So do not write policy around the assumption that current Claude Code checkpoints are Git commits by default.</p>

<p>Do write policy around the underlying problem: scratch history should not leak into protected branches.</p>

<p>A practical policy looks like this:</p>

<ul> <li>Agent sessions may use scratch branches or worktrees for recovery.</li> <li>Agents must ask before running <code>git commit</code>, <code>git push</code>, <code>git reset</code>, or <code>git rebase</code>.</li> <li>Developers clean up local history before opening a PR.</li> <li>Protected branches receive semantic commits or squash-merged changes, not prompt-by-prompt recovery noise.</li> <li>Reviewers judge the final diff and evidence bundle, not the agent transcript as a substitute for review.</li> </ul>

<p>If you want intermediate recovery states, keep them local or inside a scratch branch. If a change is ready for the team, promote it into a commit that explains the software change.</p>

<h2>A team policy that fits both tools</h2>

<p>Good policy does not ban checkpoints. It gives them the right job.</p>

<p>Use this operating model:</p>

<ul> <li><strong>Before agent work:</strong> start from a clean Git status when possible. If the task may shell out, migrate data, update dependencies, or touch many files, create a Git commit or isolated branch first.</li> <li><strong>During agent work:</strong> use checkpoints for local recovery when the agent takes a bad turn. Rewind conversation as well as code when the model's reasoning path is the problem.</li> <li><strong>Before review:</strong> inspect the full Git diff, including untracked files. Remove generated or accidental changes. Rerun the relevant tests and record the commands.</li> <li><strong>At PR time:</strong> submit a clean changeset with a human-readable summary, test evidence, known risks, and rollback notes.</li> <li><strong>At merge time:</strong> rely on GitHub branch protections, required reviews, status checks, code-owner review where relevant, and deployment gates.</li> </ul>

<p>The important distinction is authority. A checkpoint helps the person driving the session. Git governs the change that enters the organization.</p>

<h2>Decision rule</h2>

<p>Use <code>/rewind</code> when the agent went wrong inside the current Claude Code session and you need to recover tracked file edits, conversation state, or both.</p>

<p>Use Git when the change has to survive the session, be shared with another person, trigger CI, pass branch protection, support rollback, or become part of an audit trail.</p>

<p>That is the whole shape of <strong>Claude Code checkpoints vs Git commits</strong>: checkpoints make local agent exploration safer. Git makes software delivery accountable.</p> </article>