/gaia-resume

user-facing
Category:
Getting Started
Lifecycle phase:
Any
Arguments:
[workflow-name]

What it does

/gaia-resume reconnects you with an interrupted workflow. GAIA automatically saves checkpoints as you work -- if a session is interrupted (network drop, timeout, or you simply close the terminal), this command finds the checkpoint, verifies file integrity, and hands you back to the workflow where it left off.

When to use it

  • A session was interrupted mid-workflow (for example, halfway through /gaia-dev-story or /gaia-create-prd).
  • You want to see which workflows have active checkpoints before deciding whether to resume or start fresh.

Do not use this command to start a new workflow -- invoke the specific command directly instead.

Prerequisites

  • At least one checkpoint must exist. Checkpoints are stored under _memory/checkpoints/. If no checkpoints exist, the command reports "No active workflows to resume" and exits.

How to invoke

/gaia-resume

Lists all active checkpoints and lets you pick one.

/gaia-resume dev-story-E3-S7

Jumps directly to the named checkpoint without listing.

What it does step by step

  1. List active checkpoints Scans _memory/checkpoints/ for checkpoint files. Archived checkpoints (under completed/) are excluded. Shows each checkpoint's workflow name, step number, and timestamp.
  2. Select a checkpoint If only one exists, asks you to confirm. If multiple exist, asks you to pick by number. If you provided a workflow name as an argument, skips to that checkpoint directly.
  3. Read the checkpoint Loads the checkpoint data: which workflow was running, which step it reached, what variables were set, and which files were produced.
  4. Validate file integrity Checks that all files recorded in the checkpoint still exist on disk and have not been modified since the checkpoint was written (using SHA-256 checksums). Three outcomes:
    • Clean -- all files match. Proceeds automatically.
    • Drift -- one or more files changed since the checkpoint. Shows you the affected files and asks: Proceed, Start fresh, or Review the changes.
    • Missing -- one or more files were deleted. Same three-option prompt.
  5. Hand off to the workflow Restores all saved variables and tells you to re-invoke the original command. The workflow picks up at the next step after the checkpoint -- completed work is not re-run.

Inputs

Input Source Description
workflow-name Command argument (optional) The name of the checkpoint to resume (e.g., dev-story-E3-S7). If omitted, lists all active checkpoints.
Checkpoint files _memory/checkpoints/ Automatically written by GAIA workflows during execution.

Outputs

This command does not create files. It reads existing checkpoints and hands you back to the interrupted workflow, which produces its own outputs.

Example session

> /gaia-resume

Active checkpoints:

1. dev-story-E3-S7 -- step 7 (green_complete) at 2026-05-06T13:45:22Z
2. create-prd -- step 4 at 2026-05-06T09:12:05Z

Which checkpoint to resume? (1-2)
> 1

Reading checkpoint dev-story-E3-S7...
Validating file integrity...
  All file checksums match -- safe to resume.

Resuming dev-story at step 8.

Re-invoke: /gaia-dev-story E3-S7
  (The workflow will skip to step 8 automatically.)

With file drift

> /gaia-resume dev-story-E3-S7

Reading checkpoint dev-story-E3-S7...
Validating file integrity...

  1 changed file since checkpoint:
  - src/routes/auth.ts -- DRIFT (sha256 does not match)

Choose how to recover:
  [Proceed]      Resume anyway -- changed files will be re-processed.
  [Start fresh]  Discard and re-run /gaia-dev-story from the beginning.
  [Review]       Show the diff for each changed file.

> review

  src/routes/auth.ts:
    + import { validateToken } from './utils/jwt';
    (3 lines added, 1 removed)

  [Proceed] [Start fresh] [Review]
> proceed

Resuming dev-story at step 8.

What to run next

Re-invoke the command that was interrupted. /gaia-resume tells you the exact command to run (for example, /gaia-dev-story E3-S7).

Troubleshooting

"No active workflows to resume"

No checkpoint files were found under _memory/checkpoints/. Either no workflow has been interrupted, or the checkpoint files were deleted. Start a new workflow with the appropriate command.

"Corrupted checkpoint"

The checkpoint file could not be parsed. This can happen if a crash occurred during the checkpoint write. Re-run the original workflow from the beginning, or select an earlier checkpoint if one is available.

Files changed since the checkpoint

Someone (or another process) modified files that the workflow had already produced. Choose Review to see exactly what changed, then decide whether to proceed or start fresh.