@vibe-x/agent-better-checkpoint 0.1.1 → 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,7 +186,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 +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`;
@@ -216,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')
   );
@@ -265,7 +265,7 @@ function registerClaudeHook(osType) {
 }
 
 // ============================================================
-// 卸载逻辑
+// Uninstall logic
 // ============================================================
 
 function uninstallScripts() {
@@ -324,7 +324,7 @@ function unregisterClaudeHook() {
 }
 
 // ============================================================
-// 主入口
+// Main entry
 // ============================================================
 
 function main() {
@@ -341,7 +341,7 @@ function main() {
   }
 
   if (args.uninstall) {
-    // 卸载流程
+    // Uninstall flow
     console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Uninstalling...`);
 
     if (aiPlatform === 'cursor') {
@@ -355,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);
@@ -369,8 +369,8 @@ 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(`  📜 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.1",
+  "version": "0.2.0",
   "description": "Semantic Git checkpoint commits for AI coding sessions",
   "type": "module",
   "bin": {

package/platform/unix/check_uncommitted.sh

@@ -1,35 +1,37 @@
 #!/usr/bin/env bash
 #
-# check_uncommitted.sh — Stop Hook: 检查未提交的变更
+# check_uncommitted.sh — Stop Hook: check for uncommitted changes
 #
-# 在 AI 对话结束时触发，检查工作区是否存在未提交的变更。
-# 如果存在，输出提醒信息让 AI Agent 执行 fallback checkpoint commit。
+# Triggered at AI conversation end. Checks workspace for uncommitted changes.
+# If found, outputs reminder for AI Agent to run fallback checkpoint commit.
 #
-# 支持平台:
-#   - Cursor: stop hook (stdin JSON 含 workspace_roots)
-#   - Claude Code: Stop hook (stdin JSON 含 hook_event_name)
+# Supported platforms:
+#   - Cursor: stop hook (stdin JSON with workspace_roots)
+#   - Claude Code: Stop hook (stdin JSON with hook_event_name)
 #
-# 输出协议:
-#   - 无问题: {} (空 JSON)
-#   - 有问题 (Cursor): {"followup_message": "..."}
-#   - 有问题 (Claude Code): {"decision": "block", "reason": "..."}
+# Output protocol:
+#   - OK: {} (empty JSON)
+#   - Block (Cursor): {"followup_message": "..."}
+#   - Block (Claude Code): {"decision": "block", "reason": "..."}
 #
-# JSON 解析使用 grep+sed，不依赖 jq。
+# Config: .vibe-x/agent-better-checkpoint/config.yml (project-level, optional)
+# JSON parsing uses grep+sed, no jq dependency.
 
 set -euo pipefail
 
 # ============================================================
-# 辅助函数：简易 JSON 字段提取（不依赖 jq）
+# Helpers: simple JSON field extraction (no jq)
 # ============================================================
 
-# 输出允许通过的 JSON
 output_allow() {
+    local info="${1:-}"
+    if [[ -n "$info" ]]; then
+        echo "[checkpoint] $info" >&2
+    fi
     echo '{}'
     exit 0
 }
 
-# 从 JSON 中提取布尔字段值
-# Usage: json_bool "$json" "field_name" → 输出 "true" 或 "false"
 json_bool() {
     local json="$1" field="$2"
     if echo "$json" | grep -qE "\"${field}\"[[:space:]]*:[[:space:]]*true"; then
@@ -39,8 +41,6 @@ json_bool() {
     fi
 }
 
-# 从 JSON 中提取字符串字段值
-# Usage: json_string "$json" "field_name" → 输出字符串值（不含引号）
 json_string() {
     local json="$1" field="$2"
     echo "$json" | grep -oE "\"${field}\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" \
@@ -48,13 +48,10 @@ json_string() {
         | head -1
 }
 
-# 从 JSON 的 workspace_roots / workspaceRoots 数组中提取第一个路径
-# Usage: json_workspace_root "$json" → 输出路径
 json_workspace_root() {
     local json="$1"
     local result=""
 
-    # 尝试 workspace_roots 和 workspaceRoots
     for field in "workspace_roots" "workspaceRoots"; do
         result=$(echo "$json" \
             | grep -oE "\"${field}\"[[:space:]]*:[[:space:]]*\[[^]]*\]" \
@@ -70,7 +67,134 @@ json_workspace_root() {
 }
 
 # ============================================================
-# 平台检测
+# Config parsing (.vibe-x/agent-better-checkpoint/config.yml)
+# ============================================================
+
+CONFIG_FILE_NAME=".vibe-x/agent-better-checkpoint/config.yml"
+
+parse_min_changed_lines() {
+    local config="$1"
+    [[ -f "$config" ]] || return 0
+    local val
+    val=$(grep -E '^[[:space:]]+min_changed_lines:[[:space:]]*[0-9]+' "$config" 2>/dev/null \
+        | sed -E 's/.*min_changed_lines:[[:space:]]*([0-9]+).*/\1/' \
+        | head -1 || true)
+    echo "${val:-}"
+}
+
+parse_min_changed_files() {
+    local config="$1"
+    [[ -f "$config" ]] || return 0
+    local val
+    val=$(grep -E '^[[:space:]]+min_changed_files:[[:space:]]*[0-9]+' "$config" 2>/dev/null \
+        | sed -E 's/.*min_changed_files:[[:space:]]*([0-9]+).*/\1/' \
+        | head -1 || true)
+    echo "${val:-}"
+}
+
+parse_passive_patterns() {
+    local config="$1"
+    [[ -f "$config" ]] || return 0
+    local in_section=false
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        [[ "$line" =~ ^[[:space:]]*# ]] && continue
+        [[ -z "$line" ]] && continue
+        if [[ "$line" =~ ^passive_patterns: ]]; then
+            in_section=true
+            continue
+        fi
+        if $in_section; then
+            if [[ "$line" =~ ^[[:space:]]*-[[:space:]]+(.*) ]]; then
+                local val="${BASH_REMATCH[1]}"
+                val="${val#\"}" && val="${val%\"}"
+                val="${val#\'}" && val="${val%\'}"
+                val=$(echo "$val" | sed 's/[[:space:]]*#.*//;s/[[:space:]]*$//')
+                [[ -n "$val" ]] && echo "$val"
+            elif [[ ! "$line" =~ ^[[:space:]] ]]; then
+                break
+            fi
+        fi
+    done < "$config"
+}
+
+# ============================================================
+# Passive file matching
+# ============================================================
+
+match_pattern() {
+    local file="$1" pattern="$2"
+
+    # dir/** → match all files under dir/
+    if [[ "$pattern" == *"/**" ]]; then
+        local prefix="${pattern%/**}/"
+        [[ "$file" == "$prefix"* ]] && return 0
+        return 1
+    fi
+
+    # *.ext → match suffix
+    if [[ "$pattern" == \*.* ]]; then
+        local suffix="${pattern#\*}"
+        [[ "$file" == *"$suffix" ]] && return 0
+        return 1
+    fi
+
+    # Exact match
+    [[ "$file" == "$pattern" ]] && return 0
+    return 1
+}
+
+is_passive_file() {
+    local file="$1"
+    shift
+    local patterns=("$@")
+    for pattern in "${patterns[@]}"; do
+        if match_pattern "$file" "$pattern"; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+# ============================================================
+# Changed line count
+# ============================================================
+
+count_changed_lines() {
+    local workspace="$1"
+    shift
+    local files=("$@")
+    local total=0
+
+    if [[ ${#files[@]} -eq 0 ]]; then
+        echo 0
+        return
+    fi
+
+    # Tracked files: staged + unstaged diff lines (batch count)
+    local tracked_lines
+    tracked_lines=$(
+        { git -C "$workspace" diff --numstat -- "${files[@]}" 2>/dev/null || true
+          git -C "$workspace" diff --cached --numstat -- "${files[@]}" 2>/dev/null || true
+        } | awk '{a=$1; d=$2; if(a!="-") t+=a; if(d!="-") t+=d} END {print t+0}'
+    )
+    total=$((total + tracked_lines))
+
+    # Untracked files: total lines count as changes
+    for file in "${files[@]}"; do
+        if [[ -n "$(git -C "$workspace" ls-files --others --exclude-standard -- "$file" 2>/dev/null)" ]]; then
+            if [[ -f "${workspace}/${file}" ]]; then
+                local lines
+                lines=$(wc -l < "${workspace}/${file}" 2>/dev/null || echo 0)
+                total=$((total + ${lines## }))
+            fi
+        fi
+    done
+
+    echo "$total"
+}
+
+# ============================================================
+# Platform detection
 # ============================================================
 
 detect_platform() {
@@ -79,7 +203,6 @@ detect_platform() {
         echo "unknown"
         return
     fi
-    # Claude Code: 有 hook_event_name 或 tool_name
     if echo "$json" | grep -qE '"hook_event_name"|"tool_name"'; then
         echo "claude_code"
     else
@@ -88,13 +211,12 @@ detect_platform() {
 }
 
 # ============================================================
-# Workspace Root 检测
+# Workspace root detection
 # ============================================================
 
 get_workspace_root() {
     local json="$1"
 
-    # 优先从 stdin JSON 获取
     if [[ -n "$json" ]]; then
         local ws
         ws=$(json_workspace_root "$json")
@@ -104,7 +226,6 @@ get_workspace_root() {
         fi
     fi
 
-    # 回退到环境变量
     for env_var in CURSOR_PROJECT_DIR CLAUDE_PROJECT_DIR WORKSPACE_ROOT PROJECT_ROOT; do
         local val="${!env_var:-}"
         if [[ -n "$val" ]]; then
@@ -113,24 +234,17 @@ get_workspace_root() {
         fi
     done
 
-    # 最终回退到 PWD / cwd
     echo "${PWD:-$(pwd)}"
 }
 
 # ============================================================
-# Git 操作
+# Git operations
 # ============================================================
 
 is_git_repo() {
     git -C "$1" rev-parse --is-inside-work-tree &>/dev/null
 }
 
-has_uncommitted_changes() {
-    local status
-    status=$(git -C "$1" status --porcelain 2>/dev/null)
-    [[ -n "$status" ]]
-}
-
 get_change_summary() {
     local workspace="$1"
     local max_lines="${2:-20}"
@@ -153,17 +267,16 @@ get_change_summary() {
 }
 
 # ============================================================
-# 输出提醒
+# Output reminder
 # ============================================================
 
-# 转义字符串用于 JSON 值（处理引号、反斜杠、换行等）
 json_escape() {
     local str="$1"
-    str="${str//\\/\\\\}"    # 反斜杠
-    str="${str//\"/\\\"}"    # 双引号
-    str="${str//$'\n'/\\n}"  # 换行
-    str="${str//$'\r'/\\r}"  # 回车
-    str="${str//$'\t'/\\t}"  # Tab
+    str="${str//\\/\\\\}"
+    str="${str//\"/\\\"}"
+    str="${str//$'\n'/\\n}"
+    str="${str//$'\r'/\\r}"
+    str="${str//$'\t'/\\t}"
     echo "$str"
 }
 
@@ -184,17 +297,15 @@ output_block() {
 }
 
 # ============================================================
-# 主逻辑
+# Main logic
 # ============================================================
 
 main() {
-    # 从 stdin 读取 JSON（非阻塞：如果无输入则为空）
     local input=""
     if [[ ! -t 0 ]]; then
         input=$(cat)
     fi
 
-    # Claude Code 的 stop_hook_active 防止无限循环
     if [[ -n "$input" ]]; then
         local stop_active
         stop_active=$(json_bool "$input" "stop_hook_active")
@@ -203,31 +314,131 @@ main() {
         fi
     fi
 
-    # 检测平台
     local platform
     platform=$(detect_platform "$input")
 
-    # 获取 workspace root
     local workspace
     workspace=$(get_workspace_root "$input")
 
-    # 检查是否为 git 仓库
+    # Delegate to project-local script when present (committed with project)
+    local project_script="${workspace}/.vibe-x/agent-better-checkpoint/check_uncommitted.sh"
+    if [[ -f "$project_script" ]] && [[ -x "$project_script" ]]; then
+        echo "$input" | bash "$project_script"
+        exit $?
+    fi
+
     if ! is_git_repo "$workspace"; then
         output_allow
     fi
 
-    # 检查是否有未提交变更
-    if ! has_uncommitted_changes "$workspace"; then
+    # Get all changes
+    local status_output
+    status_output=$(git -C "$workspace" status --porcelain 2>/dev/null)
+
+    if [[ -z "$status_output" ]]; then
         output_allow
     fi
 
-    # 获取变更摘要
+    # Load config
+    local config_file="${workspace}/${CONFIG_FILE_NAME}"
+    local -a passive_patterns=()
+    local min_changed_lines=""
+    local min_changed_files=""
+
+    if [[ -f "$config_file" ]]; then
+        while IFS= read -r p; do
+            [[ -n "$p" ]] && passive_patterns+=("$p")
+        done < <(parse_passive_patterns "$config_file")
+
+        min_changed_lines=$(parse_min_changed_lines "$config_file")
+        min_changed_files=$(parse_min_changed_files "$config_file")
+    fi
+
+    # ---- 分离主动/被动文件 ----
+    local -a active_files=()
+    local -a passive_files_list=()
+
+    while IFS= read -r line; do
+        local file="${line:3}"
+        # Handle rename: "old -> new"
+        if [[ "$file" == *" -> "* ]]; then
+            file="${file##* -> }"
+        fi
+        # Strip possible quotes
+        file="${file#\"}" && file="${file%\"}"
+
+        if [[ ${#passive_patterns[@]} -gt 0 ]] && is_passive_file "$file" "${passive_patterns[@]}"; then
+            passive_files_list+=("$file")
+        else
+            active_files+=("$file")
+        fi
+    done <<< "$status_output"
+
+    # ---- No active files → only passive changes, skip ----
+    if [[ ${#active_files[@]} -eq 0 ]]; then
+        output_allow "Skipped: only passive file changes (${#passive_files_list[@]} files). Patterns: ${passive_patterns[*]}"
+    fi
+
+    # ---- No threshold config → trigger on any active change (backward compat) ----
+    if [[ -z "$min_changed_lines" ]] && [[ -z "$min_changed_files" ]]; then
+        # Use original reminder logic
+        build_and_output_reminder "$workspace" "$platform"
+    fi
+
+    # ---- Check trigger conditions (OR) ----
+    local triggered=false
+    local active_file_count=${#active_files[@]}
+    local active_line_count=0
+
+    # Check file count first (cheaper)
+    if [[ -n "$min_changed_files" ]] && [[ $active_file_count -ge $min_changed_files ]]; then
+        triggered=true
+    fi
+
+    # Then check line count (requires diff)
+    if [[ "$triggered" != "true" ]] && [[ -n "$min_changed_lines" ]]; then
+        active_line_count=$(count_changed_lines "$workspace" "${active_files[@]}")
+        if [[ $active_line_count -ge $min_changed_lines ]]; then
+            triggered=true
+        fi
+    fi
+
+    if [[ "$triggered" != "true" ]]; then
+        # Compute line count (if not yet, for output)
+        if [[ $active_line_count -eq 0 ]] && [[ -n "$min_changed_lines" ]]; then
+            : # Already computed
+        elif [[ $active_line_count -eq 0 ]]; then
+            active_line_count=$(count_changed_lines "$workspace" "${active_files[@]}")
+        fi
+        output_allow "Skipped: changes below threshold (${active_file_count} files, ${active_line_count} lines). Config: min_changed_files=${min_changed_files:-unset}, min_changed_lines=${min_changed_lines:-unset}"
+    fi
+
+    # ---- Threshold reached, trigger commit reminder ----
+    build_and_output_reminder "$workspace" "$platform"
+}
+
+build_and_output_reminder() {
+    local workspace="$1"
+    local platform="$2"
+
     local changes
     changes=$(get_change_summary "$workspace")
     local changes_indented
     changes_indented=$(echo "$changes" | sed 's/^/  /')
 
-    # 构建提醒消息
+    # Project-local script; fallback to global
+    local checkpoint_cmd_sh checkpoint_cmd_ps1
+    if [[ -f "${workspace}/.vibe-x/agent-better-checkpoint/checkpoint.sh" ]]; then
+        checkpoint_cmd_sh=".vibe-x/agent-better-checkpoint/checkpoint.sh"
+    else
+        checkpoint_cmd_sh="~/.vibe-x/agent-better-checkpoint/scripts/checkpoint.sh"
+    fi
+    if [[ -f "${workspace}/.vibe-x/agent-better-checkpoint/checkpoint.ps1" ]]; then
+        checkpoint_cmd_ps1='.\\.vibe-x\\agent-better-checkpoint\\checkpoint.ps1'
+    else
+        checkpoint_cmd_ps1='\$env:USERPROFILE/.vibe-x/agent-better-checkpoint/scripts/checkpoint.ps1'
+    fi
+
     local reminder
     reminder="## ⚠️ Uncommitted Changes Detected
 
@@ -242,12 +453,12 @@ ${changes_indented}
 
 **macOS/Linux:**
 \`\`\`bash
-~/.agent-better-checkpoint/scripts/checkpoint.sh \"checkpoint(<scope>): <description>\" \"<user-prompt>\" --type fallback
+${checkpoint_cmd_sh} \"checkpoint(<scope>): <description>\" \"<user-prompt>\" --type fallback
 \`\`\`
 
 **Windows (PowerShell):**
 \`\`\`powershell
-powershell -File \"\$env:USERPROFILE/.agent-better-checkpoint/scripts/checkpoint.ps1\" \"checkpoint(<scope>): <description>\" \"<user-prompt>\" -Type fallback
+powershell -File \"${checkpoint_cmd_ps1}\" \"checkpoint(<scope>): <description>\" \"<user-prompt>\" -Type fallback
 \`\`\`"
 
     output_block "$reminder" "$platform"