Checkpoint

Checkpoint is an AI-powered developer onboarding and context recovery tool for git repositories. It automatically generates living documentation that evolves with every commit, so returning developers can get up to speed instantly and new developers can understand the codebase without reading every file.

What it does

• Master Context (MASTER_CONTEXT.md) -- A full architectural overview of the codebase, regenerated on every PR merge. Perfect for new developers.
• Personalized Catchup (catchups/Catchup_<email>.md) -- A "While You Were Gone" briefing per developer, updated on every push. Shows exactly what changed since their last commit. When a developer commits, their catchup file is automatically deleted (they're caught up).
• Commit Checkpoints (checkpoints/Checkpoint-*.md) -- Per-commit summaries used as source material for catchups.
• PR Summaries (checkpoints/PR-*.md) -- A consolidated summary for each pull request.

All generation runs via GitHub Actions -- no local hooks required.

Installation

pip install checkpoint-agent

Quick Start

# Navigate to your git repository
cd /path/to/your/repo

# Install the GitHub Actions workflow + create default config + boilerplate MASTER_CONTEXT.md
checkpoint --init

Then add your LLM API key as a GitHub Secret (e.g. MISTRAL_API_KEY) and push -- checkpoints will be generated automatically.

Commands

# Setup
checkpoint --init                        # Install GitHub Actions workflow + create config
checkpoint --config                      # Show current configuration
checkpoint --install-hook                # Install git post-commit hook
checkpoint --uninstall                   # Remove git hook

# Generation (also runs automatically via GitHub Actions)
checkpoint --onboard                     # Generate MASTER_CONTEXT.md
checkpoint --catchup                     # Generate your personal catchup
checkpoint --catchup user@email.com      # Generate catchup for a specific user
checkpoint --catchup-all                 # Generate catchups for all active developers

# Commit analysis
checkpoint --commit <hash>               # Analyze a specific commit
checkpoint --commit <hash> --dry-run     # Preview without saving

# PR summary (used by CI)
checkpoint --pr <number> <base> <head> <title>

# Info
checkpoint --stats                       # Show checkpoint statistics

GitHub Actions (recommended)

Run checkpoint --init to install the workflow and create the default config, then add your LLM API key as a GitHub secret (e.g. MISTRAL_API_KEY).

The workflow runs three jobs automatically:

Configuration

.checkpoint.yaml:

llm:
  provider: mistral          # openai, anthropic, mistral, ollama, google, azure
  model: mistral-medium-2508
  temperature: 0.7
  max_tokens: 8000

repository:
  output_dir: ./checkpoints
  master_context_file: MASTER_CONTEXT.md
  ignore_patterns:
    - node_modules
    - venv
    - .git
  file_patterns:
    - "**/*.py"
    - "**/*.js"
    - "**/*.ts"

features:
  diagrams: true             # Generate Mermaid diagrams in master context
  auto_catchup: false

languages:
  - Python

API keys go in .env:

MISTRAL_API_KEY=...
# OPENAI_API_KEY=...
# ANTHROPIC_API_KEY=...

Supported LLM Providers

Any provider supported by LiteLLM: OpenAI, Anthropic, Mistral, Google Gemini, Azure, Ollama (local), and more. Set provider and model in .checkpoint.yaml.

Project Structure

checkpoint_agent/
├── __main__.py          # CLI entry point
├── agents.py            # LLM-based generator classes (Checkpoint, Catchup, MasterContext, PR)
├── graph.py             # Commit analysis pipeline (LangGraph)
├── llm.py               # LiteLLM configuration + provider auto-detection
├── config.py            # Pydantic config models (.checkpoint.yaml schema)
├── storage.py           # Checkpoint/catchup file I/O with per-author stable filenames
├── git_utils.py         # GitPython wrappers (diffs, metadata, author detection)
├── mermaid_utils.py     # AST-based Mermaid diagram generation (Python)
├── llm_diagrams.py      # LLM-based diagram generation (non-Python languages)
├── setup_wizard.py      # Config display utilities
├── git_hook_installer.py # Post-commit hook install/uninstall
└── templates/
    └── checkpoint.yml   # Bundled GitHub Actions workflow

Development

git clone https://github.com/BurntDosa/Checkpoint
cd Checkpoint
pip install -e ".[dev]"
pytest tests/

License

MIT