Skip to main content

/checkpoint - Session & Agent Checkpoint Creation

Create checkpoints for session continuity and autonomous agent handoffs. Supports two modes:

  1. Session Mode (default): Timestamped markdown documents for git commit
  2. Agent Mode (--agent): Structured checkpoints for Ralph Wiggum autonomous agent loops (ADR-108)

Usage​

Session Mode (Default)​

# Create checkpoint with description
/checkpoint "Sprint 3 complete"

# Create checkpoint with auto-commit
/checkpoint "Feature implementation done" --auto-commit

# Create checkpoint without git commit
/checkpoint "WIP snapshot" --no-commit

# Include submodule updates
/checkpoint "Multi-repo sync" --with-submodules

# Project-scoped checkpoint (ADR-159)
/checkpoint "Customer milestone" --project CUST-avivatec-fpa

Agent Mode (ADR-108)​

# Create agent checkpoint for current task
/checkpoint --agent --task-id H.8.1.8

# Create checkpoint with completed items
/checkpoint --agent --task-id A.9.1.3 --completed "API endpoint" "Unit tests"

# Create checkpoint with pending items
/checkpoint --agent --task-id B.4.2 --pending "UI integration" --focus "Button component"

# Create checkpoint with explicit phase
/checkpoint --agent --task-id H.8.5.4 --phase implementing

# Project-scoped agent checkpoint (ADR-159)
/checkpoint --agent --task-id H.8.1.8 --project PILOT

# View latest checkpoint for a task
/checkpoint --agent --task-id H.8.1.8 --show

# List checkpoint history for a task
/checkpoint --agent --task-id H.8.1.8 --history

System Prompt​

System Prompt​

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

  1. IMMEDIATELY execute - no questions, no explanations first
  2. ALWAYS show full output from script/tool execution
  3. ALWAYS provide summary after execution completes

DO NOT:

  • Say "I don't need to take action" - you ALWAYS execute when invoked
  • Ask for confirmation unless requires_confirmation: true in frontmatter
  • Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

You are executing the CODITECT checkpoint creation system.

Detect Mode:

  • If --agent flag is present → Agent Mode (Ralph Wiggum ADR-108)
  • Otherwise → Session Mode (default)

ADR-159 Project Scoping: When --project is provided (or auto-detected from $CODITECT_PROJECT or CWD), checkpoints are scoped to the project:

  • Session mode: checkpoint metadata includes project field
  • Agent mode: checkpoints stored under project-specific subdirectory
from scripts.core.scope import resolve_scope
scope = resolve_scope()  # Auto-detects from CWD / $CODITECT_PROJECT
# scope.project = "PILOT" or "CUST-avivatec-fpa" etc.

Session Mode (Default)​

Storage Location:

  • Checkpoints: context-storage/checkpoints/
  • Project-scoped: context-storage/checkpoints/{project}/
  • Format: YYYY-MM-DDTHH-MM-SSZ-{description}.md

Checkpoint Contents:

  1. Session summary and work completed
  2. Git status and recent commits
  3. Updated TASKLIST references
  4. Next steps and context for continuation
  5. Optional: Submodule pointer updates
  6. Dashboard refresh: Phase 1+2 for dashboard-enabled projects (ADR-170)

Execute the checkpoint creation script:

python3 scripts/create-checkpoint.py "$DESCRIPTION" $ARGS

For multi-submodule repositories:

python3 scripts/checkpoint-with-submodules.py "$DESCRIPTION" $ARGS

Agent Mode (--agent flag)​

Storage Location:

  • Checkpoints: ~/PROJECTS/.coditect-data/checkpoints/{task_id}/
  • Project-scoped: ~/PROJECTS/.coditect-data/checkpoints/{project}/{task_id}/
  • Format: JSON with integrity hash (SHA-256)

Checkpoint Contents (ADR-108):

  1. Metadata: checkpoint_id, task_id, agent_id, iteration, timestamp
  2. Execution State: phase, completed/pending/blocked items, current_focus
  3. Context Summary: key_decisions, assumptions, constraints, dependencies
  4. Metrics: tokens_consumed, tools_invoked, files_modified, test_status
  5. Recovery Info: last_successful_state, rollback_instructions, continuation_prompt
  6. Compliance: event_log_ref, hash, signature, retention_policy

Execute the agent checkpoint script:

python3 scripts/core/checkpoint-command.py \
  --task-id "$TASK_ID" \
  --agent-id "claude-$(date +%Y%m%d-%H%M%S)" \
  --phase "$PHASE" \
  --completed "$COMPLETED_ITEMS" \
  --pending "$PENDING_ITEMS" \
  --focus "$CURRENT_FOCUS" \
  --project "$PROJECT"

Agent Checkpoint Actions:

  • --show: Display latest checkpoint for task
  • --history: List checkpoint history (newest first)
  • --resume: Generate continuation prompt from latest checkpoint

Options​

Session Mode Options​

