agent-changelog 1.0.1

package/README.md

@@ -0,0 +1,125 @@
+# agent-changelog
+
+A versioning skill for OpenClaw that keeps a clear history of workspace changes with sender attribution.
+
+Use it to answer questions like:
+
+- Who changed this file?
+- What changed between two points in time?
+- Can I roll back to a known good state?
+
+## What you get
+
+- Automatic capture of tracked file changes between turns
+- Batched git commits every 10 minutes with per-sender attribution
+- Chat/CLI commands for status, log, diff, rollback, and restore
+- Optional push to your remote after each batched commit
+
+## Quick start
+
+Requirements: `git`, `jq`, Node.js
+
+1. Install the skill into your OpenClaw workspace:
+
+```bash
+npx agent-changelog
+```
+Defaults to `~/.openclaw/workspace` (or `OPENCLAW_WORKSPACE` if set).
+2. In your terminal, restart the gateway so the skill is picked up:
+
+```bash
+openclaw gateway restart
+```
+
+3. In chat, run:
+
+```bash
+/agent-changelog setup
+```
+![Setup command flow in chat](images/setup.gif)
+
+4. Restart the gateway again to activate the installed hooks:
+
+```bash
+openclaw gateway restart
+```
+
+5. Verify:
+
+```bash
+/agent-changelog status
+```
+![Status command output example](images/status.gif)
+
+**Optional — connect to GitHub:**
+After setup, the agent can walk you through linking the workspace to a GitHub repo. Just ask:
+```text
+/agent-changelog ok help me set up github
+```
+It will handle git identity, auth (SSH or HTTPS), remote configuration, and the initial push — no prep work needed on your end.
+
+## Example usages
+
+Check the latest commit and pending changes:
+```text
+/agent-changelog show me the recent changes
+```
+
+Browse specific recent history:
+```text
+/agent-changelog show me the last 10 changes made to the SOUL file
+```
+
+See what is pending before the next batch commit:
+```text
+/agent-changelog what are the uncommitted changes?
+```
+
+## Configuration
+
+After setup, `.agent-changelog.json` is created (if missing) and defaults to tracking the entire workspace:
+
+```json
+{
+  "tracked": [
+    "."
+  ]
+}
+```
+
+Edit this file to narrow or expand what gets tracked.
+
+## A note on secrets
+
+By default, agent-changelog tracks your entire workspace. Setup creates a `.gitignore` that excludes common secret patterns — `.env` files, API keys, tokens, credentials, cloud config directories, and more.
+
+A few things to be careful about:
+
+- **If your workspace already has a `.gitignore`**, setup leaves it untouched. Make sure it excludes anything sensitive before enabling tracking.
+- **If you're pushing to a remote**, audit your workspace for hardcoded secrets in tracked files (SOUL.md, AGENTS.md, etc.) before the first push.
+- **Narrow your tracking** if you're unsure. Edit `.agent-changelog.json` to list only the specific files you want versioned instead of `.`.
+- **Auto-push is on if a remote exists.** If a git remote is configured in your workspace, every batch commit will be pushed automatically. Remove the remote or don't connect to GitHub if you want local-only history.
+
+## In one minute: how it behaves
+
+- On `message:received`, sender details are captured.
+- On `message:sent`, tracked file changes are staged and queued with attribution.
+- Every 10 minutes, queued entries are committed together with grouped attribution.
+
+This gives you low-noise, attributable history without manual git bookkeeping every turn.
+
+## FAQ
+
+**Does this work without OpenClaw?**
+No. The hooks rely on OpenClaw's event system (`message:received` / `message:sent`), and setup uses the `openclaw` CLI to register crons and enable hooks. It's built specifically for OpenClaw and won't run on another platform without significant rework.
+
+**Can I sync history to GitHub?**
+Yes. After setup, ask the agent to help you connect to GitHub and it will handle everything — git identity, auth, remote configuration, and the initial push. Once a remote is configured, every future batch commit is pushed automatically.
+
+## Workspace files
+
+| File                        | Purpose                                                                       |
+| --------------------------- | ----------------------------------------------------------------------------- |
+| `.agent-changelog.json` | Your tracked-files configuration                                              |
+| `.version-context`          | Temporary sender handoff between hooks (not committed)                        |
+| `pending_commits.jsonl`     | Pending attribution entries waiting for the next batch commit (not committed) |

