Articles/Antigravity Basics

◉ Antigravity Basics/2026-03-27Advanced

Antigravity Checkpoints & Rollback Mastery — Advanced Version Control for AI-Powered Development

A comprehensive guide to Antigravity's checkpoint system and rollback operations. Covers the auto-save mechanism, diff comparison, Git branch integration, and production-grade disaster recovery patterns.

antigravity⁴²⁹ checkpoints² rollback³ version-control git¹² disaster-recovery

✦ Premium Article

Setup and context — Why Checkpoints Are Essential for AI-Powered Development

When AI agents write code on your behalf, a new class of challenges emerges. The fundamental question becomes: how do you manage changes that an AI generates, and how do you safely revert them when things go wrong?

Traditional Git-based version control assumes manual human commits. But AI agents can modify dozens of files in seconds. If your commits are too coarse-grained, isolating and reverting a problematic change becomes nearly impossible. If they're too fine-grained, your commit history becomes an unmanageable mess.

Antigravity's checkpoint system offers an elegant solution to this problem. It automatically records every change an AI agent makes, allowing you to roll back to any point in time with precision. This article provides a systematic deep dive — from the internal architecture of checkpoints to practical production-grade operational patterns.

By the end of this article, you'll be able to:

Understand exactly when and how checkpoints are recorded
Use multiple rollback techniques to undo changes with minimal impact
Build a production workflow that integrates Git branching with checkpoints

This guide is written for software engineers who use Antigravity daily and want to make their change management more robust when collaborating with AI agents.

The Internal Mechanics of Checkpoints

How Auto-Checkpoints Work

Antigravity creates checkpoints automatically at the end of each agent turn. Specifically, a checkpoint is recorded at these moments:

When the agent completes file creation, editing, or deletion
When the agent turn transitions (i.e., the agent returns a response to the user)
At configurable intervals during long-running tasks

A checkpoint is essentially a filesystem snapshot. Unlike a Git commit, there's no staging step — all changes are captured automatically.

// Conceptual data structure of a checkpoint
interface Checkpoint {
  id: string;                    // Unique identifier
  timestamp: number;             // Creation time (Unix timestamp)
  agentTurn: number;             // Agent turn number
  description: string;           // AI-generated description of changes
  filesModified: string[];       // Paths of modified files
  filesCreated: string[];        // Paths of newly created files
  filesDeleted: string[];        // Paths of deleted files
  parentCheckpointId: string;    // ID of the previous checkpoint
}
 
// Retrieving checkpoint history (conceptual API)
// In Antigravity's UI, checkpoints are visualized in the Timeline panel

Checkpoints vs. Git Commits

Checkpoints and Git commits serve fundamentally different purposes, and understanding this distinction is the first step to using them effectively.

Checkpoints are temporary, internal snapshots within Antigravity. They persist across sessions but are never pushed to remote repositories. Think of them as a record of the "experimentation" phase of your work.

Git commits are permanent change history meant to be shared with your team. The ideal workflow is to verify changes using checkpoints, then promote them to Git commits in meaningful units.

# View checkpoint history in Antigravity's Timeline UI
# Each checkpoint includes an auto-generated description of the agent's changes
 
# Recommended workflow: verify with checkpoints → promote to Git commits
# 1. Ask the agent to implement a feature (checkpoints are created automatically)
# 2. Review diffs between checkpoints
# 3. Once satisfied, create a formal Git commit
git add -A
git commit -m "feat: implement user authentication flow"

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Understand the internal mechanics of checkpoints and optimal usage patterns

✦Implement robust rollback strategies to safely undo AI agent changes

✦Build a production-ready workflow that integrates Git branching with checkpoints

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

The Complete Rollback Guide

Basic Rollback — Restoring from the Timeline

The simplest rollback approach is selecting a specific checkpoint from Antigravity's Timeline panel and restoring to that point.

Here's the step-by-step process:

Open the Timeline panel on the right side of the screen
Click on the checkpoint you want to restore to
Review the change diff and click "Restore"
Confirm by selecting "Yes, restore" in the confirmation dialog

This operation undoes all changes made after the selected checkpoint. Importantly, the undone changes aren't lost forever — a "pre-rollback" checkpoint is automatically created, so you can undo the rollback itself if needed.

Partial Rollback — Restoring Specific Files Only

When you need to revert only certain files rather than everything, partial rollback is your best option. This is especially useful when the AI agent modified multiple files but only some of those changes were problematic.

