feat: Adds checkpointing functionality using Git CLI commands #2896

evanliu048 · 2025-09-16T21:56:05Z

Issue #, if available:

Description of changes:
Introduce session-scoped checkpoints for the current repo. Q CLI now snapshots file changes into a shadow bare git repo and lets users list, expand, diff, and restore to any checkpoint. Errors are short and human-readable; empty diffs print “No differences.” The conversation history is also unwind when restoring a checkpoint

Commands

/checkpoint init — Manually enable checkpoints if not in a git repo.
- (Auto): If starting inside a git repo, checkpoints auto-enable (ephemeral, cleaned on session end).
/checkpoint list [--limit N] — Turn-level checkpoints with file stats.
/checkpoint expand <tag> — Show tool-level checkpoints under a turn, with “(+/~/-) files” badges.
/checkpoint diff <tag1> [tag2|HEAD]
- Prints header then diff, or “No differences.” if none.
- Unknown tags: Checkpoint with tag '' does not exist! Use /checkpoint list to see available checkpoints
/checkpoint restore [<tag>] [--hard]
- Default: revert tracked changes & deletions; do not delete files created after the checkpoint.
- --hard: make workspace exactly match the checkpoint; deletes tracked files created after it.
- If <tag> omitted, shows interactive picker.
/checkpoint clean — Delete session shadow repo.

Implementation (high-level)

Shadow storage: bare git repo under get_shadow_repo_dir(conversation_id), operating on --work-tree=..
Helper run_git(...) centralizes --git-dir/--work-tree and error handling.
File stats via git diff --name-status; treat R/C as modified; cache per-tag stats.
Previous-tag resolution for X and X.Y forms.
Soft vs hard restore wired through git checkout vs git reset --hard.

Examples

/checkpoint list
[0] 2025-09-18 14:00:00 - Initial checkpoint
[1] 2025-09-18 14:05:31 - add two_sum.py (+1 file)
[2] 2025-09-18 14:07:10 - add tests (modified 1)

/checkpoint expand 2
[2] 2025-09-18 14:07:10 - add tests
 └─ [2.1] fs_write: Add minimal test cases to two_sum.py (modified 1)

/checkpoint diff 2
Comparing current state with checkpoint [2]:
No differences.

/checkpoint restore 1 --hard
Restored checkpoint: 1

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Updates: - Only works if the user has git installed - Supports auto initialization if the user is in a git repo, manual if not - UI ported over from dedicated file tools implementation

Updates: - The clean subcommand will delete the shadow repo - The description for turn-level checkpoints is a truncated version of the user's last message

Updates: - Running the clean subcommand now properly deletes the entire shadow repo for both automatic and manual modes

Updates: - Users can now view diffs between checkpoints - Fixed tool-level checkpoint display handling

Updates: - Checkpoints now (hopefully) correctly display the correct turn-specific user message - Added slash command auto completion

…an-garre/git-checkpoints

dingfeli · 2025-09-24T00:16:49Z

crates/chat-cli/src/cli/chat/mod.rs

