claude-code-recap 1.2.0

package/install.sh

@@ -0,0 +1,249 @@
+#!/bin/sh
+# install.sh: install the recap skill for Claude Code.
+#
+#   curl -fsSL https://raw.githubusercontent.com/noluyorAbi/claude-code-recap/main/install.sh | sh
+#
+# Copies skills/recap into $CLAUDE_CONFIG_DIR/skills/recap (default ~/.claude/skills/recap).
+# Works from a git checkout and from a curl pipe, where $0 is not a usable path
+# and the skill files are fetched from GitHub instead.
+#
+# Flags:
+#   --force      overwrite an existing install, even if it was modified locally
+#   --uninstall  remove the files this script installed
+#   --help       show usage
+#
+# Env:
+#   CLAUDE_CONFIG_DIR   Claude Code config dir (default: $HOME/.claude)
+#   RECAP_REF           git ref to fetch when running from a pipe (default: main)
+#   RECAP_TARBALL       full tarball URL, overrides REPO/REF (used by the tests)
+
+set -eu
+
+REPO="noluyorAbi/claude-code-recap"
+REF="${RECAP_REF:-main}"
+SKILL_NAME="recap"
+MANIFEST_NAME=".claude-code-recap-manifest.json"
+TRACKED="SKILL.md recap.py"
+
+FORCE=0
+UNINSTALL=0
+TMPDIR_SELF=""
+
+usage() {
+  cat <<'EOF'
+install.sh: install the recap skill for Claude Code.
+
+Usage:
+  ./install.sh [--force] [--uninstall]
+  curl -fsSL https://raw.githubusercontent.com/noluyorAbi/claude-code-recap/main/install.sh | sh
+
+Options:
+  --force      overwrite an existing install, even if it has local edits
+  --uninstall  remove the files this script installed
+  -h, --help   show this help
+
+Environment:
+  CLAUDE_CONFIG_DIR  Claude Code config dir (default: $HOME/.claude)
+  RECAP_REF          git ref fetched when piped from curl (default: main)
+EOF
+}
+
+die() {
+  printf 'install.sh: %s\n' "$1" >&2
+  exit 1
+}
+
+cleanup() {
+  if [ -n "$TMPDIR_SELF" ] && [ -d "$TMPDIR_SELF" ]; then
+    rm -rf "$TMPDIR_SELF"
+  fi
+}
+trap cleanup EXIT HUP INT TERM
+
+for arg in "$@"; do
+  case "$arg" in
+    --force) FORCE=1 ;;
+    --uninstall) UNINSTALL=1 ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf 'install.sh: unknown option: %s\n\n' "$arg" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+DEST="$CONFIG_DIR/skills/$SKILL_NAME"
+MANIFEST="$DEST/$MANIFEST_NAME"
+
+sha256() {
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$1" | awk '{print $1}'
+  elif command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | awk '{print $1}'
+  else
+    die "need shasum or sha256sum to verify installed files"
+  fi
+}
+
+# Emit "<relative-path> <sha256>" for every file recorded in the manifest.
+manifest_entries() {
+  sed -n '/"files"[[:space:]]*:/,/}/p' "$1" |
+    sed -n 's/^[[:space:]]*"\([^"]*\)"[[:space:]]*:[[:space:]]*"\([0-9a-f]\{64\}\)".*/\1 \2/p'
+}
+
+# Print every tracked file whose content no longer matches the manifest.
+modified_files() {
+  [ -f "$MANIFEST" ] || return 0
+  manifest_entries "$MANIFEST" | while read -r rel recorded; do
+    [ -f "$DEST/$rel" ] || continue
+    if [ "$(sha256 "$DEST/$rel")" != "$recorded" ]; then
+      printf '%s\n' "$rel"
+    fi
+  done
+}
+
+skill_version() {
+  sed -n 's/^[[:space:]]\{1,\}version:[[:space:]]*"\{0,1\}\([0-9][0-9A-Za-z.+-]*\)"\{0,1\}[[:space:]]*$/\1/p' "$1" |
+    head -n 1
+}
+
+# ---------- uninstall ----------
+if [ "$UNINSTALL" -eq 1 ]; then
+  if [ ! -d "$DEST" ]; then
+    printf 'recap is not installed (%s does not exist).\n' "$DEST"
+    exit 0
+  fi
+
+  if [ ! -f "$MANIFEST" ]; then
+    if [ "$FORCE" -ne 1 ]; then
+      printf 'install.sh: %s exists but was not installed by this script (no manifest).\n' "$DEST" >&2
+      printf 'Refusing to remove it. Re-run with --force to delete it anyway.\n' >&2
+      exit 1
+    fi
+    rm -rf "$DEST"
+    printf 'Removed %s (forced, no manifest).\n' "$DEST"
+    exit 0
+  fi
+
+  changed="$(modified_files)"
+  if [ -n "$changed" ] && [ "$FORCE" -ne 1 ]; then
+    printf 'install.sh: these installed files have local edits:\n' >&2
+    printf '%s\n' "$changed" | sed 's/^/  /' >&2
+    printf 'Refusing to delete them. Back them up, then re-run with --force.\n' >&2
+    exit 1
+  fi
+
+  manifest_entries "$MANIFEST" | while read -r rel _hash; do
+    rm -f "$DEST/$rel"
+  done
+  rm -f "$MANIFEST"
+  # Prune empty directories bottom-up, including DEST itself when nothing is left.
+  find "$DEST" -depth -type d -empty -exec rmdir {} + 2>/dev/null || true
+
+  if [ -d "$DEST" ]; then
+    printf 'Removed the recap skill files from %s.\n' "$DEST"
+    printf 'Kept the directory: it still contains files this script did not install.\n'
+  else
+    printf 'Removed %s.\n' "$DEST"
+  fi
+  exit 0
+fi
+
+# ---------- locate the skill source ----------
+SRC=""
+SCRIPT_DIR=""
+case "${0:-}" in
+  ''|sh|-sh|bash|-bash|dash|-dash|zsh|-zsh) : ;;
+  *)
+    if [ -f "$0" ]; then
+      SCRIPT_DIR="$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)"
+    fi
+    ;;
+esac
+
+if [ -n "$SCRIPT_DIR" ] && [ -f "$SCRIPT_DIR/skills/$SKILL_NAME/SKILL.md" ]; then
+  SRC="$SCRIPT_DIR/skills/$SKILL_NAME"
+else
+  # Curl pipe: no local checkout, fetch the tarball.
+  command -v curl >/dev/null 2>&1 || die "curl is required to fetch the skill"
+  command -v tar >/dev/null 2>&1 || die "tar is required to unpack the skill"
+  TMPDIR_SELF="$(mktemp -d 2>/dev/null || mktemp -d -t recap)"
+  TARBALL="${RECAP_TARBALL:-https://codeload.github.com/$REPO/tar.gz/$REF}"
+  printf 'Fetching %s@%s ...\n' "$REPO" "$REF"
+  curl -fsSL --retry 2 -o "$TMPDIR_SELF/src.tar.gz" "$TARBALL" ||
+    die "could not download $TARBALL"
+  tar -xzf "$TMPDIR_SELF/src.tar.gz" -C "$TMPDIR_SELF" ||
+    die "could not unpack the archive downloaded from $TARBALL"
+  SRC="$(find "$TMPDIR_SELF" -type d -path "*/skills/$SKILL_NAME" | head -n 1)"
+  [ -n "$SRC" ] || die "downloaded archive does not contain skills/$SKILL_NAME"
+fi
+
+[ -f "$SRC/SKILL.md" ] || die "missing $SRC/SKILL.md"
+[ -f "$SRC/recap.py" ] || die "missing $SRC/recap.py"
+
+# The Agent Skills spec requires SKILL.md `name` to equal the directory name.
+DECLARED="$(sed -n 's/^name:[[:space:]]*\([a-z0-9][a-z0-9-]*\)[[:space:]]*$/\1/p' "$SRC/SKILL.md" | head -n 1)"
+[ "$DECLARED" = "$SKILL_NAME" ] ||
+  die "SKILL.md declares name '$DECLARED' but must declare '$SKILL_NAME'"
+
+VERSION="$(skill_version "$SRC/SKILL.md")"
+[ -n "$VERSION" ] || VERSION="unknown"
+
+# ---------- guard an existing install ----------
+if [ -d "$DEST" ]; then
+  if [ -f "$MANIFEST" ]; then
+    changed="$(modified_files)"
+    if [ -n "$changed" ] && [ "$FORCE" -ne 1 ]; then
+      printf 'install.sh: these installed files have local edits:\n' >&2
+      printf '%s\n' "$changed" | sed 's/^/  /' >&2
+      printf 'Refusing to overwrite them. Back them up, then re-run with --force.\n' >&2
+      exit 1
+    fi
+    manifest_entries "$MANIFEST" | while read -r rel _hash; do
+      rm -f "$DEST/$rel"
+    done
+    rm -f "$MANIFEST"
+  elif [ "$FORCE" -ne 1 ]; then
+    printf 'install.sh: %s already exists and was not installed by this script.\n' "$DEST" >&2
+    printf 'Refusing to overwrite it. Move it aside, or re-run with --force.\n' >&2
+    exit 1
+  fi
+fi
+
+# ---------- install ----------
+mkdir -p "$DEST"
+cp "$SRC/SKILL.md" "$DEST/SKILL.md"
+cp "$SRC/recap.py" "$DEST/recap.py"
+chmod 0644 "$DEST/SKILL.md"
+chmod 0755 "$DEST/recap.py"
+
+SKILL_SHA="$(sha256 "$DEST/SKILL.md")"
+RECAP_SHA="$(sha256 "$DEST/recap.py")"
+NOW="$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+
+{
+  printf '{\n'
+  printf '  "tool": "claude-code-recap",\n'
+  printf '  "version": "%s",\n' "$VERSION"
+  printf '  "installedAt": "%s",\n' "$NOW"
+  printf '  "files": {\n'
+  printf '    "SKILL.md": "%s",\n' "$SKILL_SHA"
+  printf '    "recap.py": "%s"\n' "$RECAP_SHA"
+  printf '  }\n'
+  printf '}\n'
+} >"$MANIFEST"
+
+printf '\nInstalled the recap skill (v%s).\n' "$VERSION"
+printf '  %s\n' "$DEST/SKILL.md"
+printf '  %s\n' "$DEST/recap.py"
+printf '\nClaude Code picks up %s/skills without a restart.\n' "$CONFIG_DIR"
+printf 'Restart it only if that directory did not exist when the session started.\n'
+printf '\nRun it with:  /recap\n'
+printf 'Or directly:  python3 %s\n' "$DEST/recap.py"
+printf 'Uninstall:    ./install.sh --uninstall\n'
+
+if ! command -v python3 >/dev/null 2>&1; then
+  printf '\nWarning: python3 was not found on PATH. The skill needs Python 3 to run.\n' >&2
+fi
+
+for rel in $TRACKED; do
+  [ -f "$DEST/$rel" ] || die "post-install check failed: $DEST/$rel is missing"
+done

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "claude-code-recap",
+  "version": "1.2.0",
+  "description": "Installs the recap skill into your Claude Code skills directory: list recent sessions across every project and get a ready-to-paste resume command.",
+  "type": "module",
+  "bin": {
+    "claude-code-recap": "bin/cli.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "install.sh",
+    "!**/__pycache__",
+    "!**/*.pyc"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-code-skills",
+    "claude-code-skill",
+    "claude-skill",
+    "agent-skills",
+    "agent-skill",
+    "skill-md",
+    "skills",
+    "anthropic",
+    "claude",
+    "session-recap",
+    "resume",
+    "developer-tools",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noluyorAbi/claude-code-recap.git"
+  },
+  "homepage": "https://github.com/noluyorAbi/claude-code-recap#readme",
+  "bugs": {
+    "url": "https://github.com/noluyorAbi/claude-code-recap/issues"
+  },
+  "license": "MIT",
+  "author": "noluyorAbi <121226886+noluyorAbi@users.noreply.github.com>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check:version": "node scripts/check-version.mjs",
+    "test": "sh tests/smoke.sh"
+  }
+}