package/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: agent-changelog
+description: Advanced handling for agent-changelog requests (history, diffs, restores, rollbacks, snapshots) using git and OpenClaw scripts with clear, user-focused summaries and outputs.
+user-invocable: true
+metadata: {"openclaw":{"requires":{"bins":["git","jq","node"],"env":["OPENCLAW_WORKSPACE","OPENCLAW_CONFIG"]}}}
+---
+
+# Agent Changelog
+
+OpenClaw tracks workspace file changes between turns and attributes them to the user who triggered the change. Use this skill to answer history and diff questions and to apply controlled restores or rollbacks.
+
+## When To Use
+
+Use this skill when the user asks about:
+- What changed, who changed it, or when it changed
+- Diffs between versions or commits
+- Rolling back or restoring files
+- Taking or inspecting snapshots or status
+- Setting up or verifying auto-versioning
+
+## Response Framework
+
+1. **Clarify intent and scope.**
+	- Determine whether the user wants a quick summary or raw output.
+	- Pin down file(s), time range, and commit identifiers if needed.
+
+2. **Choose the evidence source.**
+	- Casual queries: use git to gather a compact view.
+	- Explicit `/agent-changelog` invocations: run the matching script and return stdout verbatim.
+
+3. **Present results clearly.**
+	- Summarize what changed, who triggered it, and the rough size.
+	- Offer the next most likely action (diff, restore, rollback, or log).
+
+4. **Handle destructive actions safely.**
+	- Always show what will change before a rollback or restore.
+	- Prefer `restore` for single-file fixes; use `rollback` only when the user wants to revert everything.
+	- If the target commit is ambiguous, ask a clarification question.
+
+5. **Guide GitHub onboarding for setup.**
+	- After `setup`, proactively ask: "ok do you want help with github?"
+	- If yes, walk them through GitHub onboarding with no extra setup steps required on their side.
+	- Confirm account status, git identity, auth method, and remote configuration.
+
+## Output Style
+
+- For summaries, keep it short and conversational.
+- For script-driven output, do not reformat or summarize; if onboarding guidance is needed, provide it after the raw output.
+- If an argument looks like a typo, confirm before running.
+
+## File Content Rules
+
+**Never embed attribution metadata inside file content.** Do not add inline annotations like `(updated by X on date)`, `# changed by Y`, status footnotes, or any other authorship/timestamp markers into the files you edit. Attribution belongs exclusively in the git commit message, which is handled automatically by the hooks and `commit.sh`. Files should contain only their actual content — clean, annotation-free.
+
+## Implementation Notes
+
+- **Casual history or diff:** use a small git window (last 5-10 commits) and include stat output.
+- **Slash commands:** use the scripts in `setup.sh` and `scripts/` with the user-provided arguments.
+- **Setup:** run the setup script, then ask "ok do you want help with github?" and proceed if they confirm.
+- **Restore or rollback:** locate the commit via `log`, then perform the change after showing what will be modified.
+- **Semantic summary:** before every commit, run a quick diff and generate a sparse one-line summary of what changed and why (e.g. "added rate-limit rule to AGENTS.md, updated memory skill"). Always pass it via `--summary` and always include it in any history output presented to the user.
+- **Log output:** `log.sh` outputs raw structured data — present it conversationally based on what the user asked. Don't dump raw script output. Format each entry using the `│`-prefixed box style (same as status output), one entry per block.
+
+## Command Reference (Compact)
+
+Use this only for explicit `/agent-changelog` invocations, and return stdout verbatim.
+
+- `setup` -> `bash {baseDir}/setup.sh`
+- `setup` follow-up -> GitHub onboarding guidance
+- `status` -> `bash {baseDir}/scripts/status.sh`
+- `log` -> `bash {baseDir}/scripts/log.sh [count]`
+- `diff` -> `bash {baseDir}/scripts/diff.sh [commit] [commit2]`
+- `rollback` -> `bash {baseDir}/scripts/rollback.sh <commit> ["reason"]`
+- `restore` -> `bash {baseDir}/scripts/restore.sh <file> <commit> ["reason"]`
+- `commit` (user-requested) -> `bash {baseDir}/scripts/commit.sh --manual ["message"] [--summary "one-line semantic summary"]`
+- `commit` (cron-triggered) -> `bash {baseDir}/scripts/commit.sh [--summary "one-line semantic summary"]`
+
+## Auto-Versioning Overview
+
+Two hooks capture and commit changes between turns and attribute them to the active user. Defaults can be overridden via `.agent-changelog.json`.
+
+Tracked by default: `.` (entire workspace). Secrets and runtime files are excluded via the `.gitignore` that setup creates — note that if a `.gitignore` already exists in the workspace, setup leaves it untouched, so ensure it covers secrets before enabling tracking.
+
+To track a specific subset instead, edit `<workspace>/.agent-changelog.json` with a `tracked` array (this fully replaces the default):
+```json
+{ "tracked": ["<file-or-folder>", "<file-or-folder>"] }
+```
+
+## GitHub Onboarding (Setup Add-on)
+
+Use this flow after setup to help users connect the workspace to GitHub. The user will need to authenticate (SSH key or HTTPS credential) — walk them through it step by step:
+
+1. **Account and intent.** Confirm they have a GitHub account and want this repo linked.
+2. **Git identity.** Ensure `user.name` and `user.email` are set for commits.
+3. **Auth method.** Offer SSH or HTTPS; proceed with their preference.
+4. **Remote and verify.** Ensure an `origin` remote exists and verify access.
+5. **Next action.** Create or select the GitHub repo, then push or fetch as needed.
+

package/bin/agent-changelog.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const skillName = "agent-changelog";
+const packageRoot = path.resolve(__dirname, "..");
+const workspace =
+  process.env.OPENCLAW_WORKSPACE ||
+  path.join(os.homedir(), ".openclaw", "workspace");
+const skillsDir = path.join(workspace, "skills");
+const targetDir = path.join(skillsDir, skillName);
+
+function copyFile(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function copyDir(srcDir, destDir) {
+  if (!fs.existsSync(srcDir)) return;
+  fs.mkdirSync(destDir, { recursive: true });
+
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const src = path.join(srcDir, entry.name);
+    const dest = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(src, dest);
+    } else if (entry.isFile()) {
+      copyFile(src, dest);
+    }
+  }
+}
+
+if (!fs.existsSync(workspace)) {
+  console.error(`OpenClaw workspace not found: ${workspace}`);
+  console.error("Set OPENCLAW_WORKSPACE or run OpenClaw once to create it.");
+  process.exit(1);
+}
+
+fs.mkdirSync(skillsDir, { recursive: true });
+fs.mkdirSync(targetDir, { recursive: true });
+
+for (const file of ["SKILL.md", "setup.sh"]) {
+  const src = path.join(packageRoot, file);
+  if (!fs.existsSync(src)) {
+    console.error(`Missing required file: ${file}`);
+    process.exit(1);
+  }
+  copyFile(src, path.join(targetDir, file));
+}
+
+for (const dir of ["hooks", "scripts"]) {
+  const src = path.join(packageRoot, dir);
+  copyDir(src, path.join(targetDir, dir));
+}
+
+console.log(`Installed ${skillName} to ${targetDir}`);

