Checkpoints

Checkpoints automatically version your workspace files during Gamecraft tasks, enabling non-destructive exploration of AI suggestions and easy recovery from unwanted changes.

This powerful feature enables you to:

  • Experiment Confidently: Try AI suggestions without fear of breaking your project

  • Recover Quickly: Undo unwanted changes with a single click

  • Compare Alternatives: Evaluate different implementation strategies side-by-side

  • Iterate on Past States: Jump back to a previous project state to try a new direction

How it Works

The checkpoint system operates through an isolated Git repository that runs parallel to your existing version control setup. This dedicated tracking system automatically creates save points during your AI workflow, triggered by task initialization, file modifications, and command execution.

Prerequisites

  • Git Installation Required: The system depends on Git for version tracking capabilities

  • No External Accounts Required: Works without GitHub, GitLab, or other remote repositories

  • Zero Configuration: No need to set up Git user credentials or personal information

  • Isolated Operation: Functions independently from your project's main Git repository

Using Checkpoints​

Checkpoints are integrated directly into your workflow through the chat interface.

Each checkpoint preserves:

  • Modified file contents

  • Newly created files

  • Removed files

  • File relocations and renames

  • Binary file modifications

Checkpoints appear directly in your chat history in two forms:

  • Initial checkpoint marks your starting project state

  • Follow-up checkpoints appear after file modifications or command execution

Each checkpoint provides two primary functions:

Viewing Differences​

To compare your current workspace with a previous checkpoint:

  1. Locate the checkpoint in your chat history

  2. Click the checkpoint's View Differences button

  1. Review the differences in the comparison view:

    • Added lines are highlighted in green

    • Removed lines are highlighted in red

    • Modified files are listed with detailed changes

    • Renamed and moved files are tracked with their path changes

    • New or deleted files are clearly marked

Restoring Checkpoints​

To restore a project to a previous checkpoint state:

  1. Locate the checkpoint in your chat history

  2. Click the checkpoint's Restore Checkpoint button

  1. Choose one of these restoration options:

  • Restore Files Only - Reverts only workspace files to checkpoint state without modifying conversation history. Ideal for comparing alternative implementations while maintaining chat context, allowing you to seamlessly switch between different project states. This option does not require confirmation and lets you quickly switch between different implementations.

  • Restore Files & Task - Reverts both workspace files AND removes all subsequent conversation messages. Use when you want to completely reset both your code and conversation back to the checkpoint's point in time. This option requires confirmation in a dialog as it cannot be undone.

Limitations and Considerations​

  • Scope: Checkpoints only capture changes made during active Gamecraft tasks

  • External changes: Modifications made outside of tasks (manual edits, other tools) aren't included

  • Large files: Very large binary files may impact performance

  • Unsaved work: Restoration will overwrite any unsaved changes in your workspace

Technical Details

Core Components

The checkpoint infrastructure comprises three main elements:

Isolated Git Repository: A dedicated version control system exclusively for checkpoint data storage and management

Checkpoint Manager: Orchestrates Git operations including:

  • Shadow repository setup and initialization

  • Snapshot creation and persistence

  • Difference calculation algorithms

  • State restoration procedures

User Interface: Chat-embedded controls for checkpoint interaction and management

Restoration Mechanics

During checkpoint restoration, the system executes:

  1. Hard reset to the specified commit in the shadow repository

  2. File synchronization from shadow repository to active workspace

  3. Internal state tracking updates

Data Organization

Checkpoints operate within task boundaries, ensuring each AI session maintains its own checkpoint timeline.

Diff Creation

Change detection leverages Git's native diffing engine to generate comprehensive file comparisons:

  • Line-level modifications in text files

  • Binary file detection and appropriate handling

  • File movement and renaming tracking

  • File creation and deletion identification

File Filtering and Exclusions

The checkpoint system employs intelligent file filtering to track only relevant project assets:

Automatic Exclusions

The system includes comprehensive exclusion patterns that automatically ignore:

  • Build Artifacts: Dependencies and compilation outputs (node_modules/, dist/, build/)

  • Media Assets: Binary content like images, videos, and audio files

  • Temporary Data: Cache directories, temporary files, and backup copies (.cache/, .tmp/, .bak)

  • Sensitive Configuration: Environment files containing secrets (.env)

  • Large Binary Files: Archives, executables, and database files

  • System Files: Logs and other system-generated content

These exclusion rules are automatically configured in the shadow repository's Git exclude file during setup.

.gitignore Integration

The checkpoint system honors existing .gitignore patterns in your workspace:

  • Files excluded by .gitignore will not trigger checkpoint creation

  • Ignored files won't appear in checkpoint difference views

  • Standard Git ignore syntax and rules apply during file staging

.gamecraftignore Separation

The .gamecraftignore file (controlling AI file access) operates independently from checkpoint tracking:

  • Files blocked by .gamecraftignore but allowed by .gitignore remain under checkpoint tracking

  • Changes to AI-inaccessible files can still be restored via checkpoints

  • This separation maintains the distinction between AI access control and version history

Nested Repository Handling

Special logic manages projects containing nested Git repositories:

  • Temporarily renames nested .git directories to .git_disabled during checkpoint operations

  • Restores original names after operations complete

  • Enables proper file tracking within nested repositories

  • Preserves nested repository functionality and integrity

Concurrent Operation Management

A queuing system prevents overlapping Git operations that could corrupt repository state, ensuring checkpoint operations complete safely even when requested in rapid succession.

Git Installation Instructions

Gamecraft Checkpoints require Git to be installed on your system for version control features and project management.

Check if Git is Already Installed

Before installing, check if Git is already on your system:

Windows

  1. Open Command Prompt or PowerShell

  2. Type: git --version

  3. If Git is installed, you'll see the version number (e.g., git version 2.40.0)

Mac

  1. Open Terminal (found in Applications > Utilities)

  2. Type: git --version

  3. If Git is installed, you'll see the version number

If you see a version number, Git is already installed and you can skip to the Installation Steps section.

Installing Git

Windows Installation

  1. Download Git:

    • Visit https://git-scm.com/download/windows

    • The download should start automatically for the latest version

  2. Run the installer:

    • Double-click the downloaded .exe file

    • Follow the installation wizard with these recommended settings:

      • Select Components: Keep default selections

      • Default editor: Choose your preferred editor (or keep default)

      • PATH environment: Select "Git from the command line and also from 3rd-party software"

      • HTTPS transport backend: Use the OpenSSL library

      • Line ending conversions: "Checkout Windows-style, commit Unix-style line endings"

      • Terminal emulator: Use MinTTY

      • Extra options: Enable file system caching and Git Credential Manager

  3. Verify installation:

    • Open a new Command Prompt or PowerShell window

    • Type: git --version

    • You should see the Git version number

Mac Installation

There are several ways to install Git on Mac:

Option 1: Using Homebrew (Recommended)

  1. Install Homebrew (if not already installed):

    • Open Terminal

    • Run: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Install Git:

    • Run: brew install git

  3. Verify installation:

    • Run: git --version

Option 2: Using the Official Installer

  1. Download Git:

    • Visit https://git-scm.com/download/mac

    • Download the latest installer for macOS

  2. Run the installer:

    • Open the downloaded .dmg file

    • Double-click the .pkg installer

    • Follow the installation prompts

  3. Verify installation:

    • Open Terminal

    • Run: git --version

Option 3: Install via Xcode Command Line Tools

  1. Install Command Line Tools:

    • Open Terminal

    • Run: xcode-select --install

    • Click "Install" when prompted

  2. Verify installation:

    • Run: git --version

PreviousAsk & Agent ModesNextCustom Instructions

Last updated