OptionDescription
DESCRIPTIONRequired. Sprint/work description (max 200 chars)
--auto-commitAutomatically commit checkpoint to git
--no-commitCreate checkpoint file without git commit
--with-submodulesUse checkpoint-with-submodules.py for multi-repo
--repo-root PATHCustom repository root directory
--project IDProject scope for checkpoint (ADR-159). Auto-detected from CWD if not set.

Agent Mode Options​

OptionDescription
--agentEnable agent mode (ADR-108 Ralph Wiggum)
--task-id IDRequired. Task identifier (e.g., H.8.1.8)
--agent-id IDOptional. Agent identifier (auto-generated if not provided)
--iteration NLoop iteration number (default: auto-increment)
--phase PHASEExecution phase: planning, implementing, testing, reviewing, handoff, complete
--completed ITEM...Items completed in this iteration
--pending ITEM...Items still pending
--blocked ITEM...Items blocked by dependencies
--focus ITEMCurrent work focus
--decision TEXTKey decision made (can specify multiple)
--showDisplay latest checkpoint for task
--historyList checkpoint history
--resumeGenerate continuation prompt from latest checkpoint
--project IDProject scope for checkpoint (ADR-159). Auto-detected from CWD if not set.

Examples​

Basic Checkpoint​

/checkpoint "Implemented user authentication"

Result: Creates timestamped checkpoint in context-storage/checkpoints/

Auto-Commit Checkpoint​

/checkpoint "Sprint 3 complete" --auto-commit

Result: Creates checkpoint AND commits to git with standard message

Multi-Submodule Checkpoint​

/checkpoint "Cross-repo sync" --with-submodules

Result: Commits all modified submodules, updates parent repo, creates audit trail

WIP Snapshot​

/checkpoint "WIP: halfway through refactoring" --no-commit

Result: Creates checkpoint file only (useful for temporary snapshots)

Checkpoint Document Format​

# Session Checkpoint: {timestamp}

## Sprint: {description}

## Work Completed
- [Extracted from git diff and status]

## Git Status
- Branch: main
- Recent commits: [list]
- Uncommitted changes: [list]

## Updated Files
- [List of modified files with summary]

## Next Steps
1. [Auto-extracted from context]
2. [Pending tasks from TASKLIST]

## Context for Next Session
- Key decisions made: [list]
- Important files touched: [list]
- Dependencies added: [list]

---
Generated: {timestamp}
Script: create-checkpoint.py
Framework: CODITECT

Workflow​

# End of session workflow
/export                            # Export conversation
/cx                                # Process and index
/checkpoint "Session work" --auto-commit  # Create checkpoint

Before next session:

# Resume from checkpoint
cat context-storage/checkpoints/$(ls -t context-storage/checkpoints/ | head -1)

Integration​

Works with:

  • /export - Export session before checkpoint
  • /cx - Process exports into unified store
  • /git-sync - Full repository synchronization
  • /commit - Simple git commit workflow

Scripts:

  • scripts/create-checkpoint.py - Single repo checkpoints
  • scripts/checkpoint-with-submodules.py - Multi-submodule checkpoints

Storage:

  • Checkpoints: context-storage/checkpoints/
  • Audit logs: context-storage/audit-logs/ (for submodule checkpoints)

Safety Features​

  • Input validation (no shell injection)
  • Git state backup before operations
  • Automatic rollback on failure
  • Network retry logic for push operations
  • Detailed audit trail for multi-repo checkpoints

Success Output​

When checkpoint creation completes:

✅ COMMAND COMPLETE: /checkpoint
Description: "<description>"
File: context-storage/checkpoints/YYYY-MM-DDTHH-MM-SSZ-description.md
Git: <committed|not-committed>
Submodules: <updated|skipped>

Completion Checklist​

Before marking complete:

  • Checkpoint file created
  • Git status captured
  • Next steps documented
  • Git commit (if --auto-commit)

Failure Indicators​

This command has FAILED if:

  • ❌ Checkpoint directory not writable
  • ❌ Git repository not found
  • ❌ Script execution error
  • ❌ Submodule sync failed (if --with-submodules)

When NOT to Use​

Do NOT use when:

  • No significant work to checkpoint
  • Already created checkpoint recently
  • Need quick save (use git stash)

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Vague descriptionHard to find laterUse descriptive checkpoint names
Skip at session endLost contextAlways checkpoint before stopping
Forget --with-submodulesIncomplete stateUse for multi-repo work

Principles​

This command embodies:

  • #3 Complete Execution - Full state capture
  • #9 Based on Facts - Git-based evidence
  • #6 Clear, Understandable - Structured checkpoint format

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Scripts: scripts/create-checkpoint.py, scripts/checkpoint-with-submodules.py, scripts/core/checkpoint-command.py ADR References: ADR-108 (Agent Checkpoints), ADR-159 (Multi-Tenant Command Architecture), ADR-170 (Dashboard Refresh) Version: 2.2.0 Last Updated: 2026-02-16

Changelog:

  • v2.2.0 - ADR-170: Dashboard Phase 1+2 refresh on checkpoint for dashboard-enabled projects (session end = fresh dashboard for next session)
  • v2.1.0 - ADR-159: Project-scoped checkpoints, agent mode enhancements