package/hooks/agent-changelog-capture/HOOK.md

@@ -0,0 +1,11 @@
+---
+name: agent-changelog-capture
+description: "Captures sender identity before each agent turn for commit attribution"
+metadata: { "openclaw": { "emoji": "📸", "events": ["message:received"] } }
+---
+
+# Agent Changelog — Capture
+
+Writes sender identity to `.version-context` in the workspace before each agent turn. The companion `agent-changelog-commit` hook reads this to attribute git commits to the correct user.
+
+Part of the `agent-changelog` skill. Install via `setup.sh`.

package/hooks/agent-changelog-capture/handler.ts

@@ -0,0 +1,35 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const handler = async (event: any) => {
+  if (event.type !== "message" || event.action !== "received") return;
+
+  const workspace =
+    process.env.OPENCLAW_WORKSPACE ?? `${process.env.HOME}/.openclaw/workspace`;
+
+  const ctx = {
+    user:
+      event.context?.senderName ??
+      event.context?.metadata?.senderName ??
+      event.context?.from ??
+      "unknown",
+    userId:
+      event.context?.senderId ??
+      event.context?.metadata?.senderId ??
+      event.context?.from ??
+      "unknown",
+    channel: event.context?.channelId ?? "unknown",
+    ts: Date.now(),
+  };
+
+  try {
+    writeFileSync(join(workspace, ".version-context"), JSON.stringify(ctx));
+  } catch (err) {
+    console.error(
+      "[agent-changelog-capture] Failed to write context:",
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+};
+
+export default handler;

package/hooks/agent-changelog-commit/HOOK.md

@@ -0,0 +1,13 @@
+---
+name: agent-changelog-commit
+description: "Auto-commits workspace file changes with sender attribution after each agent turn"
+metadata: { "openclaw": { "emoji": "📝", "events": ["message:sent"], "requires": { "bins": ["git"] } } }
+---
+
+# Agent Changelog — Commit
+
+After each outbound message, stages tracked workspace files and queues sender attribution in the commit message body.
+
+Tracked files are read from `.agent-changelog.json` in the workspace, written by `setup.sh` on install.
+
+Part of the `agent-changelog` skill. Install via `setup.sh`.

package/hooks/agent-changelog-commit/handler.ts

@@ -0,0 +1,97 @@
+import { execSync } from "node:child_process";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmdirSync,
+  unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+
+function run(cmd: string, cwd: string): string {
+  try {
+    return execSync(cmd, { cwd, encoding: "utf-8", timeout: 15_000 }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function getTracked(workspace: string): string[] {
+  const cfgPath = join(workspace, ".agent-changelog.json");
+  try {
+    const cfg = JSON.parse(readFileSync(cfgPath, "utf-8"));
+    if (Array.isArray(cfg.tracked) && cfg.tracked.length > 0) return cfg.tracked;
+  } catch {}
+  return [];
+}
+
+async function acquireLock(lockDir: string): Promise<boolean> {
+  for (let i = 0; i < 50; i++) {
+    try {
+      mkdirSync(lockDir);
+      return true;
+    } catch {
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  }
+  return false;
+}
+
+const handler = async (event: any) => {
+  if (event.type !== "message" || event.action !== "sent") return;
+
+  const workspace =
+    process.env.OPENCLAW_WORKSPACE ?? `${process.env.HOME}/.openclaw/workspace`;
+
+  if (!existsSync(join(workspace, ".git"))) return;
+
+  const lockDir = join(workspace, ".version-lock");
+  const acquired = await acquireLock(lockDir);
+  if (!acquired) {
+    console.error("[agent-changelog-commit] Could not acquire lock, skipping");
+    return;
+  }
+
+  try {
+    // Detect changes since the last git add (working tree vs index).
+    const changed = run("git diff --name-only", workspace)
+      .split("\n")
+      .filter(Boolean);
+
+    if (changed.length === 0) return;
+
+    // Read sender identity written by the capture hook
+    let user = "unknown";
+    let userId = "unknown";
+    let channel = "unknown";
+    const ctxPath = join(workspace, ".version-context");
+    if (existsSync(ctxPath)) {
+      try {
+        const ctx = JSON.parse(readFileSync(ctxPath, "utf-8"));
+        user = ctx.user ?? "unknown";
+        userId = ctx.userId ?? "unknown";
+        channel = ctx.channel ?? "unknown";
+      } catch {}
+    }
+
+    // Append entry to pending log
+    const entry = JSON.stringify({ ts: Date.now(), user, userId, channel, files: changed });
+    appendFileSync(join(workspace, "pending_commits.jsonl"), entry + "\n");
+
+    // Stage tracked files
+    for (const f of getTracked(workspace)) {
+      run(`git add "${f}" 2>/dev/null || true`, workspace);
+    }
+  } catch (err) {
+    console.error(
+      "[agent-changelog-commit] Error:",
+      err instanceof Error ? err.message : String(err)
+    );
+  } finally {
+    try { rmdirSync(lockDir); } catch {}
+    try { unlinkSync(join(workspace, ".version-context")); } catch {}
+  }
+};
+
+export default handler;

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "agent-changelog",
+  "version": "1.0.1",
+  "description": "Install the agent-changelog OpenClaw skill into your OpenClaw workspace.",
+  "bin": {
+    "agent-changelog": "bin/agent-changelog.js"
+  },
+  "files": [
+    "bin/",
+    "SKILL.md",
+    "setup.sh",
+    "hooks/",
+    "scripts/",
+    "README.md"
+  ]
+}

package/scripts/commit.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+set -euo pipefail
+
+WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
+cd "$WORKSPACE"
+
+if [ ! -d .git ]; then
+  echo "⚠️ Versioning not initialized"
+  echo "Run \`/agent-changelog setup\` to get started."
+  exit 1
+fi
+
+MANUAL=false
+MESSAGE=""
+SUMMARY=""
+for arg in "$@"; do
+  case "$arg" in
+    --manual) MANUAL=true ;;
+    --summary) shift_next=true ;;
+    *)
+      if [ "${shift_next:-false}" = true ]; then
+        SUMMARY="$arg"
+        shift_next=false
+      elif [ -z "$MESSAGE" ]; then
+        MESSAGE="$arg"
+      fi
+      ;;
+  esac
+done
+
+PENDING="$WORKSPACE/pending_commits.jsonl"
+
+# ─── Resolve tracked files ────────────────────────────────────────────
+TRACKED=()
+while IFS= read -r item; do
+  TRACKED+=("$item")
+done < <(jq -r '.tracked[]?' "$WORKSPACE/.agent-changelog.json" 2>/dev/null)
+
+# ─── Stage any unstaged changes to tracked files ─────────────────────
+for f in "${TRACKED[@]+"${TRACKED[@]}"}"; do
+  git add "$f" 2>/dev/null || true
+done
+
+# ─── Nothing staged at all → nothing to do ───────────────────────────
+if git diff --cached --quiet 2>/dev/null; then
+  [ -f "$PENDING" ] && > "$PENDING"
+  echo "✓ No changes to commit"
+  exit 0
+fi
+
+# ─── Build commit message ─────────────────────────────────────────────
+STAGED_FILES=$(git diff --cached --name-only | tr '\n' ' ' | sed 's/ $//')
+USERS=""
+COUNT=0
+HAS_PENDING=false
+CHANGELOG=""
+
+if [ -f "$PENDING" ] && [ -s "$PENDING" ]; then
+  HAS_PENDING=true
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    COUNT=$((COUNT + 1))
+
+    if command -v jq &>/dev/null; then
+      user=$(echo "$line" | jq -r '.user // "unknown"' 2>/dev/null || echo "unknown")
+      ts=$(echo "$line" | jq -r '.ts // 0' 2>/dev/null || echo "0")
+      channel=$(echo "$line" | jq -r '.channel // "unknown"' 2>/dev/null || echo "unknown")
+      files=$(echo "$line" | jq -r '(.files // []) | join(", ")' 2>/dev/null || echo "")
+      action=$(echo "$line" | jq -r '.action // ""' 2>/dev/null || echo "")
+      action_target=$(echo "$line" | jq -r '.target // ""' 2>/dev/null || echo "")
+      action_file=$(echo "$line" | jq -r '.file // ""' 2>/dev/null || echo "")
+      action_from=$(echo "$line" | jq -r '.from // ""' 2>/dev/null || echo "")
+      action_reason=$(echo "$line" | jq -r '.reason // ""' 2>/dev/null || echo "")
+    else
+      user=$(echo "$line" | grep -o '"user":"[^"]*"' | cut -d'"' -f4 || echo "unknown")
+      ts="0"; channel="unknown"; files=""; action=""; action_target=""; action_file=""; action_from=""; action_reason=""
+    fi
+
+    # Format timestamp as readable date
+    if [ "$ts" != "0" ] && command -v date &>/dev/null; then
+      ts_sec=$((ts / 1000))
+      readable=$(date -r "$ts_sec" "+%Y-%m-%d %H:%M:%S" 2>/dev/null || echo "$ts")
+    else
+      readable="$ts"
+    fi
+
+    # Accumulate unique users
+    if [ -n "$user" ] && [ "$user" != "unknown" ]; then
+      if [ -z "$USERS" ]; then
+        USERS="$user"
+      elif ! echo "$USERS" | grep -qF "$user"; then
+        USERS="$USERS, $user"
+      fi
+    fi
+
+    # Build per-turn changelog line
+    if [ "$action" = "rollback" ]; then
+      CHANGELOG="${CHANGELOG}  [$readable] $user\n"
+      CHANGELOG="${CHANGELOG}  action: rollback → $action_target\n"
+      [ -n "$action_reason" ] && CHANGELOG="${CHANGELOG}  reason: $action_reason\n"
+    elif [ "$action" = "restore" ]; then
+      CHANGELOG="${CHANGELOG}  [$readable] $user\n"
+      CHANGELOG="${CHANGELOG}  action: restore $action_file from $action_from\n"
+      [ -n "$action_reason" ] && CHANGELOG="${CHANGELOG}  reason: $action_reason\n"
+    else
+      CHANGELOG="${CHANGELOG}  [$readable] $user ($channel): $files\n"
+    fi
+  done < "$PENDING"
+fi
+
+# ─── Determine prefix ─────────────────────────────────────────────────
+CTX="$WORKSPACE/.version-context"
+
+if [ "$MANUAL" = true ]; then
+  PREFIX="Manual commit"
+  # For manual commits, prefer identity from version-context (set by capture hook)
+  if [ -z "$USERS" ] || [ "$USERS" = "unknown" ]; then
+    if [ -f "$CTX" ] && command -v jq &>/dev/null; then
+      CTX_USER=$(jq -r '.user // ""' "$CTX" 2>/dev/null || true)
+      [ -n "$CTX_USER" ] && [ "$CTX_USER" != "unknown" ] && USERS="$CTX_USER"
+    fi
+  fi
+  if [ -z "$USERS" ] || [ "$USERS" = "unknown" ]; then USERS="skill invocation"; fi
+elif [ "$HAS_PENDING" = false ] || [ "$COUNT" -eq 0 ]; then
+  PREFIX="Auto-commit (cli)"
+  USERS="cli"
+else
+  PREFIX="Auto-commit"
+fi
+
+if [ -z "$USERS" ]; then USERS="unknown"; fi
+
+# ─── Assemble full message ────────────────────────────────────────────
+if [ -n "$MESSAGE" ]; then
+  SUBJECT="$MESSAGE"
+else
+  SUBJECT="${PREFIX}: $STAGED_FILES"
+fi
+
+MSG="$SUBJECT
+
+Triggered by: ${USERS}
+Turns: ${COUNT}"
+
+[ -n "$SUMMARY" ] && MSG="${MSG}
+Summary: ${SUMMARY}"
+
+if [ -n "$CHANGELOG" ]; then
+  MSG="${MSG}
+
+--- Change log ---
+$(printf "%b" "$CHANGELOG")"
+fi
+
+git commit -m "$MSG"
+SHORT_HASH=$(git rev-parse --short HEAD)
+
+[ -f "$PENDING" ] && > "$PENDING"
+
+echo "✅ **Committed** \`$SHORT_HASH\`"
+echo "$SUBJECT"
+echo "_by ${USERS}_"
+[ -n "$SUMMARY" ] && echo "$SUMMARY"
+
+# ─── Push if remote is configured ────────────────────────────────────
+GIT_REMOTE=$(git remote 2>/dev/null | head -1)
+
+if [ -n "$GIT_REMOTE" ]; then
+  if git push "$GIT_REMOTE" 2>/dev/null; then
+    echo "↑ Pushed to \`$GIT_REMOTE\`"
+  else
+    echo "⚠️ Push to \`$GIT_REMOTE\` failed"
+  fi
+fi

package/scripts/diff.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+set -euo pipefail
+
+WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
+cd "$WORKSPACE"
+
+if [ ! -d .git ]; then
+  echo "⚠️ Versioning not initialized"
+  echo "Run \`/agent-changelog setup\` to get started."
+  exit 1
+fi
+
+if [ $# -eq 0 ]; then
+  CHANGED=$(git diff HEAD --name-only --no-color 2>/dev/null | tr '\n' ' ' | sed 's/ $//' || true)
+  if [ -z "$CHANGED" ]; then
+    echo "✓ No uncommitted changes"
+    exit 0
+  fi
+  echo "✏️ **Uncommitted changes**"
+  echo "\`$CHANGED\`"
+  echo ""
+  echo '```diff'
+  git diff HEAD --no-color 2>/dev/null || git diff --no-color
+  echo '```'
+elif [ $# -eq 1 ]; then
+  SUBJECT=$(git log --format="%s" -1 "$1" 2>/dev/null || true)
+  DATE=$(git log --format="%ad" --date=format:"%b %d, %H:%M" -1 "$1" 2>/dev/null || true)
+  echo "🔍 **\`$1\`** · $DATE"
+  echo "_$SUBJECT_"
+  echo ""
+  echo '```diff'
+  git show "$1" --stat --patch --no-color
+  echo '```'
+elif [ $# -eq 2 ]; then
+  echo "🔍 **Diff** \`$1\` → \`$2\`"
+  echo ""
+  echo '```diff'
+  git diff "$1" "$2" --no-color
+  echo '```'
+fi

package/scripts/log.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+set -euo pipefail
+
+WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
+cd "$WORKSPACE"
+
+if [ ! -d .git ]; then
+  echo "⚠️ Versioning not initialized"
+  echo "Run \`/agent-changelog setup\` to get started."
+  exit 1
+fi
+
+COUNT=10
+for arg in "$@"; do
+  case "$arg" in
+    [0-9]*) COUNT="$arg" ;;
+  esac
+done
+
+[ "${COUNT:-0}" -le 0 ] && COUNT=10
+
+while IFS= read -r hash; do
+  date=$(git log --format="%ad" --date=format:"%b %d, %H:%M" -1 "$hash")
+  subject=$(git log --format="%s" -1 "$hash")
+  body=$(git log --format="%b" -1 "$hash")
+  triggered=$(echo "$body" | grep "^Triggered by:" | sed 's/Triggered by: //' || true)
+  turns=$(echo "$body" | grep "^Turns:" | sed 's/Turns: //' || true)
+  summary=$(echo "$body" | grep "^Summary:" | sed 's/Summary: //' || true)
+  changelog=$(echo "$body" | awk '/^--- Change log ---/{found=1; next} found{print}' || true)
+
+  echo "commit $hash"
+  echo "date: $date"
+  echo "subject: $subject"
+  [ -n "$triggered" ] && echo "by: $triggered"
+  [ -n "$turns" ]     && echo "turns: $turns"
+  [ -n "$summary" ]   && echo "summary: $summary"
+  [ -n "$changelog" ] && printf "changelog:\n%s\n" "$changelog"
+  echo "---"
+done < <(git log --format="%h" -n "$COUNT")

package/scripts/restore.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+set -euo pipefail
+
+WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
+cd "$WORKSPACE"
+
+if [ ! -d .git ]; then
+  echo "⚠️ Versioning not initialized"
+  echo "Run \`/agent-changelog setup\` to get started."
+  exit 1
+fi
+
+FILE="${1:-}"
+COMMIT="${2:-}"
+REASON="${3:-}"
+
+if [ -z "$FILE" ] || [ -z "$COMMIT" ]; then
+  echo "**Usage:** \`/agent-changelog restore <file> <commit> [reason]\`"
+  echo ""
+  echo "Restores a single file to its state before the given commit."
+  echo "Run \`/agent-changelog log\` to find the right commit."
+  exit 1
+fi
+
+if ! git cat-file -e "$COMMIT" 2>/dev/null; then
+  echo "⚠️ Commit \`$COMMIT\` not found"
+  exit 1
+fi
+
+if ! git diff-tree --no-commit-id -r --name-only "$COMMIT" | grep -qF "$FILE"; then
+  echo "⚠️ \`$FILE\` was not changed in \`$COMMIT\`"
+  exit 1
+fi
+
+TARGET_SHORT=$(git rev-parse --short "$COMMIT")
+
+# Read sender identity from capture hook context
+USER="unknown"
+USER_ID="unknown"
+CHANNEL="unknown"
+CTX="$WORKSPACE/.version-context"
+if [ -f "$CTX" ] && command -v jq &>/dev/null; then
+  USER=$(jq -r '.user // "unknown"' "$CTX" 2>/dev/null || echo "unknown")
+  USER_ID=$(jq -r '.userId // "unknown"' "$CTX" 2>/dev/null || echo "unknown")
+  CHANNEL=$(jq -r '.channel // "unknown"' "$CTX" 2>/dev/null || echo "unknown")
+fi
+
+# Restore file to its state before the target commit and stage it
+git checkout "${COMMIT}^" -- "$FILE"
+git add "$FILE"
+
+# Log to pending so the next commit includes restore attribution
+ENTRY=$(jq -n \
+  --argjson ts "$(date +%s000)" \
+  --arg user "$USER" \
+  --arg userId "$USER_ID" \
+  --arg channel "$CHANNEL" \
+  --arg file "$FILE" \
+  --arg from "$TARGET_SHORT" \
+  --arg reason "$REASON" \
+  '{"ts":$ts,"user":$user,"userId":$userId,"channel":$channel,"action":"restore","file":$file,"from":$from,"reason":$reason,"files":[]}')
+printf '%s\n' "$ENTRY" >> "$WORKSPACE/pending_commits.jsonl"
+
+echo "📌 **Staged restore**"
+echo "\`$FILE\` → before \`$TARGET_SHORT\`"
+echo "_by ${USER}_"
+echo ""
+echo "Commit with \`/agent-changelog commit\`"

package/scripts/rollback.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+set -euo pipefail
+
+WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
+cd "$WORKSPACE"
+
+if [ ! -d .git ]; then
+  echo "⚠️ Versioning not initialized"
+  echo "Run \`/agent-changelog setup\` to get started."
+  exit 1
+fi
+
+TARGET="${1:-}"
+REASON="${2:-}"
+
+if [ -z "$TARGET" ]; then
+  echo "**Usage:** \`/agent-changelog rollback <commit> [reason]\`"
+  echo ""
+  echo "**Recent commits:**"
+  while IFS= read -r hash; do
+    date=$(git log --format="%ad" --date=format:"%b %d, %H:%M" -1 "$hash")
+    subject=$(git log --format="%s" -1 "$hash")
+    echo "• \`$hash\` $date — $subject"
+  done < <(git log --format="%h" -10)
+  exit 1
+fi
+
+if ! git cat-file -e "$TARGET" 2>/dev/null; then
+  echo "⚠️ Commit \`$TARGET\` not found"
+  exit 1
+fi
+
+CURRENT_SHORT=$(git rev-parse --short HEAD)
+TARGET_SHORT=$(git rev-parse --short "$TARGET")
+TARGET_MSG=$(git log --format="%s" -1 "$TARGET")
+
+# Read identity from version context
+CTX="$WORKSPACE/.version-context"
+ACTOR="unknown"
+ACTOR_ID="unknown"
+CHANNEL="unknown"
+if [ -f "$CTX" ] && command -v jq &>/dev/null; then
+  ACTOR=$(jq -r '.user // "unknown"' "$CTX" 2>/dev/null || echo "unknown")
+  ACTOR_ID=$(jq -r '.userId // "unknown"' "$CTX" 2>/dev/null || echo "unknown")
+  CHANNEL=$(jq -r '.channel // "unknown"' "$CTX" 2>/dev/null || echo "unknown")
+fi
+[ "$ACTOR" = "unknown" ] && ACTOR="skill invocation"
+[ "$ACTOR_ID" = "unknown" ] && ACTOR_ID="skill invocation"
+
+# Restore only tracked files
+while IFS= read -r f; do
+  git checkout "$TARGET" -- "$f" 2>/dev/null || true
+done < <(jq -r '.tracked[]?' "$WORKSPACE/.agent-changelog.json" 2>/dev/null)
+
+# Stage the same tracked files
+while IFS= read -r f; do
+  git add "$f" 2>/dev/null || true
+done < <(jq -r '.tracked[]?' "$WORKSPACE/.agent-changelog.json" 2>/dev/null)
+
+if ! git diff --cached --quiet; then
+  ENTRY=$(jq -n \
+    --argjson ts "$(date +%s000)" \
+    --arg user "$ACTOR" \
+    --arg userId "$ACTOR_ID" \
+    --arg channel "$CHANNEL" \
+    --arg target "$TARGET_SHORT" \
+    --arg reason "$REASON" \
+    '{"ts":$ts,"user":$user,"userId":$userId,"channel":$channel,"action":"rollback","target":$target,"reason":$reason,"files":[]}')
+  printf '%s\n' "$ENTRY" >> "$WORKSPACE/pending_commits.jsonl"
+
+  echo "⏪ **Staged rollback**"
+  echo "\`$CURRENT_SHORT\` → \`$TARGET_SHORT\`"
+  echo "_$TARGET_MSG_"
+  echo ""
+  echo "_by ${ACTOR}_"
+  echo "Commit with \`/agent-changelog commit\`"
+else
+  echo "✓ Already at \`$TARGET_SHORT\`"
+  exit 0
+fi

package/scripts/status.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+set -euo pipefail
+
+WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
+cd "$WORKSPACE"
+
+if [ ! -d .git ]; then
+  echo "⚠️ Versioning not initialized"
+  echo "Run \`/agent-changelog setup\` to get started."
+  exit 0
+fi
+
+HASH=$(git log --format="%h" -1 2>/dev/null || true)
+
+if [ -z "$HASH" ]; then
+  echo "📸 No commits yet"
+else
+  DATE=$(git log --format="%ad" --date=format:"%b %d, %H:%M" -1)
+  SUBJECT=$(git log --format="%s" -1)
+  BODY=$(git log --format="%b" -1)
+
+  # Parse commit type from subject prefix
+  if echo "$SUBJECT" | grep -qi "^auto-commit"; then
+    TYPE="Auto"
+    FILES=$(echo "$SUBJECT" | sed 's/^[Aa]uto-commit[^:]*: //')
+  elif echo "$SUBJECT" | grep -qi "^manual commit"; then
+    TYPE="Manual"
+    FILES=$(echo "$SUBJECT" | sed 's/^[Mm]anual commit[^:]*: //')
+  elif echo "$SUBJECT" | grep -qi "^rollback"; then
+    TYPE="Rollback"
+    FILES=""
+  else
+    TYPE=""
+    FILES="$SUBJECT"
+  fi
+
+  # Parse identity from commit body
+  IDENTITY=$(echo "$BODY" | grep "^Triggered by:" | sed 's/Triggered by: //' | tr -d '\n' | sed 's/cli/CLI/g' || true)
+
+  # Build output line
+  echo "📸 \`$HASH\` · $DATE"
+
+  META_PARTS=()
+  [ -n "$TYPE" ] && META_PARTS+=("$TYPE")
+  [ -n "$IDENTITY" ] && META_PARTS+=("by $IDENTITY")
+  [ -n "$FILES" ] && META_PARTS+=("$FILES")
+  if [ ${#META_PARTS[@]} -gt 0 ]; then
+    (IFS=' · '; echo "_${META_PARTS[*]}_")
+  fi
+fi
+
+echo ""
+
+MODIFIED=$(git diff HEAD --name-only 2>/dev/null)
+UNTRACKED=$(git ls-files --others --exclude-standard 2>/dev/null)
+ALL_CHANGES=$(printf '%s\n%s\n' "$MODIFIED" "$UNTRACKED" | grep -v '^$' || true)
+CHANGES=$(printf '%s\n' "$ALL_CHANGES" | grep -c . || true)
+
+if [ "$CHANGES" -gt 0 ]; then
+  LABEL=$([ "$CHANGES" -eq 1 ] && echo "file" || echo "files")
+  echo "✏️ **$CHANGES uncommitted $LABEL:**"
+  while IFS= read -r file; do
+    [ -z "$file" ] && continue
+    if echo "$MODIFIED" | grep -qF "$file"; then
+      added=$(git diff HEAD -- "$file" 2>/dev/null | grep -c '^+[^+]' || true)
+      removed=$(git diff HEAD -- "$file" 2>/dev/null | grep -c '^-[^-]' || true)
+      echo "• \`$file\` +$added/-$removed"
+    else
+      echo "• \`$file\` new"
+    fi
+  done <<< "$ALL_CHANGES"
+else
+  echo "✓ No uncommitted changes"
+fi

package/setup.sh

@@ -0,0 +1,217 @@
+#!/bin/bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
+HOOKS_DEST="$WORKSPACE/hooks"
+
+success() { echo "✅ $*"; echo ""; }
+warn()    { echo "⚠️  $*"; echo ""; }
+fail()    { echo "❌ $*"; exit 1; }
+header()  { echo ""; echo "**$***"; echo ""; }
+
+echo "> 🗂️  **agent-changelog**"
+echo "> _workspace version control — setup_"
+
+# ─── Prerequisites ────────────────────────────────────────────────────
+header "Prerequisites"
+
+command -v git &>/dev/null || fail "git not found — install it first"
+success "git $(git --version | awk '{print $3}')"
+
+command -v jq &>/dev/null || fail "jq not found — install it first"
+success "jq $(jq --version)"
+
+[ -d "$WORKSPACE" ] || fail "Workspace not found: $WORKSPACE"
+success "workspace \`$WORKSPACE\`"
+
+if command -v openclaw &>/dev/null; then
+  success "openclaw $(openclaw --version 2>/dev/null | head -1 | awk '{print $3}')"
+else
+  warn "openclaw CLI not found — you'll need to enable hooks manually"
+fi
+
+# ─── Install hooks ────────────────────────────────────────────────────
+header "🪝 Installing hooks"
+
+mkdir -p "$HOOKS_DEST"
+
+HOOKS=("agent-changelog-capture" "agent-changelog-commit")
+for hook in "${HOOKS[@]}"; do
+  src="$SCRIPT_DIR/hooks/$hook"
+  dest="$HOOKS_DEST/$hook"
+
+  if [ ! -d "$src" ]; then
+    warn "Hook source not found: \`$src\`"
+    continue
+  fi
+
+  if [ -L "$dest" ]; then
+    rm "$dest"
+  elif [ -d "$dest" ]; then
+    rm -rf "$dest"
+  fi
+
+  cp -r "$src" "$dest"
+  success "Installed \`$hook\`"
+done
+
+# ─── Enable hooks via config ──────────────────────────────────────────
+header "⚡ Activating hooks"
+
+OPENCLAW_CFG="${OPENCLAW_CONFIG:-$HOME/.openclaw/openclaw.json}"
+
+if [ -f "$OPENCLAW_CFG" ] && command -v jq &>/dev/null; then
+  TMP=$(mktemp)
+  jq '
+    .hooks.internal.enabled = true |
+    .hooks.internal.entries["agent-changelog-capture"].enabled = true |
+    .hooks.internal.entries["agent-changelog-commit"].enabled = true
+  ' "$OPENCLAW_CFG" > "$TMP" && mv "$TMP" "$OPENCLAW_CFG"
+  success "Hooks enabled in config"
+else
+  warn "Could not update hook config — enable manually after restarting:"
+  for hook in "${HOOKS[@]}"; do
+    echo "  - \`openclaw hooks enable $hook\`"
+  done
+fi
+
+# ─── Register cron ────────────────────────────────────────────────────
+header "⏱️  Registering cron"
+
+if command -v openclaw &>/dev/null; then
+  CRON_NAME="agent-changelog-commit"
+  CRON_CMD="bash $SCRIPT_DIR/scripts/commit.sh"
+  if openclaw cron list --json 2>/dev/null | jq -e --arg name "$CRON_NAME" '.jobs[] | select(.name == $name)' >/dev/null 2>&1; then
+    success "Cron \`$CRON_NAME\` already registered"
+  elif openclaw cron add \
+    --name "$CRON_NAME" \
+    --cron "*/10 * * * *" \
+    --message "$CRON_CMD" \
+    --session isolated \
+    --no-deliver >/dev/null 2>&1; then
+    success "Registered \`$CRON_NAME\` _(every 10 min)_"
+  else
+    warn "Cron registration failed — check with: \`openclaw cron list\`"
+  fi
+else
+  warn "Register cron manually after gateway starts:"
+  echo "  \`openclaw cron add --name agent-changelog-commit --cron '*/10 * * * *' --message 'bash $SCRIPT_DIR/scripts/commit.sh' --session isolated --no-deliver\`"
+fi
+
+# ─── Initialize git repo ──────────────────────────────────────────────
+header "📦 Git repository"
+
+if [ -d "$WORKSPACE/.git" ]; then
+  COMMIT_COUNT=$(cd "$WORKSPACE" && git rev-list --count HEAD 2>/dev/null || echo "0")
+  success "Already initialized _($COMMIT_COUNT commits)_"
+else
+  (cd "$WORKSPACE" && git init -b main) >/dev/null 2>&1
+  success "Initialized git repository"
+fi
+
+if [ ! -f "$WORKSPACE/.gitignore" ]; then
+  cat > "$WORKSPACE/.gitignore" << 'GITIGNORE'
+# secrets
+.env
+.env.*
+*.env
+.envrc
+**/credentials/
+**/secrets/
+**/.credentials
+**/.secrets
+**/api_key*
+**/apikey*
+**/*_key.txt
+**/*_key.json
+**/*_token*
+**/*_secret*
+**/auth_token*
+**/access_token*
+**/refresh_token*
+*.pem
+*.key
+*.p12
+*.pfx
+id_rsa
+id_ed25519
+*.ppk
+client_secret*.json
+service_account*.json
+*-credentials.json
+.aws/
+.azure/
+.gcloud/
+gcloud*.json
+aws_credentials
+
+# runtime
+*.log
+*.tmp
+*.temp
+*.swp
+*.swo
+*~
+*.jsonl
+.version-context
+state/
+state.json
+memory/
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# openclaw internal
+.openclaw/
+
+# build
+node_modules/
+__pycache__/
+*.pyc
+.cache/
+dist/
+build/
+*.egg-info/
+GITIGNORE
+  success "Created \`.gitignore\`"
+else
+  warn ".gitignore already exists and was left untouched. Review it before pushing to a remote to make sure secrets are excluded."
+fi
+
+# ─── Seed workspace config ────────────────────────────────────────────
+header "🔧 Workspace config"
+
+WORKSPACE_CFG="$WORKSPACE/.agent-changelog.json"
+if [ ! -f "$WORKSPACE_CFG" ]; then
+  cat > "$WORKSPACE_CFG" << 'EOF'
+{
+  "tracked": [
+    "."
+  ]
+}
+EOF
+  success "Created \`.agent-changelog.json\`"
+else
+  success "\`.agent-changelog.json\` already exists — leaving as-is"
+fi
+
+# ─── First snapshot ───────────────────────────────────────────────────
+header "📸 First snapshot"
+
+cd "$WORKSPACE"
+while IFS= read -r f; do
+  git add "$f" 2>/dev/null || true
+done < <(jq -r '.tracked[]?' "$WORKSPACE/.agent-changelog.json" 2>/dev/null)
+
+if ! git diff --cached --quiet 2>/dev/null; then
+  git commit -m "Initial snapshot — agent versioning setup" >/dev/null 2>&1
+  HASH=$(git rev-parse --short HEAD)
+  success "Snapshot \`$HASH\` created"
+else
+  echo "_No new files to commit_"
+fi
+
+# ─── Done ─────────────────────────────────────────────────────────────
+echo ""
+echo "🎉 **Setup complete!**"