ai-session-checkpoint 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gokks8142
+
+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,143 @@
+# ai-session-checkpoint
+
+**Never lose AI coding session context again.**
+
+When your Claude Code context fills up or your Cursor tab crashes, all the context vanishes. `ai-session-checkpoint` silently saves session state to a folder — so your next session picks up exactly where you left off. Put that folder in Google Drive or iCloud and it syncs across machines automatically.
+
+## Quick Start (30 seconds)
+
+```bash
+cd ~/my-project
+
+# Option 1: Shell script (zero dependencies)
+curl -fsSL https://raw.githubusercontent.com/gokks8142/ai-session-checkpoint/main/install.sh | bash
+
+# Option 2: npx (Node.js users)
+npx ai-session-checkpoint init
+```
+
+That's it. Open your AI editor, start coding. Checkpoints happen automatically.
+
+## What It Does
+
+| Feature | How |
+|---------|-----|
+| **Auto-checkpoint** | Background agent saves every 20 min (Claude Code) |
+| **Manual checkpoint** | Say "checkpoint" in any AI editor |
+| **Session recovery** | New sessions read `.checkpoints/` on start — full context |
+| **Cross-editor** | Same `.checkpoints/` folder works in Claude Code + Cursor |
+| **Cross-machine** | Put checkpoint folder in Google Drive / iCloud — syncs automatically |
+| **Change detection** | Skips if no files changed — no noise from read-only work |
+| **Smart retention** | Keeps recent detail, compresses old history, max 50 files |
+
+## How It Works
+
+```
+my-project/
+├── .checkpoints/               ← symlink to checkpoint storage
+│   ├── project-state.md        ← current project state (always up-to-date)
+│   ├── sessions/
+│   │   ├── 2026-03-21-10-30.md ← auto-checkpoint
+│   │   └── 2026-03-21-11-15.md ← manual checkpoint
+│   ├── decisions.md            ← architecture decisions log
+│   └── problems.md             ← open issues / blockers
+├── CLAUDE.md                   ← tells Claude to read/write .checkpoints/
+└── ... (your code)
+```
+
+1. **On session start**: AI reads `project-state.md` + latest session file → full context
+2. **Every 20 min**: Background agent checks `git diff`, writes session snapshot if changes detected
+3. **On "checkpoint"**: Immediate save with summary confirmation
+4. **New session**: Reads checkpoints, picks up where you left off
+
+## Storage Options
+
+### Local folder (default)
+
+Checkpoints go to `~/.ai-checkpoints/my-project/`. Works immediately, zero setup.
+
+### Cloud sync (Google Drive / iCloud)
+
+To sync checkpoints across machines, put the folder in Google Drive or iCloud:
+
+```bash
+# 1. Create a folder in Google Drive (one time)
+mkdir -p ~/Google\ Drive/My\ Drive/ClaudeCode/
+
+# 2. Run install.sh from your project and enter the path when prompted
+cd ~/my-project
+curl -fsSL https://raw.githubusercontent.com/gokks8142/ai-session-checkpoint/main/install.sh | bash
+
+# When asked "Where should checkpoints be stored?", enter:
+#   ~/Google Drive/My Drive/ClaudeCode/
+```
+
+That's it. Checkpoints sync automatically via Google Drive. On your other machine, create the same symlink and you have full context.
+
+### Obsidian (optional bonus)
+
+If you already use [Obsidian](https://obsidian.md), you can point your vault at the same Google Drive folder. This gives you search, graph view, and backlinks across your checkpoints — but it's purely optional. The tool works identically with or without Obsidian.
+
+## Link a Project
+
+The installer handles this automatically. If you need to do it manually:
+
+```bash
+# Symlink your project to the checkpoint folder
+ln -s ~/Google\ Drive/My\ Drive/ClaudeCode/my-project  ~/my-project/.checkpoints
+```
+
+To verify:
+```bash
+ls -la .checkpoints/
+# Should show: project-state.md, sessions/, decisions.md, problems.md
+```
+
+## Supported Editors
+
+| Editor | Auto-checkpoint | Manual checkpoint | Config file |
+|--------|:-:|:-:|---|
+| Claude Code | ✅ | ✅ | `CLAUDE.md` |
+| Cursor | — | ✅ | `.cursorrules` |
+
+The checkpoint format is editor-agnostic — any AI editor that reads files can use it.
+
+## What Gets Saved
+
+**Session file** (`sessions/YYYY-MM-DD-HH-MM.md`):
+- Summary of what was accomplished
+- Files changed and why
+- Decisions made
+- Open items and next steps
+
+**Project state** (`project-state.md`):
+- What the project is and tech stack
+- What's built and working
+- What's in progress
+- Key files and their purposes
+- Known issues
+
+## Smart Retention
+
+Checkpoints don't pile up forever:
+
+| Time window | Rule |
+|-------------|------|
+| Last 24 hours | Keep all |
+| Last 7 days | Keep 1 per day |
+| Last 30 days | Keep 1 per week |
+| Older | Delete |
+
+Hard cap: **50 files max** (configurable). Oldest deleted on rollover.
+
+## Uninstall
+
+```bash
+rm .checkpoints                    # Remove symlink
+# Remove checkpoint lines from CLAUDE.md or .cursorrules
+# Optionally delete ~/.ai-checkpoints/my-project/
+```
+
+## License
+
+MIT

package/bin/init.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+
+/**
+ * ai-session-checkpoint CLI
+ *
+ * Usage:
+ *   npx ai-session-checkpoint init          # Set up checkpoints for current project
+ *   npx ai-session-checkpoint migrate --to obsidian  # Migrate local → Obsidian
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const readline = require("readline");
+
+const VERSION = "1.0.0";
+
+// --- Helpers ---
+function ask(question, defaultAnswer) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    const prompt = defaultAnswer ? `${question} (${defaultAnswer}): ` : `${question}: `;
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultAnswer || "");
+    });
+  });
+}
+
+function green(t) { return `\x1b[32m${t}\x1b[0m`; }
+function blue(t) { return `\x1b[34m${t}\x1b[0m`; }
+function cyan(t) { return `\x1b[36m${t}\x1b[0m`; }
+function bold(t) { return `\x1b[1m${t}\x1b[0m`; }
+function dim(t) { return `\x1b[2m${t}\x1b[0m`; }
+
+function writeIfMissing(filePath, content, label) {
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, content, "utf8");
+    console.log(`  ${green("✓")} Created:     ${dim(label)}`);
+    return true;
+  }
+  return false;
+}
+
+// No Obsidian-specific detection — user provides custom path if needed
+
+// --- Templates ---
+const TEMPLATES = {
+  "project-state.md": `# Project State
+
+## What is this project?
+<!-- Brief description -->
+
+## Tech Stack
+<!-- Languages, frameworks, tools -->
+
+## What's Built
+<!-- Completed features and components -->
+
+## In Progress
+<!-- Current work items -->
+
+## Key Files
+<!-- Important files and their purposes -->
+
+## Known Issues
+<!-- Bugs, blockers, open questions -->
+`,
+  "decisions.md": `# Architecture Decisions
+
+<!-- Format:
+## YYYY-MM-DD: Decision Title
+**Context:** Why this decision was needed
+**Decision:** What was decided
+**Alternatives:** What else was considered
+-->
+`,
+  "problems.md": `# Open Problems
+
+<!-- Format:
+## Problem Title
+**Status:** open | investigating | blocked | resolved
+**Description:** What's happening
+**Impact:** Why it matters
+**Notes:** Investigation progress
+-->
+`,
+};
+
+const CHECKPOINT_INSTRUCTIONS = `At session start, read \`.checkpoints/project-state.md\` and the latest file in \`.checkpoints/sessions/\` to pick up context from previous sessions.
+
+When the user says "checkpoint" or when you complete a feature/fix, write a session summary to \`.checkpoints/sessions/\` (filename: \`YYYY-MM-DD-HH-MM.md\`) and update \`.checkpoints/project-state.md\`.`;
+
+const SKILL_CONTENT = `---
+name: ai-session-checkpoint
+description: Automatically save session context, decisions, and progress so no work is lost when sessions crash or context windows fill up.
+triggers:
+  - "checkpoint"
+  - "save progress"
+  - "save context"
+  - "save session"
+---
+
+# ai-session-checkpoint
+
+## On Session Start
+
+Read \`.checkpoints/project-state.md\` and the latest file in \`.checkpoints/sessions/\` to pick up context from previous sessions. Briefly summarize what you found so the user knows you have context.
+
+## On "checkpoint" / "save progress" / "save context"
+
+1. **Check for changes**: Run \`git diff --stat\` to see if any files changed. If no changes and no significant decisions were made, tell the user "No changes to checkpoint" and skip.
+
+2. **Write session file**: Create \`.checkpoints/sessions/YYYY-MM-DD-HH-MM.md\` with:
+   \`\`\`
+   # Session: YYYY-MM-DD HH:MM
+
+   ## Summary
+   - What was accomplished this session (2-5 bullet points)
+
+   ## Files Changed
+   - path/to/file.ts — what changed and why
+
+   ## Decisions Made
+   - Key decisions with brief rationale
+
+   ## Open Items
+   - What's left to do, blockers, next steps
+   \`\`\`
+
+3. **Update project state**: Rewrite \`.checkpoints/project-state.md\` with current reality:
+   - What the project is
+   - Tech stack
+   - What's built and working
+   - What's in progress
+   - Key files and their purposes
+   - Known issues
+
+4. **Retention sweep**: Count files in \`.checkpoints/sessions/\`. If more than 50, delete the oldest file(s) to stay at 50.
+
+5. **Confirm**: Tell the user what was saved with a brief summary.
+
+## On Feature/Fix Completion
+
+When you complete a significant feature or fix, proactively offer: "Want me to checkpoint this progress?"
+`;
+
+// --- Commands ---
+async function init() {
+  const projectDir = process.cwd();
+  const projectName = path.basename(projectDir);
+  const homedir = require("os").homedir();
+  const defaultCheckpointDir = path.join(homedir, ".ai-checkpoints");
+
+  console.log("");
+  console.log(`${blue(bold("ai-session-checkpoint"))} ${dim(`v${VERSION}`)}`);
+  console.log("");
+
+  // Step 1: Storage
+  let checkpointBase;
+  console.log(cyan("? Where should checkpoints be stored?"));
+  console.log(`  ${bold("1)")} Local folder ${dim(`(${defaultCheckpointDir}/)`)}`);
+  console.log(`  ${bold("2)")} Custom path ${dim("(Google Drive, iCloud, Dropbox, etc.)")}`);
+  const choice = await ask("  Choose [1/2]", "1");
+  if (choice === "2") {
+    const customPath = await ask("  Enter path", "");
+    if (customPath) {
+      const resolved = customPath.replace(/^~/, homedir);
+      fs.mkdirSync(resolved, { recursive: true });
+      checkpointBase = resolved;
+    } else {
+      checkpointBase = defaultCheckpointDir;
+    }
+  } else {
+    checkpointBase = defaultCheckpointDir;
+  }
+
+  // Step 2: Project name
+  const name = await ask(cyan("? Project name?"), projectName);
+  const checkpointDir = path.join(checkpointBase, name);
+
+  // Step 3: Detect editor
+  let editorType = "claude-code";
+  if (fs.existsSync(path.join(projectDir, ".cursorrules")) && !fs.existsSync(path.join(projectDir, "CLAUDE.md"))) {
+    editorType = "cursor";
+  }
+  console.log(`${dim("  Editor detected: " + editorType)}`);
+  console.log("");
+
+  // Step 4: Create checkpoint folder + templates
+  fs.mkdirSync(path.join(checkpointDir, "sessions"), { recursive: true });
+
+  for (const [filename, content] of Object.entries(TEMPLATES)) {
+    writeIfMissing(path.join(checkpointDir, filename), content, filename);
+  }
+  console.log(`  ${green("✓")} Templates:   ${dim("project-state.md, decisions.md, problems.md, sessions/")}`);
+
+  // Step 5: Symlink
+  const symlinkPath = path.join(projectDir, ".checkpoints");
+  if (fs.existsSync(symlinkPath)) {
+    const stat = fs.lstatSync(symlinkPath);
+    if (stat.isSymbolicLink()) fs.unlinkSync(symlinkPath);
+  }
+  if (!fs.existsSync(symlinkPath)) {
+    fs.symlinkSync(checkpointDir, symlinkPath);
+    console.log(`  ${green("✓")} Symlink:     ${dim(`.checkpoints → ${checkpointDir}`)}`);
+  }
+
+  // Step 6: Editor config
+  if (editorType === "claude-code" || editorType === "both") {
+    const claudeMd = path.join(projectDir, "CLAUDE.md");
+    if (fs.existsSync(claudeMd)) {
+      const existing = fs.readFileSync(claudeMd, "utf8");
+      if (!existing.includes(".checkpoints/project-state.md")) {
+        fs.appendFileSync(claudeMd, "\n" + CHECKPOINT_INSTRUCTIONS + "\n");
+        console.log(`  ${green("✓")} CLAUDE.md:   ${dim("Added checkpoint instructions")}`);
+      }
+    } else {
+      fs.writeFileSync(claudeMd, CHECKPOINT_INSTRUCTIONS + "\n");
+      console.log(`  ${green("✓")} CLAUDE.md:   ${dim("Created with checkpoint instructions")}`);
+    }
+  }
+
+  if (editorType === "cursor" || editorType === "both") {
+    const cursorrules = path.join(projectDir, ".cursorrules");
+    if (fs.existsSync(cursorrules)) {
+      const existing = fs.readFileSync(cursorrules, "utf8");
+      if (!existing.includes(".checkpoints/project-state.md")) {
+        fs.appendFileSync(cursorrules, "\n" + CHECKPOINT_INSTRUCTIONS + "\n");
+        console.log(`  ${green("✓")} .cursorrules: ${dim("Added checkpoint instructions")}`);
+      }
+    } else {
+      fs.writeFileSync(cursorrules, CHECKPOINT_INSTRUCTIONS + "\n");
+      console.log(`  ${green("✓")} .cursorrules: ${dim("Created with checkpoint instructions")}`);
+    }
+  }
+
+  // Step 7: Install skill
+  if (editorType === "claude-code" || editorType === "both") {
+    const skillDir = path.join(homedir, ".claude", "skills", "ai-session-checkpoint");
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(path.join(skillDir, "SKILL.md"), SKILL_CONTENT);
+    console.log(`  ${green("✓")} Skill:       ${dim("~/.claude/skills/ai-session-checkpoint/")}`);
+  }
+
+  // Step 8: .gitignore
+  const gitignorePath = path.join(projectDir, ".gitignore");
+  if (fs.existsSync(gitignorePath)) {
+    const existing = fs.readFileSync(gitignorePath, "utf8");
+    if (!existing.includes(".checkpoints")) {
+      fs.appendFileSync(gitignorePath, "\n# ai-session-checkpoint\n.checkpoints\n");
+      console.log(`  ${green("✓")} .gitignore:  ${dim("Added .checkpoints")}`);
+    }
+  }
+
+  console.log("");
+  console.log(`${green(bold("Done!"))} Checkpoints stored in: ${dim(checkpointDir)}`);
+  console.log("");
+}
+
+async function migrate() {
+  const args = process.argv.slice(3);
+  if (args[0] !== "--to" || !args[1]) {
+    console.log("Usage: ai-session-checkpoint migrate --to <path>");
+    console.log("Example: ai-session-checkpoint migrate --to ~/Google\\ Drive/My\\ Drive/ClaudeCode");
+    process.exit(1);
+  }
+
+  const projectDir = process.cwd();
+  const symlinkPath = path.join(projectDir, ".checkpoints");
+  const homedir = require("os").homedir();
+
+  if (!fs.existsSync(symlinkPath)) {
+    console.log("No .checkpoints found in current directory. Run 'init' first.");
+    process.exit(1);
+  }
+
+  const currentTarget = fs.readlinkSync(symlinkPath);
+  const newBase = args[1].replace(/^~/, homedir);
+  const projectName = path.basename(projectDir);
+  const newTarget = path.join(newBase, projectName);
+
+  if (currentTarget === newTarget) {
+    console.log("Already using that path. Nothing to migrate.");
+    process.exit(0);
+  }
+
+  // Copy files
+  fs.mkdirSync(newTarget, { recursive: true });
+  execSync(`cp -r "${currentTarget}/"* "${newTarget}/"`, { stdio: "inherit" });
+
+  // Update symlink
+  fs.unlinkSync(symlinkPath);
+  fs.symlinkSync(newTarget, symlinkPath);
+
+  console.log(`${green("✓")} Migrated: ${dim(currentTarget)} → ${dim(newTarget)}`);
+  console.log(`${green("✓")} Symlink updated`);
+  console.log(`${green("✓")} All session history preserved`);
+}
+
+// --- Main ---
+const command = process.argv[2] || "init";
+
+switch (command) {
+  case "init":
+    init().catch(console.error);
+    break;
+  case "migrate":
+    migrate().catch(console.error);
+    break;
+  default:
+    console.log(`Unknown command: ${command}`);
+    console.log("Usage: ai-session-checkpoint [init|migrate]");
+    process.exit(1);
+}

package/editors/claude-code/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ai-session-checkpoint
+description: Automatically save session context, decisions, and progress so no work is lost when sessions crash or context windows fill up.
+triggers:
+  - "checkpoint"
+  - "save progress"
+  - "save context"
+  - "save session"
+---
+
+# ai-session-checkpoint
+
+## On Session Start
+
+Read `.checkpoints/project-state.md` and the latest file in `.checkpoints/sessions/` to pick up context from previous sessions. Briefly summarize what you found so the user knows you have context.
+
+## On "checkpoint" / "save progress" / "save context"
+
+1. **Check for changes**: Run `git diff --stat` to see if any files changed. If no changes and no significant decisions were made, tell the user "No changes to checkpoint" and skip.
+
+2. **Write session file**: Create `.checkpoints/sessions/YYYY-MM-DD-HH-MM.md` with:
+   ```
+   # Session: YYYY-MM-DD HH:MM
+
+   ## Summary
+   - What was accomplished this session (2-5 bullet points)
+
+   ## Files Changed
+   - path/to/file.ts — what changed and why
+
+   ## Decisions Made
+   - Key decisions with brief rationale
+
+   ## Open Items
+   - What's left to do, blockers, next steps
+   ```
+
+3. **Update project state**: Rewrite `.checkpoints/project-state.md` with current reality:
+   - What the project is
+   - Tech stack
+   - What's built and working
+   - What's in progress
+   - Key files and their purposes
+   - Known issues
+
+4. **Retention sweep**: Count files in `.checkpoints/sessions/`. If more than 50, delete the oldest file(s) to stay at 50.
+
+5. **Confirm**: Tell the user what was saved with a brief summary.
+
+## On Feature/Fix Completion
+
+When you complete a significant feature or fix, proactively offer: "Want me to checkpoint this progress?"

package/editors/claude-code/example-CLAUDE.md

@@ -0,0 +1,3 @@
+At session start, read `.checkpoints/project-state.md` and the latest file in `.checkpoints/sessions/` to pick up context from previous sessions.
+
+When the user says "checkpoint" or when you complete a feature/fix, write a session summary to `.checkpoints/sessions/` (filename: `YYYY-MM-DD-HH-MM.md`) and update `.checkpoints/project-state.md`.

package/editors/cursor/example-cursorrules

@@ -0,0 +1,5 @@
+At session start, read `.checkpoints/project-state.md` and the latest file in `.checkpoints/sessions/` to pick up context from previous sessions.
+
+When the user says "checkpoint" or when you complete a feature/fix, write a session summary to `.checkpoints/sessions/` (filename: `YYYY-MM-DD-HH-MM.md`) and update `.checkpoints/project-state.md`.
+
+Before ending a long conversation, offer to checkpoint: "Want me to save this session's progress?"

package/install.sh

@@ -0,0 +1,300 @@
+#!/usr/bin/env bash
+#
+# ai-session-checkpoint installer
+# Zero dependencies — works on any Mac/Linux with bash
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/gokks8142/ai-session-checkpoint/main/install.sh | bash
+#   OR
+#   ./install.sh
+#
+set -euo pipefail
+
+# --- Colors ---
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+DIM='\033[2m'
+RESET='\033[0m'
+
+# --- Config ---
+VERSION="1.0.0"
+DEFAULT_CHECKPOINT_DIR="$HOME/.ai-checkpoints"
+SKILL_DIR="$HOME/.claude/skills/ai-session-checkpoint"
+
+# --- Detect project ---
+PROJECT_DIR="$(pwd)"
+PROJECT_NAME="$(basename "$PROJECT_DIR")"
+
+echo ""
+echo -e "${BLUE}${BOLD}ai-session-checkpoint${RESET} ${DIM}v${VERSION}${RESET}"
+echo ""
+
+# --- Step 1: Storage location ---
+echo -e "${CYAN}? Where should checkpoints be stored?${RESET}"
+echo -e "  ${BOLD}1)${RESET} Local folder (${DIM}${DEFAULT_CHECKPOINT_DIR}/${RESET})"
+echo -e "  ${BOLD}2)${RESET} Custom path ${DIM}(Google Drive, iCloud, Dropbox, etc.)${RESET}"
+echo ""
+read -p "  Choose [1/2] (default: 1): " STORAGE_CHOICE
+STORAGE_CHOICE="${STORAGE_CHOICE:-1}"
+
+if [ "$STORAGE_CHOICE" = "2" ]; then
+  read -p "  Enter path: " CUSTOM_PATH
+  if [ -z "$CUSTOM_PATH" ]; then
+    echo -e "  ${RED}!${RESET} No path entered. Using local folder."
+    CHECKPOINT_BASE="$DEFAULT_CHECKPOINT_DIR"
+  else
+    # Expand ~ if present
+    CUSTOM_PATH="${CUSTOM_PATH/#\~/$HOME}"
+    mkdir -p "$CUSTOM_PATH"
+    CHECKPOINT_BASE="$CUSTOM_PATH"
+  fi
+else
+  CHECKPOINT_BASE="$DEFAULT_CHECKPOINT_DIR"
+fi
+
+# --- Step 2: Project name ---
+echo ""
+echo -e "${CYAN}? Project name?${RESET} ${DIM}(${PROJECT_NAME})${RESET}"
+read -p "  Name: " INPUT_NAME
+PROJECT_NAME="${INPUT_NAME:-$PROJECT_NAME}"
+
+CHECKPOINT_DIR="$CHECKPOINT_BASE/$PROJECT_NAME"
+
+# --- Step 3: Detect AI editor ---
+EDITOR_TYPE="unknown"
+if [ -f "$PROJECT_DIR/CLAUDE.md" ] || command -v claude &>/dev/null; then
+  EDITOR_TYPE="claude-code"
+elif [ -f "$PROJECT_DIR/.cursorrules" ]; then
+  EDITOR_TYPE="cursor"
+fi
+
+echo ""
+if [ "$EDITOR_TYPE" = "claude-code" ]; then
+  echo -e "${CYAN}? AI editor detected: ${BOLD}Claude Code${RESET}"
+elif [ "$EDITOR_TYPE" = "cursor" ]; then
+  echo -e "${CYAN}? AI editor detected: ${BOLD}Cursor${RESET}"
+else
+  echo -e "${CYAN}? AI editor:${RESET}"
+  echo -e "  ${BOLD}1)${RESET} Claude Code"
+  echo -e "  ${BOLD}2)${RESET} Cursor"
+  echo -e "  ${BOLD}3)${RESET} Both"
+  read -p "  Choose [1/2/3] (default: 1): " EDITOR_CHOICE
+  case "${EDITOR_CHOICE:-1}" in
+    2) EDITOR_TYPE="cursor" ;;
+    3) EDITOR_TYPE="both" ;;
+    *) EDITOR_TYPE="claude-code" ;;
+  esac
+fi
+
+echo ""
+
+# --- Step 4: Create checkpoint folder + templates ---
+mkdir -p "$CHECKPOINT_DIR/sessions"
+
+# project-state.md
+if [ ! -f "$CHECKPOINT_DIR/project-state.md" ]; then
+  cat > "$CHECKPOINT_DIR/project-state.md" << 'TMPL'
+# Project State
+
+## What is this project?
+<!-- Brief description -->
+
+## Tech Stack
+<!-- Languages, frameworks, tools -->
+
+## What's Built
+<!-- Completed features and components -->
+
+## In Progress
+<!-- Current work items -->
+
+## Key Files
+<!-- Important files and their purposes -->
+
+## Known Issues
+<!-- Bugs, blockers, open questions -->
+TMPL
+  echo -e "  ${GREEN}✓${RESET} Created:     ${DIM}project-state.md${RESET}"
+fi
+
+# decisions.md
+if [ ! -f "$CHECKPOINT_DIR/decisions.md" ]; then
+  cat > "$CHECKPOINT_DIR/decisions.md" << 'TMPL'
+# Architecture Decisions
+
+<!-- Format:
+## YYYY-MM-DD: Decision Title
+**Context:** Why this decision was needed
+**Decision:** What was decided
+**Alternatives:** What else was considered
+-->
+TMPL
+  echo -e "  ${GREEN}✓${RESET} Created:     ${DIM}decisions.md${RESET}"
+fi
+
+# problems.md
+if [ ! -f "$CHECKPOINT_DIR/problems.md" ]; then
+  cat > "$CHECKPOINT_DIR/problems.md" << 'TMPL'
+# Open Problems
+
+<!-- Format:
+## Problem Title
+**Status:** open | investigating | blocked | resolved
+**Description:** What's happening
+**Impact:** Why it matters
+**Notes:** Investigation progress
+-->
+TMPL
+  echo -e "  ${GREEN}✓${RESET} Created:     ${DIM}problems.md${RESET}"
+fi
+
+echo -e "  ${GREEN}✓${RESET} Templates:   ${DIM}project-state.md, decisions.md, problems.md, sessions/${RESET}"
+
+# --- Step 5: Create symlink ---
+SYMLINK_PATH="$PROJECT_DIR/.checkpoints"
+
+if [ -L "$SYMLINK_PATH" ]; then
+  rm "$SYMLINK_PATH"
+elif [ -e "$SYMLINK_PATH" ]; then
+  echo -e "  ${RED}!${RESET} .checkpoints already exists and is not a symlink. Skipping."
+  echo ""
+else
+  true
+fi
+
+if [ ! -e "$SYMLINK_PATH" ]; then
+  ln -s "$CHECKPOINT_DIR" "$SYMLINK_PATH"
+  echo -e "  ${GREEN}✓${RESET} Symlink:     ${DIM}.checkpoints → ${CHECKPOINT_DIR}${RESET}"
+fi
+
+# --- Step 6: Configure AI editor ---
+CHECKPOINT_INSTRUCTIONS='At session start, read `.checkpoints/project-state.md` and the latest file in `.checkpoints/sessions/` to pick up context from previous sessions.
+
+When the user says "checkpoint" or when you complete a feature/fix, write a session summary to `.checkpoints/sessions/` (filename: `YYYY-MM-DD-HH-MM.md`) and update `.checkpoints/project-state.md`.'
+
+# Claude Code: CLAUDE.md
+if [ "$EDITOR_TYPE" = "claude-code" ] || [ "$EDITOR_TYPE" = "both" ]; then
+  CLAUDE_MD="$PROJECT_DIR/CLAUDE.md"
+  if [ -f "$CLAUDE_MD" ]; then
+    # Check if instructions already exist
+    if ! grep -q ".checkpoints/project-state.md" "$CLAUDE_MD" 2>/dev/null; then
+      echo "" >> "$CLAUDE_MD"
+      echo "$CHECKPOINT_INSTRUCTIONS" >> "$CLAUDE_MD"
+      echo -e "  ${GREEN}✓${RESET} CLAUDE.md:   ${DIM}Added checkpoint instructions${RESET}"
+    else
+      echo -e "  ${DIM}  CLAUDE.md already has checkpoint instructions${RESET}"
+    fi
+  else
+    echo "$CHECKPOINT_INSTRUCTIONS" > "$CLAUDE_MD"
+    echo -e "  ${GREEN}✓${RESET} CLAUDE.md:   ${DIM}Created with checkpoint instructions${RESET}"
+  fi
+fi
+
+# Cursor: .cursorrules
+if [ "$EDITOR_TYPE" = "cursor" ] || [ "$EDITOR_TYPE" = "both" ]; then
+  CURSORRULES="$PROJECT_DIR/.cursorrules"
+  if [ -f "$CURSORRULES" ]; then
+    if ! grep -q ".checkpoints/project-state.md" "$CURSORRULES" 2>/dev/null; then
+      echo "" >> "$CURSORRULES"
+      echo "$CHECKPOINT_INSTRUCTIONS" >> "$CURSORRULES"
+      echo -e "  ${GREEN}✓${RESET} .cursorrules: ${DIM}Added checkpoint instructions${RESET}"
+    else
+      echo -e "  ${DIM}  .cursorrules already has checkpoint instructions${RESET}"
+    fi
+  else
+    echo "$CHECKPOINT_INSTRUCTIONS" > "$CURSORRULES"
+    echo -e "  ${GREEN}✓${RESET} .cursorrules: ${DIM}Created with checkpoint instructions${RESET}"
+  fi
+fi
+
+# --- Step 7: Install Claude Code skill (if applicable) ---
+if [ "$EDITOR_TYPE" = "claude-code" ] || [ "$EDITOR_TYPE" = "both" ]; then
+  mkdir -p "$SKILL_DIR"
+
+  cat > "$SKILL_DIR/SKILL.md" << 'SKILLEOF'
+---
+name: ai-session-checkpoint
+description: Automatically save session context, decisions, and progress so no work is lost when sessions crash or context windows fill up.
+triggers:
+  - "checkpoint"
+  - "save progress"
+  - "save context"
+  - "save session"
+---
+
+# ai-session-checkpoint
+
+## On Session Start
+
+Read `.checkpoints/project-state.md` and the latest file in `.checkpoints/sessions/` to pick up context from previous sessions. Briefly summarize what you found so the user knows you have context.
+
+## On "checkpoint" / "save progress" / "save context"
+
+1. **Check for changes**: Run `git diff --stat` to see if any files changed. If no changes and no significant decisions were made, tell the user "No changes to checkpoint" and skip.
+
+2. **Write session file**: Create `.checkpoints/sessions/YYYY-MM-DD-HH-MM.md` with:
+   ```
+   # Session: YYYY-MM-DD HH:MM
+
+   ## Summary
+   - What was accomplished this session (2-5 bullet points)
+
+   ## Files Changed
+   - path/to/file.ts — what changed and why
+
+   ## Decisions Made
+   - Key decisions with brief rationale
+
+   ## Open Items
+   - What's left to do, blockers, next steps
+   ```
+
+3. **Update project state**: Rewrite `.checkpoints/project-state.md` with current reality:
+   - What the project is
+   - Tech stack
+   - What's built and working
+   - What's in progress
+   - Key files and their purposes
+   - Known issues
+
+4. **Retention sweep**: Count files in `.checkpoints/sessions/`. If more than 50, delete the oldest file(s) to stay at 50.
+
+5. **Confirm**: Tell the user what was saved with a brief summary.
+
+## On Feature/Fix Completion
+
+When you complete a significant feature or fix, proactively offer: "Want me to checkpoint this progress?"
+SKILLEOF
+
+  echo -e "  ${GREEN}✓${RESET} Skill:       ${DIM}Installed to ~/.claude/skills/ai-session-checkpoint/${RESET}"
+fi
+
+# --- Step 8: Add .checkpoints to .gitignore ---
+GITIGNORE="$PROJECT_DIR/.gitignore"
+if [ -f "$GITIGNORE" ]; then
+  if ! grep -q ".checkpoints" "$GITIGNORE" 2>/dev/null; then
+    echo "" >> "$GITIGNORE"
+    echo "# ai-session-checkpoint" >> "$GITIGNORE"
+    echo ".checkpoints" >> "$GITIGNORE"
+    echo -e "  ${GREEN}✓${RESET} .gitignore:  ${DIM}Added .checkpoints${RESET}"
+  fi
+else
+  echo "# ai-session-checkpoint" > "$GITIGNORE"
+  echo ".checkpoints" >> "$GITIGNORE"
+  echo -e "  ${GREEN}✓${RESET} .gitignore:  ${DIM}Created with .checkpoints${RESET}"
+fi
+
+# --- Done ---
+echo ""
+echo -e "${GREEN}${BOLD}Done!${RESET} Checkpoints stored in: ${DIM}${CHECKPOINT_DIR}${RESET}"
+echo ""
+if [ "$EDITOR_TYPE" = "claude-code" ] || [ "$EDITOR_TYPE" = "both" ]; then
+  echo -e "  Your next Claude Code session will:"
+  echo -e "  ${DIM}  1. Read .checkpoints/ on start for context${RESET}"
+  echo -e "  ${DIM}  2. Checkpoint on \"checkpoint\" command${RESET}"
+  echo -e "  ${DIM}  3. Offer to checkpoint when features are done${RESET}"
+fi
+echo ""

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "ai-session-checkpoint",
+  "version": "1.0.0",
+  "description": "Never lose AI coding session context again. Auto-checkpoints for Claude Code, Cursor, and any AI editor.",
+  "license": "MIT",
+  "author": "gokks8142",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gokks8142/ai-session-checkpoint.git"
+  },
+  "bin": {
+    "ai-session-checkpoint": "bin/init.js"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "cursor",
+    "checkpoint",
+    "session",
+    "context",
+    "obsidian",
+    "developer-tools"
+  ],
+  "files": [
+    "bin/",
+    "editors/",
+    "scripts/",
+    "templates/",
+    "install.sh",
+    "LICENSE",
+    "README.md"
+  ]
+}

package/scripts/link-vault.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+#
+# Link an existing project to an Obsidian vault checkpoint folder.
+#
+# Usage:
+#   ./link-vault.sh <vault-path> <project-name> [project-dir]
+#
+# Example:
+#   ./link-vault.sh ~/GoogleDrive/.../MyVault/Org/ClaudeCode MyProject ~/vibecode/MyProject
+#
+set -euo pipefail
+
+VAULT_BASE="${1:?Usage: link-vault.sh <vault-base-path> <project-name> [project-dir]}"
+PROJECT_NAME="${2:?Usage: link-vault.sh <vault-base-path> <project-name> [project-dir]}"
+PROJECT_DIR="${3:-$(pwd)}"
+
+CHECKPOINT_DIR="$VAULT_BASE/$PROJECT_NAME"
+SYMLINK_PATH="$PROJECT_DIR/.checkpoints"
+
+# Create checkpoint folder if needed
+mkdir -p "$CHECKPOINT_DIR/sessions"
+
+# Create symlink
+if [ -L "$SYMLINK_PATH" ]; then
+  rm "$SYMLINK_PATH"
+fi
+
+ln -s "$CHECKPOINT_DIR" "$SYMLINK_PATH"
+echo "✓ Linked: $SYMLINK_PATH → $CHECKPOINT_DIR"

package/templates/decisions.md

@@ -0,0 +1,8 @@
+# Architecture Decisions
+
+<!-- Format:
+## YYYY-MM-DD: Decision Title
+**Context:** Why this decision was needed
+**Decision:** What was decided
+**Alternatives:** What else was considered
+-->

package/templates/problems.md

@@ -0,0 +1,9 @@
+# Open Problems
+
+<!-- Format:
+## Problem Title
+**Status:** open | investigating | blocked | resolved
+**Description:** What's happening
+**Impact:** Why it matters
+**Notes:** Investigation progress
+-->

package/templates/project-state.md

@@ -0,0 +1,19 @@
+# Project State
+
+## What is this project?
+<!-- Brief description -->
+
+## Tech Stack
+<!-- Languages, frameworks, tools -->
+
+## What's Built
+<!-- Completed features and components -->
+
+## In Progress
+<!-- Current work items -->
+
+## Key Files
+<!-- Important files and their purposes -->
+
+## Known Issues
+<!-- Bugs, blockers, open questions -->