# Example: restoring specific files via the terminal
# After identifying the problematic files in the Timeline diff view
 
# 1. Review the diff
# Open the relevant checkpoint's diff view in the Timeline
 
# 2. Restore only the problematic files using Git
git checkout HEAD~1 -- src/components/Auth/LoginForm.tsx
git checkout HEAD~1 -- src/hooks/useAuth.ts
 
# 3. Commit the restored state
git add src/components/Auth/LoginForm.tsx src/hooks/useAuth.ts
git commit -m "revert: restore LoginForm and useAuth to previous state"

Interactive Rollback — Conversational Recovery with the Agent

Antigravity's most powerful rollback technique is instructing the agent to perform a restoration using natural language.

// Example instruction to the agent:

"The authentication flow changes from the last turn broke the LoginForm
validation. Please revert only the validation logic to the state it was
in two checkpoints ago, while keeping all other changes intact."

With this instruction, the agent analyzes the checkpoint diffs and precisely reverts only the validation-related changes. This isn't a simple file restore — it's a semantically-aware partial rollback that understands the meaning of the code.

Advanced Checkpoint Strategies

Strategic Checkpoints — Manual Saves Before Critical Work

In addition to automatic checkpoints, it's good practice to intentionally create checkpoints before high-risk changes.

// Example instruction to the agent (before critical changes):

"I'm about to make a major database schema change. Please save the
current state as a checkpoint before starting the work."

For particularly risky operations, the following "safety net" pattern is highly effective:

# Safety net pattern: establish clear markers before and after critical changes
 
# Step 1: Verify current Git state
git status
git stash  # Stash uncommitted changes if any
 
# Step 2: Create a new branch (checkpoint + Git double protection)
git checkout -b feature/db-schema-migration
 
# Step 3: Instruct the agent
# "Start the database schema changes. After each table modification,
#  pause so I can verify the checkpoint."
 
# Step 4: If something goes wrong
git checkout main  # Discard the entire branch and start fresh

Checkpoint Lifecycle Management

Checkpoints don't accumulate indefinitely. For storage efficiency, they follow this lifecycle:

Current session: All checkpoints are retained
Previous sessions: Start and end checkpoints for each session are retained
Older sessions: Only the final checkpoint is kept (or deleted based on settings)

// Example: defining checkpoint policy in AGENTS.md
// Set project-specific checkpoint management rules
 
/*
## Checkpoint Policy
 
- Database changes: verify checkpoint after each migration file
- UI component changes: verify at the component level
- Config file changes: confirm checkpoint exists before modification
- Test additions/modifications: verify after running the test suite
*/

Integrating with Git Branch Strategies

Feature Branch + Checkpoint Pattern

The most recommended pattern for production environments combines Git Feature Branches with checkpoints in a two-layer management approach.

# Feature Branch + Checkpoint workflow
 
# 1. Create a Feature Branch
git checkout -b feature/user-dashboard
 
# 2. Instruct the agent to implement the feature
#    → Checkpoints are automatically created at each step
 
# 3. Verify incrementally using checkpoints
#    → Roll back to a checkpoint if issues arise
 
# 4. After verification, create meaningful Git commits
git add src/pages/Dashboard/
git commit -m "feat: implement dashboard base layout"
 
git add src/components/Charts/
git commit -m "feat: add chart components for dashboard"
 
# 5. Merge into main
git checkout main
git merge --no-ff feature/user-dashboard
 
# 6. Delete the Feature Branch (checkpoint history remains in the session)
git branch -d feature/user-dashboard

Integration with Trunk-Based Development

For small teams or solo developers, combining Trunk-Based Development (committing directly to main) with checkpoints can be highly effective.

# Trunk-Based + Checkpoint workflow
 
# 1. Work directly on main
git checkout main
 
# 2. Instruct the agent in small, focused units
#    "Add email validation to the LoginForm."
#    → A checkpoint is automatically created
 
# 3. Verify immediately and commit if everything looks good
npm run test
git add src/components/Auth/LoginForm.tsx
git add src/components/Auth/__tests__/LoginForm.test.tsx
git commit -m "feat: add email address validation"
git push origin main
 
# 4. If issues arise, roll back using checkpoints
#    → Safe to redo even on the main branch

Leveraging Checkpoints Before Releases

During pre-release final verification, checkpoints serve as a powerful safety net.

# Pre-release checklist with checkpoint utilization
 
