@vibe-x/agent-better-checkpoint 0.1.0 → 0.2.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
@@ -93,11 +108,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,22 +18,22 @@ 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');
 
 // ============================================================
-// 参数解析
+// Argument parsing
 // ============================================================
 
 function parseArgs(argv) {
@@ -79,12 +79,12 @@ Options:
 }
 
 // ============================================================
-// 平台检测
+// 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 +97,7 @@ function getOSType() {
 }
 
 // ============================================================
-// 文件操作辅助
+// File operation helpers
 // ============================================================
 
 function ensureDir(dir) {
@@ -116,7 +116,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 +134,7 @@ function writeJsonFile(filepath, data) {
 }
 
 // ============================================================
-// 安装逻辑
+// Install logic
 // ============================================================
 
 function installScripts(osType) {
@@ -176,7 +176,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,16 +186,15 @@ function installSkill(aiPlatform) {
     skillDir = join(homedir(), '.cursor', 'skills', SKILL_NAME);
     skillDest = join(skillDir, 'SKILL.md');
   } else if (aiPlatform === 'claude') {
-    // Claude Code: 作为 slash command 安装
-    const commandsDir = join(homedir(), '.claude', 'commands');
-    skillDest = join(commandsDir, `${SKILL_NAME}.md`);
+    // Claude Code: install to standard skills directory
+    const skillsRootDir = join(homedir(), '.claude', 'skills');
+    skillDir = join(skillsRootDir, SKILL_NAME);
+    skillDest = join(skillDir, 'SKILL.md');
 
     if (existsSync(skillDest)) {
       console.log(`  Skill   → already installed at ${skillDest} (skipped)`);
       return;
     }
-
-    skillDir = commandsDir;
   }
 
   copyFileSafe(SKILL_SRC, skillDest);
@@ -209,7 +208,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`;
@@ -217,12 +216,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')
   );
@@ -266,7 +265,7 @@ function registerClaudeHook(osType) {
 }
 
 // ============================================================
-// 卸载逻辑
+// Uninstall logic
 // ============================================================
 
 function uninstallScripts() {
@@ -287,10 +286,10 @@ function uninstallCursorSkill() {
 }
 
 function uninstallClaudeSkill() {
-  const cmdFile = join(homedir(), '.claude', 'commands', `${SKILL_NAME}.md`);
-  if (existsSync(cmdFile)) {
-    rmSync(cmdFile, { force: true });
-    console.log(`  Removed command: ${cmdFile}`);
+  const skillDir = join(homedir(), '.claude', 'skills', SKILL_NAME);
+  if (existsSync(skillDir)) {
+    rmSync(skillDir, { recursive: true, force: true });
+    console.log(`  Removed skill: ${skillDir}`);
   }
 }
 
@@ -325,7 +324,7 @@ function unregisterClaudeHook() {
 }
 
 // ============================================================
-// 主入口
+// Main entry
 // ============================================================
 
 function main() {
@@ -342,7 +341,7 @@ function main() {
   }
 
   if (args.uninstall) {
-    // 卸载流程
+    // Uninstall flow
     console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Uninstalling...`);
 
     if (aiPlatform === 'cursor') {
@@ -356,7 +355,7 @@ function main() {
     uninstallScripts();
     console.log(`\n✅ Uninstallation complete!`);
   } else {
-    // 安装流程
+    // Install flow
     console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Installing... (OS: ${osType})`);
 
     installScripts(osType);
@@ -370,9 +369,9 @@ function main() {
 
     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(`  📖 SKILL.md          → ${aiPlatform === 'cursor' ? '~/.cursor/skills/' : '~/.claude/commands/'}${SKILL_NAME}/`);
+    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! 🎉`);
   }
 }

package/package.json

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