feat(cli): implemented Git-backed Named Checkpoints and Session Reversion

[AasheeshLikePanner]

Summary

This PR implements a robust Named Checkpoint system for the Gemini CLI, allowing users to save and restore atomic snapshots of both their project files and conversation history. This feature bridges the gap between simple chat "rewinding" and professional-grade session management.

Details

Unlike the existing /rewind command which uses heuristic patches, this system leverages the CLI's Shadow Git infrastructure to create 100% reliable state snapshots.

Key Design Decisions:

• Git-Backed Integrity: Uses GitService.createFileSnapshot to ensure that every restoration is byte-perfect, even if files were modified manually between turns.
• State Synchronization: When a checkpoint is restored, the ChatRecordingService is truncated to the matching messageId, and the ContextManager is force-refreshed. This ensures the LLM's "memory" perfectly matches the restored code state.
• Auto-Safety: Implemented automatic checkpointing before every user prompt, providing a "zero-config" recovery point for every interaction.

New Commands:

• /checkpoint <name>: Create a labeled milestone.
• /revert [name]: Restore a specific state (includes an interactive selection UI if no name is provided).
• /undo: Instant one-step rollback of the last turn.

Related Issues

Closes #17967

How to Validate

1. Setup: Enable checkpointing in settings.json ("general": { "checkpointing": { "enabled": true } }).
2. Manual Checkpoint: Run /checkpoint stable-start.
3. Modification: Use the AI to modify several files across different directories.
4. Revert UI: Run /revert (no arguments) and use the arrow keys to select stable-start.
5. Verification: Confirm all files have returned to their original state and the chat history has been truncated correctly.
6. Undo Test: Perform a file edit, then run /undo to verify the instant rollback.

Pre-Merge Checklist

• Updated relevant documentation (docs/cli/checkpointing.md)
• Added/updated tests (packages/core/src/utils/checkpointUtils.test.ts, etc.)
• Validated on MacOS

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello @AasheeshLikePanner, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a robust session management system to the CLI, allowing users to save, restore, and undo changes to their project and conversation history. By leveraging a shadow Git repository for file state and integrating conversation history, it provides a powerful mechanism for developers to manage their interactive coding sessions, recover from errors, and explore different solutions with confidence.

Highlights

• New CLI Commands: Introduced three new commands: '/checkpoint' to create named snapshots of the current file state and conversation history, '/revert' to restore the project and conversation to a specific checkpoint, and '/undo' to revert to the most recent checkpoint and then remove it.
• Automatic Checkpointing: Implemented automatic checkpointing before each user prompt within the Gemini stream, ensuring that a recoverable state is saved at critical interaction points.
• Enhanced Git Service Robustness: The GitService now includes an initialization flag and an ensureInitialized method, preventing redundant initialization and guaranteeing that all Git operations are performed only after the shadow repository is properly set up.
• UI and Command Context Integration: Updated various UI components and hooks, including AppContainer.tsx and slashCommandProcessor.ts, to properly pass and access the current conversation history, enabling the new checkpointing and reversion functionalities.
• Checkpoint Utility Improvements: Added a new createManualCheckpoint utility function in @google/gemini-cli-core to standardize the process of creating file and history snapshots, and refined the ToolCallData schema to support optional names and tool calls for greater flexibility.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a robust checkpointing and session reversion system with /checkpoint, /revert, and /undo commands, which is a great addition for managing session state. The implementation, including the use of a shadow Git repository and auto-checkpointing, is well-structured. My review identified one high-severity issue where a failure to create a file snapshot during checkpointing could silently fall back to an older state, potentially leading to user confusion or data loss upon reversion. I've provided a suggestion to address this by ensuring failures are propagated to the user.

[Adib234]

Closing because of closed issue #17967