ContextOS / Checkpoint

ContextOS is repo-native continuity infrastructure for AI-assisted software engineering. Checkpoint is the local CLI that captures, updates, and projects that context into the next AI coding tool.

Plan in Claude -> Code in Codex -> Debug in Claude Code -> Delegate to Antigravity -> Resume anywhere

Checkpoint is not another coding agent. It is the continuity layer beneath coding agents: readable Markdown memory, durable task files, durable handoffs, and agent-specific continuation packs.

Install | Quickstart | Commands | How It Works | Scope | Contributing

Why Checkpoint?

AI coding sessions are powerful, but continuity is fragile. Important context lives in chat history, one tool's private memory, or a local scratch note that the next agent cannot see.

Checkpoint gives a repository an explicit continuity layer:

• Human-readable project memory in .contextos/
• User preferences in ~/.contextos/about-me.md
• Durable active tasks, completed tasks, decisions, and handoffs
• Generated AGENTS.md and CLAUDE.md compatibility files
• Continuation packs for Codex, Claude, Claude Code, Antigravity, Cursor, or a generic agent
• Final redaction for common secret patterns before generated continuation output is printed or written

The goal is simple: make the next agent useful in the first minute.

Install

Install the packaged CLI:

pip install checkpoint-cli

Or install it as a uv tool:

uv tool install checkpoint-cli

Verify the command:

checkpoint --help

60-Second Quickstart

Run this inside any project that should remember its agent work:

checkpoint setup-user
checkpoint init
checkpoint status
checkpoint continue

Typical checkpoint status output:

                        ContextOS Status
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Item           ┃ Status                      ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Project root   │ /path/to/your/repo          │
│ .contextos     │ yes                         │
│ AGENTS.md      │ yes                         │
│ CLAUDE.md      │ yes                         │
│ Latest handoff │ yes                         │
│ Active tasks   │ 0                           │
└────────────────┴─────────────────────────────┘

checkpoint continue works even before the first task exists, so a new agent can start from project memory and leave the first durable handoff. After a task and handoff exist, it becomes the happy path: it detects the current agent when it can, reads the latest handoff and active task, and prints a Markdown continuation pack with inference provenance.

checkpoint continue --for claude-code

Example continuation pack shape:

# ContextOS Continuation Pack

## Target Agent

claude-code

## Current Task

TASK-001: Add checkpoint status

## Latest Handoff

Status: in_progress
Next: finish tests, then update README

## Continue From Here

Read AGENTS.md, inspect the active task file, run the focused tests, and keep
the handoff current before ending the session.

Write the pack to a file when you want to paste, attach, or inspect it later:

checkpoint continue --for codex --output /tmp/contextos-pack.md

Commands

Command	Use it when you want to
checkpoint setup-user	Create or update your user-level about-me.md
checkpoint init	Add ContextOS files to the current project
checkpoint status	See whether project memory, tasks, and handoffs exist
checkpoint continue	Generate the next-agent continuation pack
checkpoint resume	Build a lower-level resume pack for a specific agent
checkpoint handoff	Record a handoff between agents
checkpoint detect-agent	Show the agent Checkpoint inferred from the environment
checkpoint show <path>	Print a ContextOS file with safe path handling

Useful overrides:

checkpoint continue --from codex
checkpoint continue --from codex --for claude-code --task TASK-001
checkpoint resume --for cursor --task TASK-001
checkpoint handoff --from codex --to claude-code --task TASK-001 --status in_progress
checkpoint show .contextos/handoffs/latest.md

How It Works

Checkpoint uses a local Markdown store plus agent-specific projections:

repo/.contextos/
  context/
    architecture.md
    constraints.md
    decisions.md
    project-summary.md
  plans/
    active-plan.md
  tasks/
    active/
    completed/
  handoffs/
    latest.md
  agents/
  state/
    events.jsonl

~/.contextos/
  about-me.md

The projection flow is intentionally boring:

Local Markdown Store
  -> Checkpoint resolver
  -> Secret redaction
  -> Continuation Pack
  -> Next coding agent

Generated compatibility files make existing tools understand the same continuity layer:

AGENTS.md
CLAUDE.md

Everything important is plain text by design. You can review it, edit it, diff it, and commit the project memory that belongs in your repository.

Repository Layout

src/checkpoint_cli/        Python CLI implementation
tests/                     CLI and resolver tests
.github/                   CI, issue templates, PR template

This repository dogfoods ContextOS locally, but its own .contextos/ state is kept out of git so agent handoffs, working plans, and internal references do not become part of the public open-core history.

Public product information intentionally lives in this README and the release history. Longer internal docs, planning notes, launch notes, and reference material are kept local or in private repositories.

Current Scope

Built now:

• local-first Markdown memory
• checkpoint setup-user
• checkpoint init
• checkpoint status
• checkpoint resume
• checkpoint handoff
• checkpoint continue
• checkpoint detect-agent
• checkpoint show
• generated AGENTS.md and CLAUDE.md
• durable task files
• durable handoff files
• agent-specific continuation packs
• local event logging
• final redaction for generated continuation output
• Apache-2.0 open-core CLI and schema

Roadmap

Next likely open-core improvements:

• conflict-safe handoff history
• clearer CLI recovery messages
• more redaction coverage
• better examples for real agent-switch workflows
• richer command output without hiding the underlying Markdown files

Install From Source

git clone git@github.com:bkalyankumar/contextos.git
cd contextos
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Smoke test:

checkpoint --help
checkpoint status
checkpoint continue

Editable install from a source checkout remains the recommended path for contributors.

Verification

Run the full local health stack:

mypy src
ruff check .
pytest
vulture src tests

The same checks run in CI.

Privacy And Safety

• ContextOS is local-first by default.
• Generated handoffs must not contain secrets, API keys, tokens, or private credentials.
• checkpoint continue applies final redaction before printing or writing a continuation pack.
• Local event logs store command metadata, not generated continuation pack text.

Security reports should follow SECURITY.md, not public issues.

Contributing

Start with CONTRIBUTING.md. Good first contributions improve the local-first CLI, documentation, examples, tests, and failure messages.

Please keep the MVP boring and reliable:

• Prefer readable Markdown over hidden state.
• Prefer explicit files over magical behavior.
• Keep changes aligned with the local-first CLI and human-readable Markdown model.
• Update tests and docs with behavior changes.

License

Apache-2.0. See LICENSE.