checkpoint-cli 0.1.0

Local-first CLI for ContextOS repo-native AI engineering continuity

ContextOS / Checkpoint

ContextOS is repo-native continuity infrastructure for AI-assisted software engineering. Checkpoint is the local CLI that creates, 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.

Status

Checkpoint is pre-1.0 and ready for early open-source contributors. The current release proves the local-first workflow; cloud sync, dashboards, IDE extensions, vector search, and hosted agent runtimes are intentionally out of scope.

What It Does

• Creates project memory in .contextos/
• Creates user memory in ~/.contextos/about-me.md
• Generates AGENTS.md and CLAUDE.md compatibility files
• Tracks active tasks, completed tasks, decisions, and handoffs
• Emits Markdown continuation packs for Codex, Claude, Claude Code, Antigravity, Cursor, or a generic agent
• Redacts common secret patterns before generated continuation output
• Logs local continuity events without storing generated pack contents

Install From Source

git clone [e-mail]: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

A packaged installer is not published yet. Until then, editable install from a source checkout is the supported path for contributors and early testers.

First Run In A Project

checkpoint setup-user
checkpoint init
checkpoint status
checkpoint continue

checkpoint continue is 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.

Useful overrides:

checkpoint continue --from claude
checkpoint continue --from codex --for claude-code --task TASK-001
checkpoint continue --output /tmp/contextos-pack.md
checkpoint detect-agent

Lower-level primitives remain available when you want direct control:

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

Repository Layout

src/checkpoint_cli/        Python CLI implementation
tests/                     CLI and resolver tests
.contextos/                Canonical project memory for this repo
docs/                      Product, architecture, roadmap, and launch docs
.github/                   CI, issue templates, PR template

Generated ContextOS state in consuming projects is plain Markdown by design. You should be able to review it, edit it, diff it, and commit it like any other repo-native project file.

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.
• Future remote sync must be encrypted before upload.

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.
• Do not add hosted sync, dashboards, IDE extensions, vector databases, Tree-sitter indexing, or multi-agent runtimes to the MVP.
• Update tests and docs with behavior changes.

Launch Readiness

Public launch tracking lives in docs/public-launch-checklist.md.

License

Checkpoint is licensed under the Apache License 2.0.