jjckpt (CLI engine)

Per-turn AI checkpoints backed by Jujutsu (jj), isolated from your real git history.

Every agent turn seals a lightweight checkpoint (a jj commit) in a store that never touches your .git. Revert to any checkpoint, fork an alternate timeline, or undo — all native to jj.

This package is the engine only. The everyday UI is the Jujutsu(jj) Checkpoint VS Code extension, which bundles this engine and sets up agent hooks for you.

Requirements

• jj on PATH (brew install jj, winget install jj-vcs.jj, cargo install --locked --bin jj jj-cli)
• git (required by jj)
• Node.js >= 16

Install

npm install -g jjckpt
# or ad hoc, no install:
npx jjckpt status

Then wire your agent's end-of-turn hook to jjckpt hook-commit. For Claude Code, merge into ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "jjckpt hook-commit --agent claude-code || true" }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "jjckpt hook-commit --phase pre --agent human --session human || true" }] }
    ]
  }
}

Hook configs for Codex, Cursor, Gemini, OpenCode, and VS Code Copilot are in the repo's README.md / editors/ directory — or let the VS Code extension's setup wizard write them for you.

Commands

jjckpt commit          seal a checkpoint from current edits (skips if clean)
jjckpt log             list checkpoints (newest first)
jjckpt stages          checkpoints bucketed by the git commit they sit on
jjckpt status          summary
jjckpt diff [id]       show a checkpoint's diff (or the live diff)
jjckpt restore <id>    restore working copy to a checkpoint (undoable)
jjckpt fork <id>       start an alternate timeline off a checkpoint
jjckpt undo            rewind the last operation

Checkpoints are local jj commits with Jjckpt-* metadata trailers; they never appear in git log. In a git repo the store lives OUTSIDE the repo (~/.local/share/jjckpt/stores), keyed by project path.