← Back to Blog

What Can Cline Checkpoints Revert? Code Rollback, Chat History, and Git Worktree Boundaries

Learn what Cline checkpoints restore, why worktrees are not permission sandboxes, and how to verify file and chat recovery before relying on agent rollback.

When using Cline for autonomous software engineering, developers often view checkpoints as a universal undo mechanism. However, treating checkpoints as an infallible safety net can lead to data loss, uncontained mutations, and unexpected token consumption. This article analyzes checkpoint architecture, rollback boundaries, and Git worktree integration based on published technical documentation .

Clarification: The mechanisms described below synthesize official documentation rather than assertions from live UI tests in a specific Cline build. Specific UI labels and snapshot triggers can vary across releases.

Checkpoint Architecture and Recovery Scope

According to the Cline Checkpoints Documentation, Cline tracks workspace snapshots using a shadow Git system that operates independently of the project’s primary Git commit tree. Because shadow Git recalculates indexes and commit hashes across file states, tracking very large codebases may introduce storage and performance overhead.

Semantic Categories of Restoration

According to the official core workflow docs and the Cline IDE Interface Guide, checkpoints offer three distinct restoration modes:

  1. Restore Files (or Restore Workspace Only): Reverts local workspace files to the selected snapshot while preserving subsequent conversation history and analysis.
  2. Restore Task Only: Truncates the conversation tree back to the chosen turn, discarding subsequent prompt messages while leaving files on disk untouched.
  3. Restore Files & Task (or Restore Task and Workspace): Reverts workspace files and conversation history together, realigning context and source files to that milestone.

What Checkpoints Can and Cannot Revert

Checkpoints strictly govern local workspace files and conversation context. They do not provide an operating-system permission sandbox:

CategoryReversible by CheckpointsOperational Context
Tracked local file changesYesReverts modifications, additions, and deletions tracked by shadow Git.
Chat conversation contextYes (Optional)Removes turns to reset the model instruction chain.
Consumed API tokensNeverTokens spent on model inference cannot be reversed or refunded by restoring files.
External API & cloud servicesNeverProvisioned cloud instances, triggered webhooks, and third-party API mutations persist.
Database reads, writes, migrationsNeverCheckpoints cannot reverse database side effects. Restoring local database files is not transaction recovery and can corrupt active databases.
Background processes & daemonsNeverLong-running test runners, web servers, and container instances stay active.
Remote Git operationsNeverOnce git push executes, local checkpoints hold zero authority over remote branches.

Critical Note: Checkpoints cannot undo external side effects and does not reverse API billing. Never treat checkpoints as a justification for unconditionally enabling global auto-approve permissions.

Standard Seven-Step Recovery Flow

When code generation breaks builds, fails tests, or veers off course, follow this structured recovery workflow:

  1. Halt Concurrent Operations: Stop the active Cline task or disable autonomous execution immediately to prevent further writes.
  2. Back Up Untracked Artifacts: Checkpoints may not reliably capture untracked files or outputs excluded by ignore rules. Archive essential outputs before reverting.
  3. Inspect the Snapshot Diff: Use IDE comparison tools to review differences between current files and the target snapshot.
  4. Choose Granular Recovery: Use Restore Task Only if only reasoning diverged, Restore Files if code broke but reasoning remains useful, or Restore Files & Task to reset completely.
  5. Prompt Agent to Re-read Files: After resetting files, explicitly instruct the agent to inspect the filesystem and check Git status to clear stale memory representations.
  6. Execute Project Test Suites: Run your local test suite and compiler checks to verify that runtime behavior is restored.
  7. Review Diffs and Commit: Once verified manually, create a formal Git commit to establish a version-controlled baseline.

Using Git Worktrees for Directory Separation

Checkpoints provide short-term rollback inside your editor, while Git Worktrees provide filesystem-level directory separation. Worktrees allow checking out multiple branches simultaneously across separate directory paths while sharing repository objects and refs.

