How gstack Continuous Checkpoint Mode Auto-Commits Work

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:

gstack-config set checkpoint_mode continuous

Optionally enable automatic pushing to remote repositories:

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, 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. This block instructs the runtime to create commits upon four specific conditions:

New intentional files — When you explicitly stage files using git add <file> 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: <concise description of what changed>

[gstack-context]
Decisions: <key choices made this step>
Remaining: <what's left in the logical unit>
Tried: <failed approaches worth recording>
Skill: </skill-name-if-running>
[/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.
• 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.
• 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 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 <file>. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}