+                    String::new()
+                }
+                // Take manager out temporarily to avoid borrow conflicts
+                else if let Some(mut manager) = self.conversation.checkpoint_manager.take() {


Is there any invocation here that requires a mut self for manager? If not we can just do

else if let Some(manager) = self.conversation.checkpoint_manager.as_mut() { ... }

Thanks for the advise! I do change manager later (tools_in_turn += 1 and create_checkpoint also mutates internal state)

Also the take() approach is here because I need to access both manager (mutably) and self.conversation.history() (immutably) in the same scope. Using as_mut() would cause a borrowing conflict when calling self.conversation.history().clone() inside create_checkpoint().

crates/chat-cli/src/cli/chat/mod.rs

dingfeli · 2025-09-24T00:26:07Z

crates/chat-cli/src/cli/chat/mod.rs

+                            debug!("Failed to create tool checkpoint: {}", e);
+                            String::new()
+                        } else {
+                            manager.tools_in_turn += 1;


Do we ever increment this by more than one per turn? I see that we are resetting it to 0 every turn.
If that's the case this can just be a bool then?

Yes we do increase this value
It's used to generate unique checkpoint tags like "3.1", "3.2" for each tool within a turn
Multiple tools can be executed within a single turn.
We need to distinguish between different tool checkpoints in the same turn

kensave · 2025-09-25T17:36:08Z

crates/chat-cli/src/cli/chat/cli/checkpoint.rs

+impl CheckpointSubcommand {
+    pub async fn execute(self, os: &Os, session: &mut ChatSession) -> Result<ChatState, ChatError> {
+        // Check if in tangent mode - captures are disabled during tangent mode
+        if os


This is on me but we should have an experiment helper to query experiments in particular.

kensave · 2025-09-25T17:37:21Z

crates/chat-cli/src/cli/chat/cli/checkpoint.rs

+                session.stderr,
+                style::SetForegroundColor(Color::Yellow),
+                style::Print(
+                    "⚠️ Checkpoint is disabled while in tangent mode. Disable tangent mode with: q settings -d chat.enableTangentMode.\n\n"


Why disable checkpoint if tangent mode is enabled? I understand disabling it while in Tangent mode, but not following why we can't have both features enabled at same time.

crates/chat-cli/src/cli/chat/cli/experiment.rs

kensave · 2025-09-25T17:40:55Z

crates/chat-cli/src/cli/chat/conversation.rs

+    /// Restore conversation from a checkpoint's history snapshot
+    pub fn restore_to_checkpoint(&mut self, checkpoint: &Checkpoint) -> Result<(), eyre::Report> {
+        // 1. Restore history from snapshot
+        self.history = checkpoint.history_snapshot.clone();


Just curious? Can a checkpoint corrupt conversation history by any means? Like a tool use without tool results and so on?

The checkpoint is created after the tool executes successfully and in handle_response, so that should be fine. Thanks for the callout — we can test it more thoroughly during the bug bash

kkashilk · 2025-09-26T18:41:14Z

crates/chat-cli/src/cli/chat/cli/checkpoint.rs

+                session.stderr,
+                style::SetForegroundColor(Color::Yellow),
+                style::Print(
+                    "⚠️ Checkpoint is disabled while in tangent mode. Disable tangent mode with: q settings -d chat.enableTangentMode.\n\n"


I think user just needs to exit tangent mode, right? Doesn't need to disable it completely?

yes. thanks for catching this. I will change the word here

* (in progress) Implement checkpointing using git CLI commands * feat: Add new checkpointing functionality using git CLI Updates: - Only works if the user has git installed - Supports auto initialization if the user is in a git repo, manual if not - UI ported over from dedicated file tools implementation * feat: Add user message for turn-level checkpoints, clean command Updates: - The clean subcommand will delete the shadow repo - The description for turn-level checkpoints is a truncated version of the user's last message * fix: Fix shadow repo deletion logic Updates: - Running the clean subcommand now properly deletes the entire shadow repo for both automatic and manual modes * chore: Run formatter and fix clippy warnings * feat: Add checkpoint diff Updates: - Users can now view diffs between checkpoints - Fixed tool-level checkpoint display handling * fix: Fix last messsage handling for checkpoints Updates: - Checkpoints now (hopefully) correctly display the correct turn-specific user message - Added slash command auto completion * fix: Fix commit message handling again * chore: Run formatter * Removed old comment * define a global capture dirctory * revise the capture path * fix cpature clean bug * add a clean all flag * add auto drop method for capture feature * support file details when expand * add the file summary when list and expand * revise structure and print no diff msg * delete all flag, add summry when fs read * refactor code * revise ui * add capture into experiement * clippy * rename to checkpoint * reverse false renaming * recover history * disable tangent mode in checkpoint * fix cr * nit: keep checkpoint name * allow both tangent & checkpoint enabled * ci --------- Co-authored-by: kiran-garre <[email protected]>

kiran-garre and others added 16 commits August 13, 2025 16:48

(in progress) Implement checkpointing using git CLI commands

39ade9d

feat: Add new checkpointing functionality using git CLI

c5c033f

Updates: - Only works if the user has git installed - Supports auto initialization if the user is in a git repo, manual if not - UI ported over from dedicated file tools implementation

feat: Add user message for turn-level checkpoints, clean command

1760839

Updates: - The clean subcommand will delete the shadow repo - The description for turn-level checkpoints is a truncated version of the user's last message

fix: Fix shadow repo deletion logic

5a27533

Updates: - Running the clean subcommand now properly deletes the entire shadow repo for both automatic and manual modes

chore: Run formatter and fix clippy warnings

643912d

feat: Add checkpoint diff

7f0cba9

Updates: - Users can now view diffs between checkpoints - Fixed tool-level checkpoint display handling

fix: Fix last messsage handling for checkpoints

30b5a95

Updates: - Checkpoints now (hopefully) correctly display the correct turn-specific user message - Added slash command auto completion

fix: Fix commit message handling again

8eb341a

Merge commit

566f0c9

Fix merge conflicts

e38c1f8

chore: Run formatter

eae59d5

Removed old comment

bc23993

Merge branch 'main' of github.com:aws/amazon-q-developer-cli into kir…

b709854

…an-garre/git-checkpoints

define a global capture dirctory

a97f3f8

revise the capture path

25645b1

fix cpature clean bug

0f74051

evanliu048 marked this pull request as draft September 16, 2025 21:56

evanliu048 added 11 commits September 16, 2025 15:35

add a clean all flag

a9801c0

Merge branch 'main' into snapshot_revise

13a1385

add auto drop method for capture feature

e1a3cfe

support file details when expand

a44f814

add the file summary when list and expand

3829fa2

revise structure and print no diff msg

0a6e993

delete all flag, add summry when fs read

58ea878

refactor code

f1b76f8

revise ui

e2c3590

add capture into experiement

f1f0816

clippy

1c366e4

evanliu048 marked this pull request as ready for review September 22, 2025 22:51

evanliu048 changed the title ~~feat: Adds checkpointing/Capture functionality using Git CLI commands~~ feat: Adds checkpointing functionality using Git CLI commands Sep 22, 2025

evanliu048 added 2 commits September 22, 2025 16:32

rename to checkpoint

594305b

reverse false renaming

e9f30d9

dingfeli reviewed Sep 24, 2025

View reviewed changes

evanliu048 added 4 commits September 24, 2025 13:43

recover history

9211e75

disable tangent mode in checkpoint

e16541e

fix cr

049ea08

nit: keep checkpoint name

e479178

kensave reviewed Sep 25, 2025

View reviewed changes

allow both tangent & checkpoint enabled

3601482

kensave approved these changes Sep 25, 2025

View reviewed changes

evanliu048 added 2 commits September 25, 2025 15:41

Merge branch 'main' into snapshot_revise

163ed21

ci

a313dfd

brandonskiser approved these changes Sep 25, 2025

View reviewed changes

kensave merged commit 1f4f96f into main Sep 25, 2025
14 of 15 checks passed

kensave deleted the snapshot_revise branch September 25, 2025 23:12

kkashilk reviewed Sep 26, 2025

View reviewed changes

feat: Adds checkpointing functionality using Git CLI commands #2896

feat: Adds checkpointing functionality using Git CLI commands #2896

Uh oh!

Conversation

evanliu048 commented Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

evanliu048 Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

evanliu048 commented Sep 16, 2025 •

edited

Loading

evanliu048 Sep 24, 2025 •

edited

Loading