@vibe-x/agent-better-checkpoint 0.1.1 → 0.3.0

package/README.md

@@ -1,4 +1,4 @@
-# Agent Better Checkpoint
+# Agent Better Checkpoint (ABC)
 
 **One-line install, zero config.** Turns AI agent edits into transparent, queryable Git commits.
 
@@ -6,6 +6,8 @@
 npx @vibe-x/agent-better-checkpoint
 ```
 
+![Agent Better Checkpoint](./assets/agent-better-checkpoint.png)
+
 That's it. Your AI coding assistant (Cursor, Claude Code) will now auto-commit every meaningful edit with semantic messages and structured metadata — no more opaque checkpoints.
 
 ---
@@ -40,6 +42,19 @@ git log --format="%(trailers:key=Agent,valueonly)"     # by agent
 git log --grep="User-Prompt:.*registration"            # by prompt keyword
 ```
 
+### Works with Your Favorite Git Tools
+
+Since every checkpoint is a standard Git commit, the entire Git ecosystem is at your disposal — what was once a hidden, platform-specific checkpoint becomes a first-class citizen you can browse, search, diff, and rebase.
+
+| Tool | Type | What You Get |
+|------|------|-------------|
+| [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) | VS Code / Cursor Extension | Inline blame, file history, visual commit graph, interactive rebase — see *who* (you or the AI) changed *what* and *when*, right in the editor |
+| [lazygit](https://github.com/jesseduffield/lazygit) | Terminal UI | Fast keyboard-driven staging, diff browsing, cherry-pick, and rebase across checkpoint commits |
+| [tig](https://github.com/jonas/tig) | Terminal UI | Lightweight ncurses Git log viewer, great for quickly scanning checkpoint history |
+| [GitHub / GitLab Web UI](https://github.com) | Web | Browse, compare, and share checkpoint history online after pushing |
+
+For example, with **GitLens in Cursor** you can hover any line to see which checkpoint introduced it and the original user prompt, view all checkpoints for a file in a timeline, or search commits by `checkpoint(` prefix and `User-Prompt` trailer content.
+
 ---
 
 ## How It Works
@@ -81,6 +96,28 @@ npx @vibe-x/agent-better-checkpoint --platform cursor
 npx @vibe-x/agent-better-checkpoint --platform claude
 ```
 
+### Project-local Install
+
+Install scripts into your project for self-contained setup (commit with repo):
+
+```bash
+cd /path/to/your/project
+npx @vibe-x/agent-better-checkpoint --target .
+```
+
+Or specify a target directory:
+
+```bash
+npx @vibe-x/agent-better-checkpoint --target /path/to/your/project
+```
+
+Uninstall project-local only:
+
+```bash
+npx @vibe-x/agent-better-checkpoint --uninstall --target .
+npx @vibe-x/agent-better-checkpoint --uninstall --target /path/to/project
+```
+
 ### Via [skills.sh](https://skills.sh)
 
 ```bash
@@ -93,11 +130,13 @@ The AI agent will auto-bootstrap the runtime scripts on first use.
 
 | Location | Content |
 |----------|---------|
-| `~/.agent-better-checkpoint/scripts/` | Commit script (`checkpoint.sh` / `.ps1`) |
-| `~/.agent-better-checkpoint/hooks/stop/` | Stop hook (`check_uncommitted.sh` / `.ps1`) |
+| `~/.vibe-x/agent-better-checkpoint/scripts/` | Commit script (`checkpoint.sh` / `.ps1`) |
+| `~/.vibe-x/agent-better-checkpoint/hooks/stop/` | Stop hook (`check_uncommitted.sh` / `.ps1`) |
 | Platform skill directory | `SKILL.md` — AI agent instructions |
 | Platform hook config | Stop hook registration |
 
+> **Project-local mode**: Projects can also commit `.vibe-x/agent-better-checkpoint/` (config + scripts) for self-contained setup. When present, the global hook delegates to the project-local scripts automatically.
+
 ### Uninstall
 
 ```bash

package/bin/cli.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 /**
- * agent-better-checkpoint 安装器 (Node.js)
+ * agent-better-checkpoint installer (Node.js)
  *
- * 通过 npx 一键安装 checkpoint 脚本、stop hook 和 SKILL.md 到用户环境。
- * 按平台（macOS/Linux vs Windows）选择性部署对应脚本。
+ * One-click install via npx: checkpoint scripts, stop hook, and SKILL.md to user env.
+ * Deploys platform-specific scripts (macOS/Linux vs Windows).
  *
  * Usage:
  *   npx @vibe-x/agent-better-checkpoint
@@ -18,26 +18,27 @@ import { homedir, platform } from 'node:os';
 import { fileURLToPath } from 'node:url';
 
 // ============================================================
-// 路径常量
+// Path constants
 // ============================================================
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PKG_ROOT = resolve(__dirname, '..');
 
-const INSTALL_BASE = join(homedir(), '.agent-better-checkpoint');
+const INSTALL_BASE = join(homedir(), '.vibe-x', 'agent-better-checkpoint');
 const SKILL_NAME = 'agent-better-checkpoint';
 
-// 包内源文件路径
+// In-package source paths
 const PLATFORM_DIR = join(PKG_ROOT, 'platform');
 const SKILL_SRC = join(PKG_ROOT, 'skill', 'SKILL.md');
+const CONFIG_TEMPLATE = join(PLATFORM_DIR, 'config.template.yml');
 
 // ============================================================
-// 参数解析
+// Argument parsing
 // ============================================================
 
 function parseArgs(argv) {
-  const args = { platform: null, uninstall: false };
+  const args = { platform: null, uninstall: false, target: null };
   for (let i = 2; i < argv.length; i++) {
     switch (argv[i]) {
       case '--platform':
@@ -47,6 +48,13 @@ function parseArgs(argv) {
           process.exit(1);
         }
         break;
+      case '--target':
+        args.target = argv[++i];
+        if (!args.target) {
+          console.error('Error: --target requires a path argument');
+          process.exit(1);
+        }
+        break;
       case '--uninstall':
         args.uninstall = true;
         break;
@@ -73,18 +81,19 @@ Usage:
 
 Options:
   --platform <cursor|claude>  Target AI platform (auto-detected if omitted)
+  --target <path>             Install to specified project directory (. for cwd)
   --uninstall                 Remove installed files and hook registrations
   -h, --help                  Show this help message
 `);
 }
 
 // ============================================================
-// 平台检测
+// Platform detection
 // ============================================================
 
 function detectAIPlatform() {
   const home = homedir();
-  // 优先 Claude（如果两者都存在，用户可以用 --platform 覆盖）
+  // Prefer Claude (if both exist, user can override with --platform)
   if (existsSync(join(home, '.claude'))) return 'claude';
   if (existsSync(join(home, '.cursor'))) return 'cursor';
   return null;
@@ -97,7 +106,7 @@ function getOSType() {
 }
 
 // ============================================================
-// 文件操作辅助
+// File operation helpers
 // ============================================================
 
 function ensureDir(dir) {
@@ -116,7 +125,7 @@ function setExecutable(filepath) {
     const st = statSync(filepath);
     chmodSync(filepath, st.mode | 0o111);
   } catch {
-    // Windows 下 chmod 可能无效，忽略
+    // chmod may be ineffective on Windows, ignore
   }
 }
 
@@ -134,7 +143,7 @@ function writeJsonFile(filepath, data) {
 }
 
 // ============================================================
-// 安装逻辑
+// Install logic
 // ============================================================
 
 function installScripts(osType) {
@@ -176,7 +185,7 @@ function installSkill(aiPlatform) {
   let skillDest;
 
   if (aiPlatform === 'cursor') {
-    // 检查 skills.sh 安装路径
+    // Check skills.sh install path
     const skillsShPath = join(homedir(), '.cursor', 'skills', SKILL_NAME, 'SKILL.md');
     if (existsSync(skillsShPath)) {
       console.log(`  Skill   → already installed at ${skillsShPath} (skipped)`);
@@ -186,7 +195,7 @@ function installSkill(aiPlatform) {
     skillDir = join(homedir(), '.cursor', 'skills', SKILL_NAME);
     skillDest = join(skillDir, 'SKILL.md');
   } else if (aiPlatform === 'claude') {
-    // Claude Code: 按标准 skills 目录安装
+    // Claude Code: install to standard skills directory
     const skillsRootDir = join(homedir(), '.claude', 'skills');
     skillDir = join(skillsRootDir, SKILL_NAME);
     skillDest = join(skillDir, 'SKILL.md');
@@ -208,7 +217,7 @@ function registerCursorHook(osType) {
   if (!config.hooks) config.hooks = {};
   if (!config.hooks.stop) config.hooks.stop = [];
 
-  // 构建 hook 命令
+  // Build hook command
   let hookCmd;
   if (osType === 'unix') {
     hookCmd = `bash ${INSTALL_BASE}/hooks/stop/check_uncommitted.sh`;
@@ -216,12 +225,12 @@ function registerCursorHook(osType) {
     hookCmd = `powershell -File "${INSTALL_BASE}\\hooks\\stop\\check_uncommitted.ps1"`;
   }
 
-  // 检查是否已注册
+  // Check if already registered
   const alreadyRegistered = config.hooks.stop.some(
     h => typeof h === 'object' && h.command && h.command.includes(SKILL_NAME.replace(/-/g, ''))
   );
 
-  // 用更精确的检测：检查命令中是否包含 agent-better-checkpoint
+  // More precise check: command includes agent-better-checkpoint
   const registered = config.hooks.stop.some(
     h => typeof h === 'object' && h.command && h.command.includes('agent-better-checkpoint')
   );
@@ -234,6 +243,37 @@ function registerCursorHook(osType) {
   console.log(`  Config  → ${hooksPath}`);
 }
 
+function installProjectLocal(targetDir, osType) {
+  const projectBase = join(resolve(targetDir), '.vibe-x', 'agent-better-checkpoint');
+  ensureDir(projectBase);
+
+  if (osType === 'unix') {
+    copyFileSafe(join(PLATFORM_DIR, 'unix', 'checkpoint.sh'), join(projectBase, 'checkpoint.sh'));
+    copyFileSafe(join(PLATFORM_DIR, 'unix', 'check_uncommitted.sh'), join(projectBase, 'check_uncommitted.sh'));
+    setExecutable(join(projectBase, 'checkpoint.sh'));
+    setExecutable(join(projectBase, 'check_uncommitted.sh'));
+  }
+  copyFileSafe(join(PLATFORM_DIR, 'win', 'checkpoint.ps1'), join(projectBase, 'checkpoint.ps1'));
+  copyFileSafe(join(PLATFORM_DIR, 'win', 'check_uncommitted.ps1'), join(projectBase, 'check_uncommitted.ps1'));
+
+  const configDest = join(projectBase, 'config.yml');
+  if (!existsSync(configDest) && existsSync(CONFIG_TEMPLATE)) {
+    copyFileSafe(CONFIG_TEMPLATE, configDest);
+  }
+
+  console.log(`  Project → ${projectBase}/`);
+}
+
+function uninstallProjectLocal(targetDir) {
+  const projectBase = join(resolve(targetDir), '.vibe-x', 'agent-better-checkpoint');
+  if (existsSync(projectBase)) {
+    rmSync(projectBase, { recursive: true, force: true });
+    console.log(`  Removed project-local: ${projectBase}`);
+  } else {
+    console.log(`  ${projectBase} not found, nothing to remove`);
+  }
+}
+
 function registerClaudeHook(osType) {
   const settingsPath = join(homedir(), '.claude', 'settings.json');
   let settings = readJsonFile(settingsPath) || {};
@@ -265,9 +305,15 @@ function registerClaudeHook(osType) {
 }
 
 // ============================================================
-// 卸载逻辑
+// Uninstall logic
 // ============================================================
 
+function hasInstallation(platform) {
+  const home = homedir();
+  const skillDir = join(home, platform === 'cursor' ? '.cursor' : '.claude', 'skills', SKILL_NAME);
+  return existsSync(skillDir);
+}
+
 function uninstallScripts() {
   if (existsSync(INSTALL_BASE)) {
     rmSync(INSTALL_BASE, { recursive: true, force: true });
@@ -324,15 +370,16 @@ function unregisterClaudeHook() {
 }
 
 // ============================================================
-// 主入口
+// Main entry
 // ============================================================
 
 function main() {
   const args = parseArgs(process.argv);
   const osType = getOSType();
   const aiPlatform = args.platform || detectAIPlatform();
+  const projectTargetDir = args.target ? resolve(args.target) : null;
 
-  if (!aiPlatform) {
+  if (!aiPlatform && !projectTargetDir && !args.uninstall) {
     console.error(
       'Error: could not detect AI platform.\n' +
       'Please specify: npx @vibe-x/agent-better-checkpoint --platform cursor|claude'
@@ -341,38 +388,72 @@ function main() {
   }
 
   if (args.uninstall) {
-    // 卸载流程
-    console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Uninstalling...`);
+    if (projectTargetDir) {
+      console.log('\n[Project-local] Uninstalling...');
+      uninstallProjectLocal(projectTargetDir);
+    }
 
-    if (aiPlatform === 'cursor') {
-      uninstallCursorSkill();
-      unregisterCursorHook();
-    } else {
-      uninstallClaudeSkill();
-      unregisterClaudeHook();
+    // 指定 --platform 时只清该平台；未指定时清理所有已安装的平台
+    const platforms = args.platform
+      ? [args.platform]
+      : ['cursor', 'claude'].filter(p => hasInstallation(p));
+
+    if (!projectTargetDir || args.platform) {
+      for (const p of platforms) {
+        console.log(`\n[${p === 'cursor' ? 'Cursor' : 'Claude Code'}] Uninstalling...`);
+        if (p === 'cursor') {
+          uninstallCursorSkill();
+          unregisterCursorHook();
+        } else {
+          uninstallClaudeSkill();
+          unregisterClaudeHook();
+        }
+      }
+      if (platforms.length > 0) {
+        uninstallScripts();
+      }
     }
 
-    uninstallScripts();
-    console.log(`\n✅ Uninstallation complete!`);
+    if (platforms.length === 0 && !projectTargetDir) {
+      console.log('\nNo installation found for any platform.');
+    }
+    console.log('\n✅ Uninstallation complete!');
   } else {
-    // 安装流程
-    console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Installing... (OS: ${osType})`);
-
-    installScripts(osType);
-    installSkill(aiPlatform);
-
-    if (aiPlatform === 'cursor') {
-      registerCursorHook(osType);
+if (projectTargetDir) {
+        if (!aiPlatform) {
+        console.error('Error: --target requires AI platform for global hook. Specify --platform cursor|claude');
+        process.exit(1);
+      }
+      console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Installing... (OS: ${osType})`);
+      installScripts(osType);
+      installSkill(aiPlatform);
+      if (aiPlatform === 'cursor') {
+        registerCursorHook(osType);
+      } else {
+        registerClaudeHook(osType);
+      }
+      installProjectLocal(projectTargetDir, osType);
     } else {
-      registerClaudeHook(osType);
+      console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Installing... (OS: ${osType})`);
+      installScripts(osType);
+      installSkill(aiPlatform);
+      if (aiPlatform === 'cursor') {
+        registerCursorHook(osType);
+      } else {
+        registerClaudeHook(osType);
+      }
     }
 
-    console.log(`\n✅ Installation complete!`);
-    console.log(`\nInstalled components:`);
-    console.log(`  📜 Checkpoint script → ~/.agent-better-checkpoint/scripts/`);
-    console.log(`  🔒 Stop hook         → ~/.agent-better-checkpoint/hooks/stop/`);
+    console.log('\n✅ Installation complete!');
+    console.log('\nInstalled components:');
+    console.log(`  📜 Checkpoint script → ~/.vibe-x/agent-better-checkpoint/scripts/`);
+    console.log(`  🔒 Stop hook         → ~/.vibe-x/agent-better-checkpoint/hooks/stop/`);
     console.log(`  📖 SKILL.md          → ${aiPlatform === 'cursor' ? '~/.cursor/skills/' : '~/.claude/skills/'}${SKILL_NAME}/`);
-    console.log(`\nThe AI agent will now auto-commit with semantic messages. Happy coding! 🎉`);
+    if (projectTargetDir) {
+      const projectBase = join(resolve(projectTargetDir), '.vibe-x', 'agent-better-checkpoint');
+      console.log(`  📁 Project-local     → ${projectBase}/`);
+    }
+    console.log('\nThe AI agent will now auto-commit with semantic messages. Happy coding! 🎉');
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-x/agent-better-checkpoint",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Semantic Git checkpoint commits for AI coding sessions",
   "type": "module",
   "bin": {

package/platform/config.template.yml

@@ -0,0 +1,16 @@
+# Checkpoint commit trigger conditions
+#
+# Controls when stop hook (check_uncommitted) triggers commit reminder.
+# Affects only stop hook detection, not checkpoint.sh commit behavior.
+
+# Trigger reminder if ANY condition met (OR)
+# Empty/commented = condition disabled
+trigger_if_any:
+  # min_changed_files: 3   # At least N active files changed
+  min_changed_lines: 5      # At least N lines changed
+
+# Passive file patterns — matched files do not trigger reminder alone
+passive_patterns:
+  - ".discuss/**"
+  - ".vibe-x/**"
+  - ".DS_Store"