Metadata-Version: 2.4
Name: checkpoint-cli
Version: 0.1.0
Summary: Local-first CLI for ContextOS repo-native AI engineering continuity
Author: ContextOS contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/bkalyankumar/contextos
Project-URL: Issues, https://github.com/bkalyankumar/contextos/issues
Project-URL: Changelog, https://github.com/bkalyankumar/contextos/blob/main/CHANGELOG.md
Keywords: ai,agents,cli,context,developer-tools,handoff,markdown
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.18.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.14.0; extra == "dev"
Requires-Dist: vulture>=2.14; extra == "dev"
Dynamic: license-file

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

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

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

Smoke test:

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

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

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

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

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

```bash
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](SECURITY.md), not public issues.

## Contributing

Start with [CONTRIBUTING.md](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](docs/public-launch-checklist.md).

## License

Checkpoint is licensed under the [Apache License 2.0](LICENSE).
