# How gstack Continuous Checkpoint Mode Auto-Commits Work > Understand how gstack continuous checkpoint mode auto-commits save your workflow context automatically. Learn about silent WIP commits for staged files, code units, bug fixes, and long commands. - Repository: [Garry Tan/gstack](https://github.com/garrytan/gstack) - Tags: internals - Published: 2026-05-15 --- **gstack's continuous checkpoint mode automatically creates silent "WIP" commits whenever you stage intentional files, complete logical code units with passing tests, fix verified bugs, or run long-running commands, storing workflow context in a structured format for later recovery or squashing.** The continuous checkpoint mode in `garrytan/gstack` eliminates manual commit interruptions during development by auto-committing work-in-progress snapshots based on specific runtime triggers. This feature is controlled by the `checkpoint_mode` configuration key and ensures you never lose context while maintaining atomic, reversible milestones throughout your coding session. ## Enabling Continuous Checkpoint Mode To activate auto-commits, set the configuration value using the gstack CLI: ```bash gstack-config set checkpoint_mode continuous ``` Optionally enable automatic pushing to remote repositories: ```bash gstack-config set checkpoint_push true ``` These values are injected into the runtime environment through the bash preamble resolver. In [`scripts/resolvers/preamble/generate-preamble-bash.ts`](https://github.com/garrytan/gstack/blob/main/scripts/resolvers/preamble/generate-preamble-bash.ts), the configuration store exports `CHECKPOINT_MODE` and `CHECKPOINT_PUSH` as environment variables that the skill runtime evaluates before executing commands. ## Auto-Commit Triggers in Continuous Mode When `CHECKPOINT_MODE` is set to `"continuous"`, the preamble includes a help block generated by `generateContinuousCheckpoint` in [`scripts/resolvers/preamble/generate-continuous-checkpoint.ts`](https://github.com/garrytan/gstack/blob/main/scripts/resolvers/preamble/generate-continuous-checkpoint.ts). This block instructs the runtime to create commits upon four specific conditions: **New intentional files** — When you explicitly stage files using `git add ` rather than `git add -A`, the runtime recognizes deliberate changes and queues a commit once tests pass. **Completed functions or modules** — When a logical unit of code is finished and its associated test suite succeeds, the runtime treats this boundary as a checkpoint worthy of preservation. **Verified bug-fixes** — After a previously failing test is repaired and the full suite passes, the runtime auto-commits the verified solution. **Before long-running commands** — Prior to executing install, build, or test commands that could take many seconds, the runtime creates a checkpoint to ensure you can recover from potential timeouts or failures. ## The WIP Commit Format Every auto-generated commit follows a strict template that embeds workflow metadata within the commit message: ``` WIP: [gstack-context] Decisions: Remaining: Tried: Skill: [/gstack-context] ``` The `generateContinuousCheckpoint` function provides the human-readable specification for this format, ensuring that the LLM runtime populates the `[gstack-context]` block with decisions made, remaining work, discarded approaches, and the active skill name. These commits are created silently without console output to maintain a smooth workflow. ## Safety Constraints and Push Behavior The continuous checkpoint implementation enforces strict safety guarantees to prevent repository pollution. **Only intentional files are staged** — the runtime never executes `git add -A` or commits untracked files automatically. Furthermore, **broken tests or half-finished edits are never committed**; the commit only finalizes after the test suite confirms success. Remote push behavior depends on the `CHECKPOINT_PUSH` configuration. When set to `"true"`, each WIP commit is pushed immediately to the remote. When `"false"` or unset, commits remain local until you explicitly push or invoke the shipping workflow. ## Integration with Context-Restore and Ship Skills The structured metadata in WIP commits enables powerful recovery and cleanup workflows. The `/context-restore` skill reads the `[gstack-context]` block from previous commits to reconstruct your mental state and decision history when resuming work. When you are ready to finalize your changes, the `/ship` skill **squashes** the entire series of WIP commits into clean, conventional commits that follow standard commit message formats, removing the temporary checkpoint markers before the final push. ## Summary - Continuous checkpoint mode is enabled via `gstack-config set checkpoint_mode continuous` and controlled through `CHECKPOINT_MODE` and `CHECKPOINT_PUSH` variables injected by [`generate-preamble-bash.ts`](https://github.com/garrytan/gstack/blob/main/generate-preamble-bash.ts). - Auto-commits trigger on intentional file staging, completed logical units with passing tests, verified bug fixes, and before long-running commands. - WIP commits follow a strict template with embedded `[gstack-context]` metadata generated according to the rules in [`generate-continuous-checkpoint.ts`](https://github.com/garrytan/gstack/blob/main/generate-continuous-checkpoint.ts). - The runtime never stages untracked files automatically or commits broken code, ensuring repository integrity. - Use `/context-restore` to recover workflow state from checkpoint metadata and `/ship` to squash WIP commits into production-ready history. ## Frequently Asked Questions ### How do I enable continuous checkpoint mode in gstack? Run `gstack-config set checkpoint_mode continuous` in your terminal. This updates the gstack configuration store, which [`scripts/resolvers/preamble/generate-preamble-bash.ts`](https://github.com/garrytan/gstack/blob/main/scripts/resolvers/preamble/generate-preamble-bash.ts) reads to inject the `CHECKPOINT_MODE` environment variable into the skill runtime. ### What prevents continuous checkpoint mode from committing broken code? The runtime only creates commits after the test suite passes and only stages files you explicitly added with `git add `. It never runs `git add -A` and never commits when tests are failing, ensuring that every WIP commit represents a working state. ### Does continuous checkpoint mode automatically push commits to the remote? Only if you enable it separately. Set `gstack-config set checkpoint_push true` to allow the runtime to push each WIP commit immediately. By default, commits remain local until you manually push or use the `/ship` skill, which squashes them into final commits before pushing. ### How do I convert WIP commits into clean final commits? Use the `/ship` skill, which automatically squashes the series of continuous checkpoint commits into conventional, well-formatted commits and removes the `[gstack-context]` metadata blocks before the final push to the remote repository.