@mohshomis/ckpt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+# ckpt
+
+Automatic checkpoints for AI coding sessions. Per-step undo, branching, and restore — on top of git.
+
+```bash
+ckpt watch     # start watching — auto-snapshots every AI change
+# ... let Kiro / Cursor / Claude Code / Codex do its thing ...
+ckpt steps     # see what happened, step by step
+ckpt restore 3 # go back to step 3
+ckpt end       # squash into one clean git commit
+```
+
+## The problem
+
+AI agents edit your code in rapid bursts — 5, 10, 20 files at once. When something breaks:
+
+- **Undo everything** (Kiro/Cursor revert) — lose all the good changes too
+- **Manually figure out** which change broke things — painful and slow
+
+No per-step undo. No timeline. No way to try a different approach without losing the first one.
+
+### How AI agents handle errors today (and why it's wasteful)
+
+When an AI agent breaks something, here's what actually happens:
+
+1. The agent notices the error (or you tell it)
+2. It re-reads the files it already wrote to understand the current state
+3. It reasons about what went wrong — burning tokens on analysis
+4. It rewrites the files — often re-generating code it already had right
+5. If the fix doesn't work, repeat steps 2-4 again. And again.
+
+Every cycle costs tokens, time, and context window. A simple revert that should take milliseconds instead takes 30-60 seconds and hundreds of tokens as the agent manually reconstructs what it already had.
+
+With ckpt: `ckpt restore 3` — instant rollback to the last good state. Zero tokens. Zero re-reading. Zero re-writing.
+
+## "But my IDE already has checkpoints"
+
+Yes. Cursor has timeline. Kiro has revert. Windsurf has checkpoints. Here's what ckpt does differently:
+
+### 1. The AI agent can operate it — not just you
+
+IDE checkpoints are buttons in a UI. The human clicks "revert." The AI agent can't.
+
+With ckpt, the agent itself runs `ckpt restore 3`. It becomes self-correcting — it can checkpoint its own work, detect when something broke, roll back, and try a different approach. No human in the loop. No IDE UI needed.
+
+This is the core difference. IDE checkpoints are a human safety net. ckpt is an AI capability.
+
+### 2. Terminal agents have nothing
+
+Claude Code, Codex, Aider, and any agent running in a terminal have zero checkpoint support. No UI, no revert button, nothing. When they break something, they brute-force fix it by re-reading and rewriting — slow, expensive, and often makes things worse.
+
+ckpt is the only checkpoint system that works for terminal-based agents.
+
+### 3. Branching — try multiple approaches
+
+No IDE has this. `ckpt try approach-a -r 2` saves the current work, goes back to step 2, and lets the agent try a completely different approach. Then `ckpt trydiff approach-a` compares the two. The agent (or you) picks the better one.
+
+IDEs give you undo. ckpt gives you branching exploration.
+
+### 4. Persistent history
+
+IDE checkpoints disappear when you close the session or the IDE. `ckpt log` keeps every session permanently. Weeks later you can see exactly what the agent did, step by step.
+
+### 5. Works everywhere
+
+IDE checkpoints only work inside that IDE. ckpt works in any terminal, any CI pipeline, any environment. It's just git.
+
+| Feature | IDE checkpoints | ckpt |
+|---------|----------------|------|
+| AI agent can use it | ✗ | ✓ |
+| Terminal agents (Codex, Aider, Claude Code) | ✗ | ✓ |
+| Branch & compare approaches | ✗ | ✓ |
+| Persistent history | ✗ | ✓ |
+| Works outside IDE | ✗ | ✓ |
+| Step tagging | ✗ | ✓ |
+| Auto-snapshot | ✓ | ✓ |
+| Per-step restore | ✓ | ✓ |
+
+## What happens when AI agents use ckpt
+
+ckpt is a CLI. Every AI coding agent can already run shell commands. No plugins, no integrations, no MCP servers. Just tell the agent to use it.
+
+Add this to your prompt or system instructions:
+
+> Run `ckpt watch` in the background before starting work. It auto-snapshots every change you make. If something breaks, run `ckpt restore <step>` instead of manually rewriting. To try a different approach, run `ckpt try <name> -r <step>`. When done, run `ckpt end`.
+>
+> For richer snapshots with reasoning, use `ckpt snap "why you made this change"` after each logical step instead of relying on auto-snapshots.
+
+Here's what changes:
+
+### Faster error recovery
+
+Without ckpt: agent breaks something → re-reads files → reasons about the error → rewrites the fix → maybe breaks it again → repeat. 30-60 seconds per cycle.
+
+With ckpt: `ckpt restore 3` → back to the last good state in milliseconds. Try a different approach immediately.
+
+### Cheaper sessions
+
+Every time an agent re-reads and rewrites files to fix a mistake, that's tokens you're paying for. A typical error-fix cycle costs 500-2000 tokens just to get back to where you were. ckpt eliminates that entire cost — restore is free.
+
+### Better results through exploration
+
+Without ckpt, agents commit to one approach and push forward. If it doesn't work, they patch on top of patches until the code is a mess.
+
+With ckpt, an agent can:
+1. Try approach A → `ckpt snap "approach A: class-based"`
+2. Hit a wall → `ckpt try approach-a -r 1` (save A, go back)
+3. Try approach B → `ckpt snap "approach B: hooks-based"`
+4. Compare → `ckpt trydiff approach-a`
+5. Pick the better one
+
+This is how good developers work. ckpt gives AI agents the same workflow.
+
+### Cleaner context windows
+
+When an agent manually reverts by rewriting, it fills the context window with "oops, let me fix that" back-and-forth. With ckpt, a failed approach is `ckpt restore 3` — one line instead of 20 messages of debugging. The context stays clean for actual work.
+
+## Works with any AI agent
+
+| Agent | Works? | How |
+|-------|--------|-----|
+| Kiro | ✓ | Runs shell commands natively |
+| Cursor | ✓ | Runs shell commands natively |
+| Claude Code | ✓ | Runs shell commands natively |
+| OpenAI Codex | ✓ | Runs shell commands natively |
+| GitHub Copilot | ✓ | Via terminal |
+| Windsurf | ✓ | Runs shell commands natively |
+| Aider | ✓ | Runs shell commands natively |
+| Any human | ✓ | It's a CLI |
+
+## What ckpt does
+
+ckpt watches your project while an AI agent works. Every time the agent pauses, ckpt takes a snapshot. You get a timeline of every step, and you can restore to any point.
+
+It's just git under the hood — hidden branch, real commits, squash when done.
+
+## Install
+
+```bash
+npm install -g @mohshomis/ckpt
+```
+
+## Usage
+
+### Auto mode (recommended)
+
+```bash
+ckpt watch
+```
+
+That's it. Let your AI agent work. ckpt snapshots automatically.
+
+### Manual mode
+
+```bash
+ckpt start
+ckpt snap "chose HS256 over RS256 because this is a monolith"
+ckpt snap "updated tests — old ones used session cookies"
+ckpt end -m "refactored auth to JWT"
+```
+
+### Restore
+
+```bash
+ckpt restore 5              # go back to step 5
+ckpt restore --last-good    # go back to last step tagged "good"
+ckpt restore --last working # go back to last step tagged "working"
+```
+
+### Tag steps
+
+```bash
+ckpt tag 3 good        # mark step 3 as good
+ckpt tag 5 broken      # mark step 5 as broken
+ckpt tag 2 experiment  # or any custom tag
+```
+
+### Try multiple approaches
+
+```bash
+# AI tries approach A, gets to step 5
+ckpt try approach-a -r 2    # save as branch, go back to step 2
+
+# AI tries approach B from step 2
+ckpt snap "approach B: used hooks instead of HOCs"
+
+# Compare the two approaches
+ckpt trydiff approach-a
+
+# List all experiments
+ckpt tries
+```
+
+### Range diff
+
+```bash
+ckpt diff 3       # what changed at step 3
+ckpt diff 2 7     # everything that changed between step 2 and step 7
+```
+
+### Session history
+
+```bash
+ckpt log                      # list all past sessions
+ckpt log --detail abc123      # see full step history for a past session
+```
+
+### End a session
+
+```bash
+ckpt end -m "built auth system"  # squash into one clean commit
+ckpt end --discard               # throw away everything
+```
+
+## All commands
+
+| Command | What it does |
+|---------|-------------|
+| `ckpt watch` | Auto-snapshot file changes |
+| `ckpt start` | Start a session manually |
+| `ckpt snap <msg>` | Manual snapshot with a reason |
+| `ckpt steps` | List all snapshots |
+| `ckpt diff <step> [step]` | Diff for one step or between two |
+| `ckpt why <step>` | Show why a step was made |
+| `ckpt tag <step> <tag>` | Tag a step (good, broken, etc.) |
+| `ckpt restore [step]` | Go back to a step |
+| `ckpt restore --last-good` | Go back to last "good" step |
+| `ckpt try <name> [-r step]` | Branch to try a different approach |
+| `ckpt trydiff <name>` | Compare with an experiment branch |
+| `ckpt tries` | List experiment branches |
+| `ckpt end` | Squash into one commit |
+| `ckpt log` | Show all past sessions |
+| `ckpt status` | Current session info |
+
+## How it works
+
+1. `ckpt start` creates a hidden branch: `ckpt/session/<id>`
+2. Each snapshot = a real git commit on that branch
+3. `ckpt restore` = `git reset --hard` to that commit
+4. `ckpt try` = `git branch` at current HEAD
+5. `ckpt end` = `git merge --squash` back to your branch
+6. Session history saved to `.ckpt/history/`
+
+No database. No new format. Just git.
+
+## Smart auto-labels
+
+In watch mode, ckpt auto-categorizes changes:
+
+```
+✓ Step 1  [components] created Button.tsx, Modal.tsx
+✓ Step 2  [tests] modified Button.test.tsx
+✓ Step 3  [config] modified package.json
+✓ Step 4  [styles] modified globals.css
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import path from 'path';
+import * as core from './core.js';
+import { startWatch } from './watch.js';
+const program = new Command();
+program
+    .name('ckpt')
+    .description('Automatic checkpoints for AI coding sessions. Per-step undo on top of git.')
+    .version('0.1.0')
+    .option('-C, --path <dir>', 'Run as if ckpt was started in <dir>');
+function getCwd() {
+    const opts = program.opts();
+    return opts.path ? path.resolve(opts.path) : process.cwd();
+}
+// ── watch ─────────────────────────────────────────────────────────────────
+program
+    .command('watch')
+    .description('Auto-snapshot file changes — just run this and let the AI work')
+    .option('-d, --debounce <ms>', 'Quiet period before snapshotting (ms)', '2000')
+    .action((opts) => {
+    startWatch(getCwd(), parseInt(opts.debounce));
+});
+// ── start ─────────────────────────────────────────────────────────────────
+program
+    .command('start')
+    .description('Start a session manually (watch does this automatically)')
+    .action(() => {
+    try {
+        const session = core.startSession(getCwd());
+        console.log(`\n⚡ Session started: ${session.id}`);
+        console.log(`   Branch: ${session.branch}\n`);
+    }
+    catch (e) {
+        console.error(`✗ ${e.message}`);
+        process.exit(1);
+    }
+});
+// ── snap ──────────────────────────────────────────────────────────────────
+program
+    .command('snap <message>')
+    .description('Manual snapshot with a reason')
+    .action((message) => {
+    try {
+        const snapshot = core.snap(getCwd(), message);
+        if (snapshot) {
+            console.log(`\n✓ Step ${snapshot.id}: ${snapshot.message}`);
+            console.log(`  ${snapshot.hash} | ${snapshot.filesChanged.length} files | +${snapshot.additions} -${snapshot.deletions}\n`);
+        }
+        else {
+            console.log('Nothing to snapshot — no changes.');
+        }
+    }
+    catch (e) {
+        console.error(`✗ ${e.message}`);
+        process.exit(1);
+    }
+});
+// ── steps ─────────────────────────────────────────────────────────────────
+program
+    .command('steps')
+    .description('List all snapshots in the current session')
+    .action(() => {
+    try {
+        const snapshots = core.steps(getCwd());
+        if (snapshots.length === 0) {
+            console.log('\nNo snapshots yet.\n');
+            return;
+        }
+        console.log(`\n  Steps (${snapshots.length}):\n`);
+        for (const s of snapshots) {
+            const time = new Date(s.timestamp).toLocaleTimeString();
+            const tag = s.tag ? ` [${s.tag}]` : '';
+            console.log(`  ${s.id}  ${s.hash}  ${time}  +${s.additions} -${s.deletions}  ${s.message}${tag}`);
+        }
+        console.log();
+    }
+    catch (e) {
+        console.error(`✗ ${e.message}`);
+        process.exit(1);
+    }
+});
+// ── diff ──────────────────────────────────────────────────────────────────
+program
+    .command('diff <from> [to]')
+    .description('Show diff for a step, or between two steps (ckpt diff 2 7)')
+    .action((from, to) => {
+    try {
+        console.log(core.diff(getCwd(), parseInt(from), to ? parseInt(to) : undefined));
+    }
+    catch (e) {
+        console.error(`✗ ${e.message}`);
+        process.exit(1);
+    }
+});
+// ── why ───────────────────────────────────────────────────────────────────
+program
+    .command('why <step>')
+    .description('Show why a step was made')
+    .action((step) => {
+    try {
+        const info = core.why(getCwd(), parseInt(step));
+        const tag = info.tag ? ` [${info.tag}]` : '';
+        console.log(`\n  Step ${step}: "${info.message}"${tag}\n`);
+        console.log(`  Files: ${info.files.join(', ')}\n`);
+        console.log(info.diff);
+    }
+    catch (e) {
+        console.error(`✗ ${e.message}`);
+        process.exit(1);
+    }
+});
+// ── tag ───────────────────────────────────────────────────────────────────
+program
+    .command('tag <step> <tag>')
+    .description('Tag a step (good, broken, experiment, or any custom tag)')
+    .action((step, tag) => {
+    try {
+        core.tagStep(getCwd(), parseInt(step), tag);
+        console.log(`\n✓ Step ${step} tagged as "${tag}".\n`);
+    }
+    catch (e) {
+        console.error(`✗ ${e.message}`);
+        process.exit(1);
+    }
+});
+// ── restore ───────────────────────────────────────────────────────────────
+program
+    .command('restore [step]')
+    .description('Go back to a step, or --last-good to restore last "good" tagged step')
+    .option('--last-good', 'Restore to the last step tagged "good"')
+    .option('--last <tag>', 'Restore to the last step with this tag')
+    .action((step, opts) => {
+    try {
+        if (opts.lastGood) {
+            const id = core.restoreToTag(getCwd(), 'good');
+            console.log(`\n✓ Restored to step ${id} (last "good").\n`);
+        }
+        else if (opts.last) {
+            const id = core.restoreToTag(getCwd(), opts.last);
+            console.log(`\n✓ Restored to step ${id} (last "${opts.last}").\n`);
+        }
+        else if (step) {
+            core.restore(getCwd(), parseInt(step));
+            console.log(`\n✓ Restored to step ${step}.\n`);
+        }
+        else {
+            console.error('✗ Provide a step number, --last-good, or --last <tag>.');
+            process.exit(1);
+        }
+    }
+    catch (e) {
+        console.error(`✗ ${e.message}`);
+        process.exit(1);
+    }
+});
+// ── try ───────────────────────────────────────────────────────────────────
+program
+    .command('try <name>')
+    .description('Save current progress as a named branch, optionally go back to try another approach')
+    .option('-r, --restore <step>', 'After branching, restore to this step to try a different approach')
+    .action((name, opts) => {
+    try {
+        const restoreTo = opts.restore ? parseInt(opts.restore) : undefined;
+        const branch = core.branchSession(getCwd(), name, restoreTo);
+        console.log(`\n✓ Saved as ${branch}`);
+        if (restoreTo)
+            console.log(`  Restored to step ${restoreTo} — try a different approach.`);
+        console.log(`  Compare later with: ckpt trydiff ${name}\n`);
+    }
+    catch (e) {
+        console.error(`✗ ${e.message}`);
+        process.exit(1);
+    }
+});
+// ── trydiff ───────────────────────────────────────────────────────────────
+program
+    .command('trydiff <name>')
+    .description('Compare current state with a named experiment branch')
+    .action((name) => {
+    try {
+        console.log(core.branchDiff(getCwd(), name));
+    }
+    catch (e) {
+        console.error(`✗ ${e.message}`);
+        process.exit(1);
+    }
+});
+// ── tries ─────────────────────────────────────────────────────────────────
+program
+    .command('tries')
+    .description('List all named experiment branches')
+    .action(() => {
+    try {
+        const branches = core.listBranches(getCwd());
+        if (branches.length === 0) {
+            console.log('\nNo experiment branches. Use "ckpt try <name>" to create one.\n');
+            return;
+        }
+        console.log(`\n  Experiments (${branches.length}):\n`);
+        for (const b of branches)
+            console.log(`  ${b}`);
+        console.log();
+    }
+    catch (e) {
+        console.error(`✗ ${e.message}`);
+        process.exit(1);
+    }
+});
+// ── end ───────────────────────────────────────────────────────────────────
+program
+    .command('end')
+    .description('End session — squash all steps into one clean commit')
+    .option('-m, --message <msg>', 'Commit message')
+    .option('--discard', 'Throw away all changes instead of committing')
+    .action((opts) => {
+    try {
+        const result = core.endSession(getCwd(), opts.message, opts.discard);
+        console.log(`\n✓ ${result}\n`);
+    }
+    catch (e) {
+        console.error(`✗ ${e.message}`);
+        process.exit(1);
+    }
+});
+// ── status ────────────────────────────────────────────────────────────────
+program
+    .command('status')
+    .description('Show current session info')
+    .action(() => {
+    const session = core.status(getCwd());
+    if (!session) {
+        console.log('\nNo active session. Run "ckpt watch" to start.\n');
+        return;
+    }
+    console.log(`\n  Session: ${session.id}`);
+    console.log(`  Branch:  ${session.branch}`);
+    console.log(`  Base:    ${session.originalBranch}`);
+    console.log(`  Steps:   ${session.snapshots.length}`);
+    console.log(`  Started: ${new Date(session.startedAt).toLocaleString()}\n`);
+});
+// ── log ───────────────────────────────────────────────────────────────────
+program
+    .command('log')
+    .description('Show history of all past sessions')
+    .option('--detail <id>', 'Show full detail for a specific past session')
+    .action((opts) => {
+    try {
+        if (opts.detail) {
+            const s = core.logDetail(getCwd(), opts.detail);
+            const st = s.discarded ? '(discarded)' : `→ ${s.commitHash}`;
+            console.log(`\n  Session ${s.id} ${st}`);
+            console.log(`  Branch:  ${s.originalBranch}`);
+            console.log(`  Started: ${new Date(s.startedAt).toLocaleString()}`);
+            console.log(`  Ended:   ${new Date(s.endedAt).toLocaleString()}`);
+            console.log(`  Steps:   ${s.snapshots.length}\n`);
+            for (const snap of s.snapshots) {
+                const time = new Date(snap.timestamp).toLocaleTimeString();
+                const tag = snap.tag ? ` [${snap.tag}]` : '';
+                console.log(`  ${snap.id}  ${snap.hash}  ${time}  +${snap.additions} -${snap.deletions}  ${snap.message}${tag}`);
+            }
+            console.log();
+        }
+        else {
+            const sessions = core.log(getCwd());
+            if (sessions.length === 0) {
+                console.log('\nNo session history yet.\n');
+                return;
+            }
+            console.log(`\n  Session history (${sessions.length}):\n`);
+            for (const s of sessions) {
+                const date = new Date(s.startedAt).toLocaleDateString();
+                const time = new Date(s.startedAt).toLocaleTimeString();
+                const st = s.discarded ? 'discarded' : `→ ${s.commitHash}`;
+                console.log(`  ${s.id}  ${date} ${time}  ${s.snapshots.length} steps  ${st}`);
+            }
+            console.log(`\n  Run "ckpt log --detail <id>" for full step history.\n`);
+        }
+    }
+    catch (e) {
+        console.error(`✗ ${e.message}`);
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/core.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ckpt core — automatic checkpoints for AI coding sessions, on top of git.
+ *
+ * Uses a hidden branch (ckpt/session/<id>) to store lightweight snapshots.
+ * Each snapshot is a real git commit on that branch, so all git tooling works.
+ * When you're done, squash into a single commit on your real branch.
+ */
+export type StepTag = 'good' | 'broken' | 'experiment' | string;
+export interface Snapshot {
+    id: number;
+    hash: string;
+    timestamp: string;
+    message: string;
+    filesChanged: string[];
+    additions: number;
+    deletions: number;
+    tag: StepTag | null;
+}
+export interface Session {
+    id: string;
+    branch: string;
+    originalBranch: string;
+    startedAt: string;
+    snapshots: Snapshot[];
+}
+export interface ArchivedSession {
+    id: string;
+    originalBranch: string;
+    startedAt: string;
+    endedAt: string;
+    commitHash: string | null;
+    discarded: boolean;
+    snapshots: Snapshot[];
+}
+export declare function startSession(cwd: string): Session;
+export declare function snap(cwd: string, message: string): Snapshot | null;
+export declare function steps(cwd: string): Snapshot[];
+export declare function diff(cwd: string, fromStep: number, toStep?: number): string;
+export declare function why(cwd: string, stepId: number): {
+    message: string;
+    diff: string;
+    files: string[];
+    tag: StepTag | null;
+};
+export declare function restore(cwd: string, stepId: number): void;
+export declare function restoreToTag(cwd: string, tag?: StepTag): number;
+export declare function tagStep(cwd: string, stepId: number, tag: StepTag): void;
+export declare function branchSession(cwd: string, name: string, restoreToStep?: number): string;
+export declare function branchDiff(cwd: string, name: string): string;
+export declare function listBranches(cwd: string): string[];
+export declare function endSession(cwd: string, commitMessage?: string, discard?: boolean): string;
+export declare function status(cwd: string): Session | null;
+export declare function log(cwd: string): ArchivedSession[];
+export declare function logDetail(cwd: string, sessionId: string): ArchivedSession;

package/dist/core.js

@@ -0,0 +1,272 @@
+/**
+ * ckpt core — automatic checkpoints for AI coding sessions, on top of git.
+ *
+ * Uses a hidden branch (ckpt/session/<id>) to store lightweight snapshots.
+ * Each snapshot is a real git commit on that branch, so all git tooling works.
+ * When you're done, squash into a single commit on your real branch.
+ */
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+const CKPT_DIR = '.ckpt';
+const SESSION_FILE = 'session.json';
+const HISTORY_DIR = 'history';
+function git(cmd, cwd) {
+    return execSync(`git ${cmd}`, {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+}
+function gitSafe(cmd, cwd) {
+    try {
+        return git(cmd, cwd);
+    }
+    catch {
+        return null;
+    }
+}
+function ensureGitRepo(cwd) {
+    if (!gitSafe('rev-parse --git-dir', cwd)) {
+        throw new Error('Not a git repository. Run "git init" first.');
+    }
+}
+function sessionPath(cwd) {
+    return path.join(cwd, CKPT_DIR, SESSION_FILE);
+}
+function historyDir(cwd) {
+    return path.join(cwd, CKPT_DIR, HISTORY_DIR);
+}
+function loadSession(cwd) {
+    const p = sessionPath(cwd);
+    if (!fs.existsSync(p))
+        return null;
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+function saveSession(cwd, session) {
+    const dir = path.join(cwd, CKPT_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(sessionPath(cwd), JSON.stringify(session, null, 2), 'utf8');
+}
+function ensureCkptIgnored(cwd) {
+    const gitignorePath = path.join(cwd, '.gitignore');
+    const gitignore = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
+    if (!gitignore.includes('.ckpt')) {
+        fs.appendFileSync(gitignorePath, '\n.ckpt/\n');
+    }
+}
+function archiveSession(cwd, session, commitHash, discarded) {
+    const dir = historyDir(cwd);
+    fs.mkdirSync(dir, { recursive: true });
+    const archived = {
+        id: session.id,
+        originalBranch: session.originalBranch,
+        startedAt: session.startedAt,
+        endedAt: new Date().toISOString(),
+        commitHash,
+        discarded,
+        snapshots: session.snapshots,
+    };
+    fs.writeFileSync(path.join(dir, `${session.id}.json`), JSON.stringify(archived, null, 2), 'utf8');
+}
+// ── Public API ────────────────────────────────────────────────────────────
+export function startSession(cwd) {
+    ensureGitRepo(cwd);
+    const existing = loadSession(cwd);
+    if (existing) {
+        throw new Error(`Session already active (${existing.id}). Run "ckpt end" or "ckpt end --discard" first.`);
+    }
+    const status = git('status --porcelain', cwd);
+    if (status) {
+        git('stash push -m "ckpt: auto-stash before session"', cwd);
+    }
+    const originalBranch = git('rev-parse --abbrev-ref HEAD', cwd);
+    const sessionId = randomUUID().slice(0, 8);
+    const branchName = `ckpt/session/${sessionId}`;
+    git(`checkout -b ${branchName}`, cwd);
+    if (status) {
+        gitSafe('stash pop', cwd);
+    }
+    const session = {
+        id: sessionId,
+        branch: branchName,
+        originalBranch,
+        startedAt: new Date().toISOString(),
+        snapshots: [],
+    };
+    ensureCkptIgnored(cwd);
+    saveSession(cwd, session);
+    return session;
+}
+export function snap(cwd, message) {
+    ensureGitRepo(cwd);
+    const session = loadSession(cwd);
+    if (!session) {
+        throw new Error('No active session. Run "ckpt start" first.');
+    }
+    git('add -A', cwd);
+    const status = git('status --porcelain', cwd);
+    if (!status)
+        return null;
+    const diffFiles = gitSafe('diff --cached --name-only', cwd) ?? '';
+    const filesChanged = diffFiles.split('\n').filter(Boolean);
+    const numstat = gitSafe('diff --cached --numstat', cwd) ?? '';
+    let additions = 0;
+    let deletions = 0;
+    for (const line of numstat.split('\n').filter(Boolean)) {
+        const [add, del] = line.split('\t');
+        additions += parseInt(add) || 0;
+        deletions += parseInt(del) || 0;
+    }
+    const stepNum = session.snapshots.length + 1;
+    const commitMsg = `ckpt[${stepNum}]: ${message}`;
+    git(`commit -m "${commitMsg.replace(/"/g, '\\"')}"`, cwd);
+    const hash = git('rev-parse --short HEAD', cwd);
+    const snapshot = {
+        id: stepNum,
+        hash,
+        timestamp: new Date().toISOString(),
+        message,
+        filesChanged,
+        additions,
+        deletions,
+        tag: null,
+    };
+    session.snapshots.push(snapshot);
+    saveSession(cwd, session);
+    return snapshot;
+}
+export function steps(cwd) {
+    const session = loadSession(cwd);
+    if (!session)
+        throw new Error('No active session. Run "ckpt start" first.');
+    return session.snapshots;
+}
+export function diff(cwd, fromStep, toStep) {
+    const session = loadSession(cwd);
+    if (!session)
+        throw new Error('No active session.');
+    if (toStep !== undefined) {
+        const from = session.snapshots.find((s) => s.id === fromStep);
+        const to = session.snapshots.find((s) => s.id === toStep);
+        if (!from)
+            throw new Error(`Step ${fromStep} not found.`);
+        if (!to)
+            throw new Error(`Step ${toStep} not found.`);
+        return git(`diff ${from.hash} ${to.hash}`, cwd);
+    }
+    const snapshot = session.snapshots.find((s) => s.id === fromStep);
+    if (!snapshot)
+        throw new Error(`Step ${fromStep} not found.`);
+    return git(`diff ${snapshot.hash}~1 ${snapshot.hash}`, cwd);
+}
+export function why(cwd, stepId) {
+    const session = loadSession(cwd);
+    if (!session)
+        throw new Error('No active session.');
+    const snapshot = session.snapshots.find((s) => s.id === stepId);
+    if (!snapshot)
+        throw new Error(`Step ${stepId} not found.`);
+    const d = git(`diff ${snapshot.hash}~1 ${snapshot.hash} --stat`, cwd);
+    return { message: snapshot.message, diff: d, files: snapshot.filesChanged, tag: snapshot.tag };
+}
+export function restore(cwd, stepId) {
+    const session = loadSession(cwd);
+    if (!session)
+        throw new Error('No active session.');
+    const snapshot = session.snapshots.find((s) => s.id === stepId);
+    if (!snapshot)
+        throw new Error(`Step ${stepId} not found.`);
+    git(`reset --hard ${snapshot.hash}`, cwd);
+    session.snapshots = session.snapshots.filter((s) => s.id <= stepId);
+    saveSession(cwd, session);
+}
+export function restoreToTag(cwd, tag = 'good') {
+    const session = loadSession(cwd);
+    if (!session)
+        throw new Error('No active session.');
+    const tagged = session.snapshots.filter((s) => s.tag === tag);
+    if (tagged.length === 0)
+        throw new Error(`No steps tagged "${tag}".`);
+    const last = tagged[tagged.length - 1];
+    restore(cwd, last.id);
+    return last.id;
+}
+export function tagStep(cwd, stepId, tag) {
+    const session = loadSession(cwd);
+    if (!session)
+        throw new Error('No active session.');
+    const snapshot = session.snapshots.find((s) => s.id === stepId);
+    if (!snapshot)
+        throw new Error(`Step ${stepId} not found.`);
+    snapshot.tag = tag;
+    saveSession(cwd, session);
+}
+export function branchSession(cwd, name, restoreToStep) {
+    const session = loadSession(cwd);
+    if (!session)
+        throw new Error('No active session.');
+    const branchName = `ckpt/try/${name}`;
+    git(`branch ${branchName}`, cwd);
+    if (restoreToStep !== undefined) {
+        restore(cwd, restoreToStep);
+    }
+    return branchName;
+}
+export function branchDiff(cwd, name) {
+    return git(`diff HEAD ckpt/try/${name}`, cwd);
+}
+export function listBranches(cwd) {
+    const raw = gitSafe('branch --list "ckpt/try/*"', cwd) ?? '';
+    return raw.split('\n').map((b) => b.trim()).filter(Boolean);
+}
+export function endSession(cwd, commitMessage, discard = false) {
+    const session = loadSession(cwd);
+    if (!session)
+        throw new Error('No active session.');
+    const snapshotCount = session.snapshots.length;
+    if (discard || snapshotCount === 0) {
+        git(`checkout ${session.originalBranch}`, cwd);
+        gitSafe(`branch -D ${session.branch}`, cwd);
+        archiveSession(cwd, session, null, true);
+        cleanup(cwd);
+        return discard ? 'Session discarded. All changes dropped.' : 'Session ended with no changes.';
+    }
+    const msg = commitMessage ?? session.snapshots.map((s) => `- ${s.message}`).join('\n');
+    git(`checkout ${session.originalBranch}`, cwd);
+    git(`merge --squash ${session.branch}`, cwd);
+    git(`commit -m "${msg.replace(/"/g, '\\"')}"`, cwd);
+    const commitHash = git('rev-parse --short HEAD', cwd);
+    gitSafe(`branch -D ${session.branch}`, cwd);
+    for (const b of listBranches(cwd)) {
+        gitSafe(`branch -D ${b}`, cwd);
+    }
+    archiveSession(cwd, session, commitHash, false);
+    cleanup(cwd);
+    return `Committed ${snapshotCount} steps as one commit on ${session.originalBranch}.`;
+}
+export function status(cwd) {
+    return loadSession(cwd);
+}
+// ── History ───────────────────────────────────────────────────────────────
+export function log(cwd) {
+    const dir = historyDir(cwd);
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir)
+        .filter((f) => f.endsWith('.json'))
+        .map((f) => JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')))
+        .sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+}
+export function logDetail(cwd, sessionId) {
+    const filePath = path.join(historyDir(cwd), `${sessionId}.json`);
+    if (!fs.existsSync(filePath))
+        throw new Error(`Session "${sessionId}" not found in history.`);
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+function cleanup(cwd) {
+    const p = sessionPath(cwd);
+    if (fs.existsSync(p))
+        fs.unlinkSync(p);
+}

package/dist/watch.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ckpt watch — auto-snapshot mode.
+ *
+ * Watches the project for file changes. After a 2-second quiet period
+ * (no new changes), it auto-snapshots with a smart description.
+ * Zero friction — just run "ckpt watch" and forget about it.
+ */
+export declare function startWatch(cwd: string, debounceMs?: number): void;

package/dist/watch.js

@@ -0,0 +1,120 @@
+/**
+ * ckpt watch — auto-snapshot mode.
+ *
+ * Watches the project for file changes. After a 2-second quiet period
+ * (no new changes), it auto-snapshots with a smart description.
+ * Zero friction — just run "ckpt watch" and forget about it.
+ */
+import chokidar from 'chokidar';
+import path from 'path';
+import * as core from './core.js';
+export function startWatch(cwd, debounceMs = 2000) {
+    let session = core.status(cwd);
+    if (!session) {
+        session = core.startSession(cwd);
+        console.log(`⚡ Session started: ${session.id}`);
+    }
+    else {
+        console.log(`⚡ Resuming session: ${session.id}`);
+    }
+    console.log(`👀 Watching ${cwd}`);
+    console.log(`   Auto-snapshot after ${debounceMs / 1000}s of quiet.`);
+    console.log(`   Press Ctrl+C to stop.\n`);
+    let pending = [];
+    let timer = null;
+    const watcher = chokidar.watch(cwd, {
+        ignored: [
+            /(^|[/\\])\./,
+            /node_modules/,
+            /dist\//,
+            /build\//,
+        ],
+        persistent: true,
+        ignoreInitial: true,
+    });
+    const flush = () => {
+        if (pending.length === 0)
+            return;
+        const events = [...pending];
+        pending = [];
+        const label = buildSmartLabel(events);
+        try {
+            const snapshot = core.snap(cwd, label);
+            if (snapshot) {
+                const time = new Date().toLocaleTimeString();
+                console.log(`  ✓ Step ${snapshot.id}  ${time}  +${snapshot.additions} -${snapshot.deletions}  ${label}`);
+            }
+        }
+        catch (e) {
+            if (!e.message.includes('Nothing to snapshot')) {
+                console.error(`  ✗ ${e.message}`);
+            }
+        }
+    };
+    const onEvent = (type) => (filePath) => {
+        pending.push({ type, file: path.relative(cwd, filePath) });
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(flush, debounceMs);
+    };
+    watcher
+        .on('add', onEvent('add'))
+        .on('change', onEvent('change'))
+        .on('unlink', onEvent('unlink'));
+    const shutdown = () => {
+        console.log('\n⏹  Stopping watch...');
+        if (timer)
+            clearTimeout(timer);
+        if (pending.length > 0)
+            flush();
+        watcher.close().then(() => {
+            const s = core.status(cwd);
+            const count = s?.snapshots.length ?? 0;
+            console.log(`\n  Session ${session.id}: ${count} steps recorded.`);
+            console.log(`  Run "ckpt steps" to review.`);
+            console.log(`  Run "ckpt restore <step>" to go back.`);
+            console.log(`  Run "ckpt end" to commit everything.\n`);
+            process.exit(0);
+        });
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+// ── Smart labeling ────────────────────────────────────────────────────────
+const CATEGORY_MAP = {
+    'tests': ['.test.', '.spec.', '__tests__', 'test/', 'tests/'],
+    'styles': ['.css', '.scss', '.less', '.styled.'],
+    'config': ['package.json', 'tsconfig', '.eslint', '.prettier', 'vite.config', 'webpack.config', '.env'],
+    'components': ['/components/', '.tsx', '.jsx'],
+    'api': ['/api/', '/routes/', '/controllers/', '/handlers/'],
+    'types': ['.d.ts', '/types/', '/interfaces/'],
+    'docs': ['.md', 'README', 'CHANGELOG', 'LICENSE'],
+    'deps': ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'],
+};
+function categorizeFile(file) {
+    const lower = file.toLowerCase();
+    for (const [category, patterns] of Object.entries(CATEGORY_MAP)) {
+        if (patterns.some((p) => lower.includes(p)))
+            return category;
+    }
+    return null;
+}
+function buildSmartLabel(events) {
+    const added = events.filter((e) => e.type === 'add');
+    const changed = events.filter((e) => e.type === 'change');
+    const deleted = events.filter((e) => e.type === 'unlink');
+    const categories = new Set(events.map((e) => categorizeFile(e.file)).filter(Boolean));
+    let prefix = '';
+    if (categories.size === 1)
+        prefix = `[${[...categories][0]}] `;
+    else if (categories.size > 1)
+        prefix = `[${[...categories].join(', ')}] `;
+    const parts = [];
+    if (added.length > 0)
+        parts.push(added.length <= 2 ? `created ${added.map((e) => path.basename(e.file)).join(', ')}` : `created ${added.length} files`);
+    if (changed.length > 0)
+        parts.push(changed.length <= 2 ? `modified ${changed.map((e) => path.basename(e.file)).join(', ')}` : `modified ${changed.length} files`);
+    if (deleted.length > 0)
+        parts.push(deleted.length <= 2 ? `deleted ${deleted.map((e) => path.basename(e.file)).join(', ')}` : `deleted ${deleted.length} files`);
+    return prefix + (parts.join(', ') || 'file changes');
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@mohshomis/ckpt",
+  "version": "0.1.0",
+  "description": "Automatic checkpoints for AI coding sessions. Per-step undo, branching, and restore — on top of git.",
+  "type": "module",
+  "bin": {
+    "ckpt": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "git", "ai", "checkpoint", "undo", "version-control",
+    "cursor", "kiro", "claude", "copilot", "coding-agent",
+    "snapshot", "restore", "diff", "developer-tools"
+  ],
+  "author": "mohshomis",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mohshomis/ckpt"
+  },
+  "homepage": "https://github.com/mohshomis/ckpt#readme",
+  "dependencies": {
+    "chokidar": "^3.6.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}