# Step 1: Create a release branch
git checkout -b release/v2.1.0
 
# Step 2: Ask the agent to address pre-release fixes
#    "Please fix the following issues: #142, #155, #163"
#    → A checkpoint is created for each issue fix
 
# Step 3: Run the CI/CD pipeline
npm run lint
npm run test
npm run build
 
# Step 4: If issues are found
#    → Roll back to the relevant checkpoint
#    → Re-implement the fix
 
# Step 5: After all tests pass, tag the release
git tag -a v2.1.0 -m "Release v2.1.0"
git push origin v2.1.0

Disaster Recovery Patterns for Production

Pattern 1: Recovering from Agent Runaway

When an AI agent makes unintended large-scale changes, follow this recovery procedure.

# Runaway recovery procedure
 
# 1. Stop the agent immediately
#    → Cmd+Shift+Backspace (Mac) / Ctrl+Shift+Backspace (Windows)
 
# 2. Review the scope of changes in the Timeline
#    → Identify the number of changed files and the blast radius
 
# 3. Identify the last good checkpoint before the runaway
#    → Find the "everything was still correct here" point in the Timeline
 
# 4. Execute the rollback
#    → Select the checkpoint in the Timeline and click Restore
 
# 5. Verify the Git state
git status
git diff  # Confirm changes have been cleanly reverted
 
# 6. Create a Git backup as an additional safety measure
git stash  # Stash current changes just in case

Pattern 2: Recovering After a Problematic Deployment

When issues surface after deployment, the combination of checkpoints and Git enables rapid recovery.

# Post-deployment recovery
 
# 1. Identify the production issue
# Check logs, monitoring dashboards, and user reports
 
# 2. Revert to the previous release using Git
git revert HEAD  # Undo the most recent commit
# or
git checkout v2.0.0  # Switch to the last stable release tag
 
# 3. Emergency deploy
git push origin main  # CI/CD automatically deploys
 
# 4. Use Antigravity checkpoints to identify the root cause
#    → Ask the agent: "Analyze the v2.1.0 changes and identify what went wrong"
 
# 5. Create a hotfix
#    → Use checkpoints to isolate and fix only the problematic changes

Pattern 3: Resolving Team Merge Conflicts

When multiple developers work simultaneously, checkpoints can assist in resolving merge conflicts.

# Conflict resolution workflow
 
# 1. A conflict occurs during merge
git merge feature/payment-flow
# CONFLICT (content): Merge conflict in src/api/checkout.ts
 
# 2. Ask the agent to resolve the conflict
#    "Resolve the merge conflict in checkout.ts. Prioritize the payment
#     logic from the payment-flow branch while preserving the validation
#     improvements from main."
 
# 3. The agent resolves conflicts with checkpoints at each step
#    → A checkpoint is recorded for each file resolution
 
# 4. Verify the resolution
git diff --check  # Ensure no conflict markers remain
npm run test      # Confirm tests pass
 
# 5. Complete the merge commit
git add .
git commit -m "merge: integrate payment-flow (conflicts resolved)"

Configuring Checkpoint Policies in AGENTS.md

By documenting checkpoint policies in your project's AGENTS.md, the agent automatically follows those guidelines.

# Add to your project's AGENTS.md
 
## Change Management Policy
 
### Checkpoint Guidelines
- Database migrations: leave a descriptive checkpoint memo
  after each migration execution
- API endpoint changes: explicitly verify state before making
  any backward-incompatible changes
- Config file changes: document existing configuration
  before modifications
 
### Rollback Criteria
- If any test fails: roll back to the previous checkpoint
- If a build error occurs: analyze the cause before deciding
- If performance degrades by more than 20%: compare checkpoints to identify the cause

With this configuration, the agent automatically manages checkpoints according to these criteria and makes appropriate rollback decisions when issues arise.

Summary

Antigravity's checkpoint system establishes a new standard for change management in AI-powered development. With automatic checkpoint recording, you can safely manage AI agent changes and rapidly roll back when issues arise.

Let's recap the key takeaways.

Checkpoints are a safety net that complements Git commits, created automatically at each agent turn. There are three types of rollback — full restore, partial restore, and conversational agent-driven rollback — and choosing the right one depends on the situation. By combining checkpoints with your Git branching strategy, whether Feature Branch or Trunk-Based Development, you achieve robust change management for any workflow.

To build an environment where you can confidently delegate work to AI agents, make checkpoints a core part of your development practice.

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.