Checkpoints and Branching Strategies

You asked Agent to refactor your authentication module. It rewrote six files, reorganized imports, and updated three test files. Then you noticed it also changed your database connection pooling logic — something you never asked for. You press undo a few times, but the changes are interleaved across files and you cannot get back to a clean state. You close Cursor, run git checkout ., and lose the authentication changes you actually wanted.

This scenario is entirely preventable. Cursor’s checkpoint system, combined with disciplined git branching, gives you a safety net that lets you experiment aggressively without risking your working code.

What You’ll Walk Away With

• A workflow for using Cursor’s automatic checkpoints to roll back unwanted AI changes
• A git branching strategy designed specifically for AI-assisted development
• Techniques for combining checkpoints with git commits for multi-layer safety
• Copy-paste prompts for safe experimentation patterns

How Cursor Checkpoints Work

Every time Agent makes a set of changes, Cursor automatically creates a checkpoint. This checkpoint captures the state of all modified files before the changes were applied. You can restore any checkpoint to undo a specific set of AI changes without affecting other work.

Checkpoints are visible in the chat history. Each Agent response that modified files has a “Restore” option that reverts the codebase to the state before those changes.

Checkpoint Limitations

Checkpoints are local to your Cursor session. They are not persisted across IDE restarts. They do not capture terminal side effects (if Agent ran a database migration, restoring the checkpoint does not undo the migration). And they track file changes only — if Agent deleted a file, restoring brings it back, but if Agent created new files that you then manually edited, things get complicated.

This is why checkpoints alone are not enough. You need git as your primary safety net.

The Two-Layer Safety Strategy

Layer 1 is git commits. Layer 2 is Cursor checkpoints. Use them together:

1. Create a feature branch before starting any AI-assisted work
2. Commit your current clean state (even if it is just the branch creation)
3. Let Agent make changes — Cursor automatically creates checkpoints
4. Review the changes. If they look good, commit them with a descriptive message
5. If the changes are partially good, use the checkpoint to restore, then re-prompt with more specific instructions
6. If everything went wrong, git checkout . to return to your last commit

Tip

Copy-paste prompt for previewing changes before execution:

Before you make any changes, tell me your plan. List the files you intend to modify and what changes you will make to each one. Wait for my approval before proceeding.

Use this when working on critical code paths where you want to vet the approach before the agent touches anything.

Git Branching for AI-Assisted Development

Standard git branching works for AI development, but the cadence is different. With AI, you generate more speculative changes that may or may not pan out. This calls for more frequent, smaller commits and a willingness to throw away branches entirely.

The Micro-Branch Pattern

Instead of one feature branch with many commits, create micro-branches for each AI experiment:

# Main feature branch
git checkout -b feature/payment-system

# Micro-branch for the first AI experiment
git checkout -b feature/payment-system/stripe-approach

# If it works, merge back
git checkout feature/payment-system
git merge feature/payment-system/stripe-approach

# If it does not, discard
git checkout feature/payment-system
git branch -D feature/payment-system/stripe-approach

This pattern works well when you want Agent to try different approaches to the same problem. Spin up a branch, let Agent work, evaluate the result, and either merge or discard.

Commit Cadence for AI Work

Commit more frequently than you would with manual coding:

• Before each Agent prompt — So you have a clean restore point
• After each successful Agent change — Lock in good work immediately
• After manual tweaks to AI output — Keep your refinements separate from the AI’s work

Tip

Copy-paste prompt for commit-aware workflow:

I am about to ask you to make significant changes. Before you start, run `git status` to confirm there are no uncommitted changes. If there are uncommitted changes, stop and tell me -- I need to commit or stash them first.

Parallel Agents and Worktrees

Cursor supports parallel agents that run in isolated git worktrees. You can run the same prompt against multiple models simultaneously, compare the results, and apply the best one.

Setting Up Worktrees

Cursor automatically creates and manages worktrees for parallel agents. When you launch a parallel agent, it gets its own copy of your codebase. Your main working tree is unaffected until you choose to apply changes.

Configure worktree initialization in .cursor/worktrees.json:

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

For Python projects:

{
  "setup-worktree": [
    "python -m venv venv",
    "source venv/bin/activate && pip install -r requirements.txt",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

Best-of-N: Multiple Models, One Prompt

Send the same prompt to two or more models and compare their approaches:

1. Select multiple models in the parallel agent dropdown
2. Submit your prompt
3. Each model works independently in its own worktree
4. Compare the results side by side
5. Click “Apply” on the one you prefer

This is powerful for hard problems where different models take different approaches. You can also use it to benchmark which model works best for your codebase.

Caution

Worktrees currently do not have LSP (Language Server Protocol) support, so agents in worktrees cannot access linting information. Run linting yourself after applying worktree changes.

Advanced Checkpoint Patterns

The Incremental Commit Pattern

For large, multi-step features:

1. Ask Agent to implement step 1 of your plan
2. Review the changes, commit if good
3. Ask Agent to implement step 2, building on committed step 1
4. Review, commit
5. Continue until complete

If step 3 goes wrong, you only lose step 3’s work. Steps 1 and 2 are safely committed.

The Selective Accept Pattern

Agent often generates changes that are 80% correct. Instead of accepting or rejecting everything:

1. Review the diff in Cursor’s change view
2. Accept the changes you want (click the checkmark on individual files)
3. Reject the changes you do not want
4. Commit the accepted changes
5. Re-prompt Agent for just the rejected parts, being more specific

Tip

Copy-paste prompt for targeted rework:

Your previous changes to src/services/payment.ts were good and I have accepted them. However, the changes to src/controllers/checkout.ts did not handle the case where the payment provider returns a pending status. Please redo only the checkout controller changes, keeping the payment service as-is. Handle pending status by returning a 202 response with a polling URL.

When This Breaks

Checkpoints disappear after restarting Cursor. They are session-local. Always commit important work to git. Never rely on checkpoints as your only safety net.

Agent modifies files you already committed. Start a new chat for each distinct task. Long conversations cause the agent to lose track of what has been committed versus what is still in progress.

Worktree setup fails. Check .cursor/worktrees.json for syntax errors. Debug the setup script via the Output panel, selecting “Worktrees Setup” from the dropdown. Use pnpm or bun instead of npm install for faster worktree initialization.

Merge conflicts when applying worktree changes. Cursor offers “Full Overwrite” or native conflict resolution. For complex conflicts, apply worktree changes to a new branch and resolve there.

What’s Next

• Large Codebase Strategies — Branching strategies matter more at scale
• Agent Modes Deep Dive — Plan mode creates structured plans before Agent executes
• Token Management — Parallel agents consume more tokens; manage costs effectively