package/skills/recap/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: recap
+description: Show recent Claude Code sessions across all projects, so the user can re-enter work after a reboot or context switch. Lists per session the absolute project path, a short summary, last activity, turn count, git branch, model, and a ready-to-paste resume command, and can re-open all of them at once in new terminal tabs. Use when the user asks "what was I working on", "which projects did I touch recently", "where did I leave off", "list my recent sessions", "how do I get back into that session", "open all my sessions again", or invokes /recap. Reads only local files; the default run is instant and offline.
+license: MIT
+metadata:
+  version: "1.2.0"
+  author: noluyorAbi
+  source: https://github.com/noluyorAbi/claude-code-recap
+---
+
+# recap: re-entry radar for Claude Code sessions
+
+One command, full overview of recent sessions across every project on this machine. Built for the post-reboot moment: which projects, what was each session about, and the exact command to jump back in.
+
+## How to run it
+
+Personal or project install (the skill directory is on disk next to this file):
+
+```bash
+python3 ~/.claude/skills/recap/recap.py [flags]
+```
+
+Plugin install (Claude Code exports the plugin root):
+
+```bash
+python3 "$CLAUDE_PLUGIN_ROOT/skills/recap/recap.py" [flags]
+```
+
+Nothing to install beyond Python 3 (stdlib only, no third-party packages).
+
+| Flag | Meaning |
+|------|---------|
+| (none) | last 15 sessions, newest first, instant, no network |
+| `--since 7d` | only sessions active in the window (`30m`, `24h`, `7d`, `2w`) |
+| `--project foo` | filter by substring of the absolute project path |
+| `--limit N` | max rows (default 15) |
+| `--json` | machine-readable output with full session ids and resume commands |
+| `--smart` | real one-sentence summaries via ONE `claude -p` haiku call (network, ~10s) |
+| `--pick` | choose a row interactively, then `cd` + `claude -r` into it directly |
+| `--open` | open EVERY listed session in its own new terminal tab and resume it there (macOS) |
+| `--claude-flags "..."` | extra flags for each resumed `claude` (e.g. `"--chrome --dangerously-skip-permissions"`); also shown in the printed resume lines and `--json` |
+| `--terminal auto\|iTerm2\|Terminal` | which app `--open` drives (default: iTerm2 when installed) |
+| `--yes` / `-y` | skip the `--open` confirmation prompt (required when stdin is not a TTY) |
+| `--dry-run` | with `--open`: print the tabs and commands, open nothing |
+| `--color` | force ANSI colors when output is piped (e.g. inside Claude Code) |
+| `--plain` | no ANSI at all (also honors NO_COLOR / FORCE_COLOR env) |
+
+## Usage examples
+
+```bash
+# after a reboot: what was I doing?
+python3 ~/.claude/skills/recap/recap.py
+
+# everything in one repo this week
+python3 ~/.claude/skills/recap/recap.py --since 7d --project my-repo
+
+# jump straight back into a session
+python3 ~/.claude/skills/recap/recap.py --pick
+
+# re-open yesterday's whole working set in terminal tabs, browser enabled, no permission prompts
+python3 ~/.claude/skills/recap/recap.py --since 24h --limit 12 \
+  --open --yes --claude-flags "--chrome --dangerously-skip-permissions"
+
+# preview first, open nothing
+python3 ~/.claude/skills/recap/recap.py --open --dry-run
+
+# feed into other tooling
+python3 ~/.claude/skills/recap/recap.py --json --limit 50
+```
+
+## The `--open` flag
+
+Restores a whole working set at once. It opens one new tab per listed session and types the resume command into it. Rules:
+
+- The session recap itself runs in is skipped automatically (matched on `CLAUDE_CODE_SESSION_ID`), so it never re-opens itself.
+- Sessions whose project directory no longer exists are skipped and reported, never opened.
+- Scope comes from the normal filters, so `--limit` / `--since` / `--project` decide exactly which tabs appear. Check with `--dry-run` before committing.
+- Without `--yes` it asks for confirmation; with piped stdin (Claude Code's Bash tool) it refuses to open unless `--yes` is passed.
+- `--claude-flags` is passed through verbatim to every tab. `--dangerously-skip-permissions` disables all permission checks in each opened session; the script prints a warning before doing it.
+- Tab opening drives iTerm2 or Terminal through `osascript`, so it is macOS-only. On other platforms `--open` exits with a clear message; `--open --dry-run` still prints the commands so they can be pasted anywhere.
+
+## When Claude runs this skill
+
+Run the script with Bash, ALWAYS with `--color` (tool output is piped, auto-detection would strip the colors; Claude Code renders ANSI). Add `--since`/`--project` if the user narrowed the question, then relay the table. Quote the resume command (`cd <path> && claude -r <id>`) for any session the user wants to re-enter. Only add `--smart` if the user explicitly asks for better summaries; it makes a network call.
+
+Use `--open` only when the user explicitly asks to re-open or resume the sessions. Because the Bash tool pipes stdin, `--open` needs `--yes`; treat the user's request as the confirmation, and set the scope with `--limit`/`--since` so no unwanted session gets a tab. Pass `--claude-flags` only with flags the user named; state the permission-bypass warning in your reply whenever `--dangerously-skip-permissions` is among them.
+
+## Data sources and guarantees
+
+- `~/.claude/history.jsonl` is the fast index (prompt text, timestamp, project path, session id). `CLAUDE_CONFIG_DIR` is honored when set.
+- `~/.claude/projects/<encoded>/<session>.jsonl` transcripts are parsed only for the displayed rows (title, branch, model, turn count). Project paths always come from the `cwd`/`project` fields, never decoded from folder names (that encoding is lossy).
+- Summary preference: Claude Code's own `ai-title` line, else the first real user prompt, else `(no prompt)`.
+- `--smart` privacy: the only path that leaves the machine. It shells out to the local `claude` CLI once and sends, for the listed sessions only, each session's 8-character id prefix, its title (first 150 characters), and its first user prompt (first 300 characters). No file bodies, no transcript contents, no other sessions. If `claude` is not on PATH, `--smart` is skipped with a warning and the offline summaries are used.
+- Turn count groups assistant streaming chunks by message id and is labeled approximate.
+- Broken or partial JSONL lines are skipped, never fatal. Times shown in the local timezone.
+- Display: day-grouped timeline (Today green, Yesterday amber), 14-day activity sparkline in the header, per-project colored dot (stable hash), four-level gray hierarchy with one accent color, per-session resume line indented with spaces only (safe to copy). Falls back to plain text when piped or when NO_COLOR is set.
+- Read-only: the tool never writes or deletes anything. It sees only sessions still on disk (Claude Code prunes old ones). `--open` and `--pick` are the only side-effecting paths: `--open` drives iTerm2/Terminal via `osascript`, `--pick` `exec`s `claude -r` in the chosen directory. Neither writes or touches session data.
+
+## Optional shell alias
+
+```bash
+alias recap='python3 ~/.claude/skills/recap/recap.py'
+```