AI-powered developer onboarding and context recovery system for git repositories
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Project description
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:
| Trigger | Job | Output |
|---|---|---|
| Push to any branch | Generate commit checkpoints + catchups for all developers | checkpoints/Checkpoint-*.md, catchups/Catchup_*.md |
| PR opened/updated | Generate per-commit checkpoints + PR summary | checkpoints/PR-*.md |
| PR merged to main | Regenerate master context | MASTER_CONTEXT.md |
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
Project details
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file checkpoint_agent-1.2.5.tar.gz.
File metadata
- Download URL: checkpoint_agent-1.2.5.tar.gz
- Upload date:
- Size: 33.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
453daf8f7d47c69c19cd897ff9f3b037a026414f27a44680a26767982095ad33
|
|
| MD5 |
dbec8c6bc3c88a1ef1e28a64eaac26f8
|
|
| BLAKE2b-256 |
bca6ce67aeb1b2db482202913b14839026492069a68903d8f2cc7ef4891e7df9
|
Provenance
The following attestation bundles were made for checkpoint_agent-1.2.5.tar.gz:
Publisher:
publish.yml on BurntDosa/Checkpoint
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
checkpoint_agent-1.2.5.tar.gz -
Subject digest:
453daf8f7d47c69c19cd897ff9f3b037a026414f27a44680a26767982095ad33 - Sigstore transparency entry: 1101728318
- Sigstore integration time:
-
Permalink:
BurntDosa/Checkpoint@e28ada9e3af44ecd43c5a394d8522c336c10e9d8 -
Branch / Tag:
refs/tags/v1.2.5 - Owner: https://github.com/BurntDosa
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@e28ada9e3af44ecd43c5a394d8522c336c10e9d8 -
Trigger Event:
release
-
Statement type:
File details
Details for the file checkpoint_agent-1.2.5-py3-none-any.whl.
File metadata
- Download URL: checkpoint_agent-1.2.5-py3-none-any.whl
- Upload date:
- Size: 35.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0f6eeedba9bdfc6178b7a1a00793c7c405c6357c2bf7703b9a7804860c106534
|
|
| MD5 |
8e691a641b81fae48de86e0835c46317
|
|
| BLAKE2b-256 |
4799b06a580ffd7fc79c5888f0ae4ba9e3030cfdcd190926105c56125ecea0da
|
Provenance
The following attestation bundles were made for checkpoint_agent-1.2.5-py3-none-any.whl:
Publisher:
publish.yml on BurntDosa/Checkpoint
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
checkpoint_agent-1.2.5-py3-none-any.whl -
Subject digest:
0f6eeedba9bdfc6178b7a1a00793c7c405c6357c2bf7703b9a7804860c106534 - Sigstore transparency entry: 1101728324
- Sigstore integration time:
-
Permalink:
BurntDosa/Checkpoint@e28ada9e3af44ecd43c5a394d8522c336c10e9d8 -
Branch / Tag:
refs/tags/v1.2.5 - Owner: https://github.com/BurntDosa
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@e28ada9e3af44ecd43c5a394d8522c336c10e9d8 -
Trigger Event:
release
-
Statement type:
