Metadata-Version: 2.4
Name: checkpoint-agent
Version: 1.2.4
Summary: AI-powered developer onboarding and context recovery system for git repositories
Author-email: Gagan N Bangaragiri <gagan.bangaragiri@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/BurntDosa/Checkpoint
Project-URL: Documentation, https://github.com/BurntDosa/Checkpoint#readme
Project-URL: Repository, https://github.com/BurntDosa/Checkpoint
Project-URL: Issues, https://github.com/BurntDosa/Checkpoint/issues
Keywords: git,ai,onboarding,documentation,llm,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: litellm>=1.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

<p align="center">
  <img src="assets/banner.png" alt="Checkpoint" />
</p>

# 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.

![Python](https://img.shields.io/badge/Python-3.10%2B-blue)
![License](https://img.shields.io/badge/License-MIT-green)

## 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

```bash
pip install checkpoint-agent
```

## Quick Start

```bash
# 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

```bash
# 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`:

```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`:

```env
MISTRAL_API_KEY=...
# OPENAI_API_KEY=...
# ANTHROPIC_API_KEY=...
```

## Supported LLM Providers

Any provider supported by [LiteLLM](https://github.com/BerriAI/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

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

## License

MIT