Point Cline to the separate worktree for branch-specific edits. This does not prevent the agent from accessing the main workspace.

Security Boundary Notice: A Git worktree separates working directories, but it is not a permission sandbox. Running processes can still read or write other directories, bind local ports, call local services, and access shared environment credentials.

Isolation Setup Walkthrough

In a clean repository with an existing commit history, run:

# 1. Review status in the primary working tree
git status --short

# 2. Check out a fresh experimental branch into a separate directory
# Note: The destination path ../cline-checkpoint-lab and branch must not already exist
git worktree add -b cline-checkpoint-lab ../cline-checkpoint-lab HEAD

# 3. Verify active worktrees
git worktree list

Open a new editor window targeting ../cline-checkpoint-lab, and initiate your Cline tasks inside this workspace.

Inspection and Verification

Once the agent completes its experiment, inspect changes within that directory:

# Review summary of modified files
git diff --stat

# Check for whitespace issues or conflict artifacts
git diff --check

# Review repository status (note that standard git diff excludes untracked files)
git status --short

Clean up worktrees deliberately after manual review.

Disposable Directory Verification Checklist

The Git commands above were exercised in a disposable repository. The following is a proposed local checklist, not a completed Cline UI or model end-to-end test. Before relying on checkpoints for complex repositories, validate your local installation:

  • Run one user task with two separate tool writes (create file_a, then file_b).
  • Inspect if the intermediate snapshot exists.
  • Restore files to the first write state, expecting file_a present and file_b absent.
  • If the intermediate snapshot is missing, tool-specific recovery is unverified.
  • Reset to the second state before a task-only restore; verify files remain unchanged and chat state updates correctly.

High-Efficiency API Routing to Mitigate Iteration Costs

Frequent rollbacks and prompt retries consume token volume. Because checkpoints cannot reverse token consumption or API billing, stabilizing access to cost-effective upstream models is essential for sustained agent workflows.

Using a unified gateway allows you to route Cline directly to reasoning models. Based on the Cline OpenAI-Compatible Provider Setup, configure the connection in Cline settings:

Setting FieldConfiguration Value
ProviderOpenAI Compatible
Base URLhttps://api.apibox.cc/v1
API KeyYour platform API token
Model IDTarget model identifier (such as gpt-6-astra, claude-sonnet-5, or gemini-3.8-flash)

Regarding model availability and tiered pricing, data from the APIBox Pricing Endpoint shows specific group multiplier structures:

  • GPT Tier: gpt-6-astra supports group multiplier 0.1 (90% OFF) when assigned to the gpt-vip-1 group condition.
  • Claude Tier: claude-sonnet-5 supports group multiplier 0.3 (70% OFF) when assigned to the claude-vip-2 group condition.
  • Gemini Tier: gemini-3.8-flash supports group multiplier 0.2 (80% OFF) when assigned to the gemini-vip group condition.

These multipliers require qualified user groups rather than applying automatically to all tokens. Stock availability and route entries do not guarantee full end-to-end client compatibility. Per APIBox Payment Information, WeChat and Alipay top-ups are supported. Gateway routing helps manage costs during agent trial and error, but it does not replace disciplined local checkpoints and Git version control practices.

Frequently Asked Questions

Can Cline checkpoints roll back database writes or external API requests?

Checkpoints cannot undo external database transactions, cloud writes, or reverse API billing. Restoring a local database file is not a transactional recovery process and may corrupt an active database if overwritten while in use.

How does Git worktree enhance agent experimentation safety compared to regular branches?

Worktrees use separate directories sharing repository objects, not a permission sandbox. Processes retain access to other directories and credentials; do not rely on this feature for security isolation.

What is the primary difference between Restore Files and Restore Task Only?

Restore Files only reverts workspace files to a selected snapshot while preserving all subsequent chat messages, whereas Restore Task Only truncates conversation messages after that turn without touching local disk files.


Further Reference & Architecture Guides:

Platform resources:

Try it now, sign up and start using 30+ models with one API key

Sign up free →