Introduction

Quick Start

Install the CLI, save a checkpoint of a git repository, and check it from a fresh session.

  1. Install

    bash
    pip install contextbridge-cli
contextbridge --help

    The package is contextbridge-cli on PyPI ↗; the command it installs is contextbridge.

  2. Initialize the repository

    bash
    cd your-repo
contextbridge init

    This creates a contextbridge/ folder (state.json, graph.json, sessions.json, HANDOFF.md) and, if it is missing, a .contextbridgeignore file.

  3. Run your tests through ContextBridge

    bash
    contextbridge run -- python3 -m unittest

    The command runs normally. ContextBridge records its exit code, duration, the last lines of output (secrets redacted) and the workspace state it ran against.

    text
    E1 `python3 -c print('ok')` -> PASSED (exit 0, 0.06s)

  4. Save a checkpoint

    bash
    contextbridge save --objective "Add login" --next "Write the logout handler"

    A checkpoint stores the branch, the HEAD commit, every uncommitted file with its SHA-256, and a fingerprint of the whole workspace. It also rewrites HANDOFF.md.

  5. Check it from a fresh session

    bash
    contextbridge resume --check
    text
    ## Resume safety gate: READY
No conflicts detected. Proceed with the Next action and keep verifying with tests.

No drift: workspace matches the checkpoint.
[exit 0]

    Edit a file and run it again. The verdict changes, and the exit code with it:

    text
    ## Resume safety gate: REVIEW_REQUIRED
Do not edit yet. Inspect each item below, reconcile it with the code or the user, then proceed.

[WARN ] app.py: new uncommitted change since checkpoint
[WARN ] no passing test run matches the current workspace state; re-run tests before trusting 'done'
[exit 1]

    contextbridge resume (without --check) prints the same gate result followed by the full handoff, ready to paste into a new session.

Where to go next