Jujutsu(jj) Checkpoint — VS Code

Save safe points around AI agent edits without polluting your git history.

Jujutsu(jj) Checkpoint gives you a simple default flow: install it, run your agent, and get safe points you can inspect or roll back. Under the hood it uses Jujutsu (jj) as the checkpoint engine, so power users can still fork timelines and inspect the DAG.

The sidebar shows Sessions -> Safe Points -> Files. Each changed file opens in VS Code's native diff viewer, and you can compare any safe point to your current working copy before restoring it.

When you go back to an older safe point and continue in a new direction, older future safe points stay visible but are marked off current path with a muted icon. That makes the current A -> D path obvious without deleting the preserved A -> B -> C history.

Prerequisites

• VS Code 1.80 or newer.
• Git 2.41 or newer, required by Jujutsu.
• Jujutsu (jj).
• Bash for the bundled jjckpt engine. macOS and Linux already have this in normal setups. On Windows, install Git for Windows or use WSL.
• Optional: at least one supported AI agent: Claude Code, Codex, Cursor, Gemini, Antigravity, or OpenCode.

Install Jujutsu manually if you do not want the extension setup prompt to do it:

# macOS or Linux with Homebrew
brew install jj

# Windows
winget install jj-vcs.jj

# Any platform with Rust/Cargo
cargo install --locked --bin jj jj-cli

The extension also asks for permission to install jj on first startup if it is missing.

Install the Extension

From the Marketplace, install Jujutsu(jj) Checkpoint. VS Code activates the extension on startup and asks whether to set it up. Setup installs the bundled jjckpt engine and offers to wire hooks for detected agents.

To install from a local VSIX:

code --install-extension jj-checkpoint-0.3.0.vsix

For development:

code /path/to/jjckpt-vscode
# Press F5 in VS Code to launch an Extension Development Host.

How to Use

1. Install the extension.
2. Accept the setup prompt, or run Jujutsu(jj) Checkpoint: Setup / install dependencies from the Command Palette.
3. Select the AI agents you want to checkpoint.
4. Open a project folder in VS Code.
5. Run an agent turn, or click Save Safe Point in the status bar or Checkpoints sidebar.
6. Open the Checkpoints activity bar view.
7. Expand Sessions -> Safe Points -> Files.
8. Click a file to inspect what changed at that safe point.

Sidebar actions:

• Save Safe Point: manually seal the current working copy.
• Refresh: reload sessions and checkpoints.
• Compare to current: compare a safe point or file against your current working copy.
• Restore: preview changed files or restore the working copy to that safe point.
• Undo: rewind the last jjckpt operation.
• Safe points marked off current path are preserved older futures, not the path you are currently editing.

Power mode:

• Disabled by default to keep the UI linear and friendly.
• Run jjckpt: Toggle power mode to show advanced actions.
• Power mode adds the timeline graph and fork actions for Jujutsu-style branching.

Manual jjckpt CLI Install

The extension setup installs jjckpt automatically. To install it manually from this repository:

mkdir -p ~/.local/bin
cp bin/jjckpt ~/.local/bin/jjckpt
chmod +x ~/.local/bin/jjckpt

Make sure ~/.local/bin is on your PATH, then verify:

jjckpt status

If VS Code cannot find it, set:

{
  "jjckpt.binary": "/Users/you/.local/bin/jjckpt"
}

Windows manual wrapper:

mkdir "%LOCALAPPDATA%\jjckpt\bin"
copy bin\jjckpt "%LOCALAPPDATA%\jjckpt\bin\jjckpt"

Create %LOCALAPPDATA%\jjckpt\bin\jjckpt.cmd:

@echo off
where bash >nul 2>nul
if errorlevel 1 echo jjckpt needs bash. Install Git for Windows or use WSL. 1>&2 & exit /b 1
bash "%~dp0jjckpt" %*

Then set jjckpt.binary to the full jjckpt.cmd path.

Manual Agent Hooks

The setup wizard can write these for you. Use the examples below only when you want to wire agents manually. Replace /Users/you/.local/bin/jjckpt with your real jjckpt path.

Claude Code

File: ~/.claude/settings.json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/you/.local/bin/jjckpt hook-commit --agent claude-code || true"
          }
        ]
      }
    ]
  }
}

Codex

File: ~/.codex/hooks.json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/you/.local/bin/jjckpt hook-commit --agent codex",
            "statusMessage": "Saving checkpoint"
          }
        ]
      }
    ]
  }
}

Cursor

File: ~/.cursor/hooks.json

{
  "version": 1,
  "hooks": {
    "stop": [
      {
        "command": "/Users/you/.local/bin/jjckpt hook-commit --agent cursor",
        "timeout": 10
      }
    ]
  }
}

Gemini

File: ~/.gemini/settings.json

{
  "hooks": {
    "AfterAgent": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/you/.local/bin/jjckpt hook-commit --agent gemini",
            "name": "jjckpt-checkpoint",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

Antigravity

File: ~/.gemini/antigravity-cli/hooks.json

{
  "jjckpt-checkpoint": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/you/.local/bin/jjckpt hook-commit --agent antigravity",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

OpenCode

File: ~/.config/opencode/plugins/jjckpt.js

// jjckpt checkpoint plugin for OpenCode.
export const JjckptCheckpoint = async ({ $, directory }) => {
  return {
    event: async ({ event }) => {
      if (event.type !== "session.idle") return;
      const sid = event.properties?.sessionID || "opencode";
      const payload = JSON.stringify({ session_id: sid, cwd: directory });
      await $`printf %s ${payload} | /Users/you/.local/bin/jjckpt hook-commit --agent opencode`
        .quiet()
        .nothrow();
    },
  };
};

CLI Commands

jjckpt commit --agent vscode  # save a safe point now
jjckpt status                 # summary and recent checkpoints
jjckpt log                    # list checkpoints
jjckpt graph                  # show timelines/forks
jjckpt diff <id>              # inspect a checkpoint diff
jjckpt restore <id>           # restore working copy to a checkpoint
jjckpt fork <id>              # start an alternate timeline
jjckpt undo                   # undo the last jjckpt operation

Settings

• jjckpt.binary: path to the CLI. Use an absolute path if VS Code cannot find it.
• jjckpt.pollSeconds: how often the sidebar polls for new checkpoints.
• jjckpt.powerMode: show advanced Jujutsu actions like graph and fork.

Notes

• Checkpoints are local. They are not git commits and do not appear in git log.
• In a non-git folder, jjckpt creates a self-contained .jj/ store.
• In an existing git repository, jjckpt keeps the checkpoint store separate and adds .jj/ to the local git exclude file.