Metadata-Version: 2.4
Name: checkpoint-agent
Version: 1.0.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"

# Code Checkpoint

**Code 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** (`checkpoints/Checkpoint_<email>.md`) — A "While You Were Gone" briefing per developer, updated on every push. Shows exactly what changed since their last commit.
- **Commit Checkpoints** — Per-commit summaries stored in `checkpoints/`, used as the source material for catchups.
- **PR Summaries** — 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

# Run the interactive setup wizard
checkpoint --init

# Install the GitHub Actions workflow
checkpoint --install-ci

# Generate the master context (first time)
checkpoint --onboard
```

The setup wizard will ask for your LLM provider, model, and API key, then write `.checkpoint.yaml` and `.env`.

## Commands

```bash
# Setup
checkpoint --init                        # Interactive setup wizard
checkpoint --install-ci                  # Install GitHub Actions workflow
checkpoint --config                      # Show current configuration
checkpoint --install-hook                # Install local git post-commit hook (optional)
checkpoint --uninstall                   # Remove git hook

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

# Info
checkpoint --stats                       # Show checkpoint statistics
```

## GitHub Actions (recommended)

Run `checkpoint --install-ci` to install the workflow, 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`, `checkpoints/Checkpoint_*.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: 2000

repository:
  output_dir: ./checkpoints
  master_context_file: MASTER_CONTEXT.md

features:
  git_hook: false            # Local hook (GitHub Actions is preferred)
  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 prompts (CheckpointGenerator, CatchupGenerator, etc.)
├── graph.py             # Commit analysis pipeline
├── llm.py               # LiteLLM configuration
├── config.py            # Pydantic config models
├── storage.py           # Checkpoint file I/O
├── git_utils.py         # GitPython wrappers
├── mermaid_utils.py     # AST-based diagram generation (Python)
├── llm_diagrams.py      # LLM-based diagram generation (other languages)
├── setup_wizard.py      # Interactive setup wizard
├── git_hook_installer.py
└── 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
