/whats-new — Changelog Cross-Reference

Inspired by Brad Feld's whats-new plugin. Our version tracks FOUR products and cross-references against the full golems ecosystem.

What This Skill Does

Fetches the latest release notes for tools you depend on, diffs them against your actual configuration, and produces a structured report of:

1. BREAKING / AFFECTS YOU -- changes that directly touch something in your setup
2. NEW CAPABILITY -- features you should consider adopting given what you already use
3. FYI -- everything else, collapsed to one-liners

CRITICAL: Changelog Size Limits

NEVER fetch a full changelog page via crawling_exa with maxCharacters > 3000. The Anthropic changelog alone is 200K+ characters. Fetching it causes "result exceeds maximum" errors and the skill fails. Always use: GitHub API (preferred), freshness-scoped search, OR crawling with maxCharacters: 3000 (gets only the most recent entries at the top of the page). This applies to ALL products — Claude Code, Codex CLI, Cursor CLI, and Wispr Flow release pages all grow over time.

Products Tracked and Cross-Reference Targets

Full per-product sources, version commands, and what to check in each surface: references/products-and-targets.md. Changelog URLs: references/changelog-sources.md.

Cross-reference every entry against: A ~/.claude/settings.json · B ~/.claude/skills/ · C ~/.claude/hooks/ · D MCP servers across repos · E VoiceBar competitive intel ($HOME/Gits/voicelayer/) · F repoGolem launchers (Codex + Cursor routing) · G plugins (enabledPlugins).

Execution Procedure

Step 0: Schema Snapshot & Diff (reverse-engineering undocumented changes)

Save a snapshot of the current Claude Code CLI surface and diff against the previous version:

# Save current snapshot
ver=$(claude --version | head -1 | awk '{print $1}')
snapshot_dir=~/.claude/schema-snapshots
mkdir -p "${snapshot_dir}"

version_sort() {
  if command -v gsort >/dev/null 2>&1; then
    gsort -V
  else
    python3 -c 'import re, sys
def key(value):
    return [int(part) if part.isdigit() else part.lower() for part in re.split(r"([0-9]+)", value.rstrip())]
for line in sorted((line.rstrip("\n") for line in sys.stdin if line.strip()), key=key):
    print(line)'
  fi
}

find_previous_snapshot() {
  pattern="$1"
  current_file="$2"
  find "${snapshot_dir}" -maxdepth 1 -name "${pattern}" -type f 2>/dev/null \
    | version_sort \
    | grep -F -v "${current_file}" \
    | tail -1
}

# CLI help (all flags)
claude --help > "${snapshot_dir}/help-${ver}.txt" 2>&1

# Environment variables (from installed package)
pkg_path=""
if npm_root=$(npm root -g); then
  candidate="${npm_root}/@anthropic-ai/claude-code"
  if [ -f "${candidate}/cli.mjs" ]; then
    pkg_path="${candidate}"
  fi
fi
if [ -z "${pkg_path}" ]; then
  claude_bin=$(command -v claude)
  claude_real=$(python3 -c 'import os, sys; print(os.path.realpath(sys.argv[1]))' "${claude_bin}")
  if candidate=$(cd "$(dirname "${claude_real}")/../lib/node_modules/@anthropic-ai/claude-code" 2>/dev/null && pwd); then
    if [ -f "${candidate}/cli.mjs" ]; then
      pkg_path="${candidate}"
    fi
  fi
fi
if [ -z "${pkg_path}" ]; then
  echo "Error: could not locate @anthropic-ai/claude-code via npm root -g or the claude binary layout" >&2
  exit 1
fi
grep -rohE "CLAUDE_CODE_[A-Z_]+" "${pkg_path}/cli.mjs" | sort -u > "${snapshot_dir}/envvars-${ver}.txt"

# Find previous snapshot
prev=$(find_previous_snapshot "help-[0-9]*.txt" "${snapshot_dir}/help-${ver}.txt")

# Codex CLI snapshot
prev_codex=""
if command -v codex >/dev/null 2>&1; then
  codex_bin=$(command -v codex)
  codex_ver=$(codex --version 2>/dev/null || echo unknown)
  codex --help > "${snapshot_dir}/help-codex-${codex_ver}.txt" 2>&1
  if [ -n "${codex_bin}" ]; then
    grep -aohE "CODEX_[A-Z_]+" "${codex_bin}" 2>/dev/null | sort -u > "${snapshot_dir}/envvars-codex-${codex_ver}.txt"
  fi
  prev_codex=$(find_previous_snapshot "help-codex-*.txt" "${snapshot_dir}/help-codex-${codex_ver}.txt")
fi

# Antigravity CLI (agy) snapshot. The bare `gemini` CLI is dead for this
# account; agy is the live Gemini-family CLI (flags on --help, AGY_* env vars).
prev_agy=""
if command -v agy >/dev/null 2>&1; then
  agy_bin=$(command -v agy)
  agy_ver=$(agy --version 2>/dev/null | head -1)
  [ -n "${agy_ver}" ] || agy_ver=unknown
  agy --help > "${snapshot_dir}/help-agy-${agy_ver}.txt" 2>&1
  if [ -n "${agy_bin}" ]; then
    grep -aohE "AGY_[A-Z_]+" "${agy_bin}" 2>/dev/null | sort -u > "${snapshot_dir}/envvars-agy-${agy_ver}.txt"
  fi
  prev_agy=$(find_previous_snapshot "help-agy-*.txt" "${snapshot_dir}/help-agy-${agy_ver}.txt")
fi

# Cursor CLI snapshot
prev_cursor=""
if command -v cursor >/dev/null 2>&1; then
  cursor_bin=$(command -v cursor)
  cursor_ver=$(cursor --version 2>/dev/null || echo unknown)
  cursor --help > "${snapshot_dir}/help-cursor-${cursor_ver}.txt" 2>&1
  if [ -n "${cursor_bin}" ]; then
    grep -aohE "CURSOR_[A-Z_]+" "${cursor_bin}" 2>/dev/null | sort -u > "${snapshot_dir}/envvars-cursor-${cursor_ver}.txt"
  fi
  prev_cursor=$(find_previous_snapshot "help-cursor-*.txt" "${snapshot_dir}/help-cursor-${cursor_ver}.txt")
fi

If a previous snapshot exists, diff:

if [ -n "$prev" ]; then
  prev_ver=$(basename "$prev" | sed 's/help-//;s/.txt//')
  echo "=== Diffing v${prev_ver} \u2192 v${ver} ==="

  # New CLI flags
  diff <(grep '^\s*--' "${snapshot_dir}/help-${prev_ver}.txt" | sort) \
       <(grep '^\s*--' "${snapshot_dir}/help-${ver}.txt" | sort) | grep '^>'

  # New env vars
  diff "${snapshot_dir}/envvars-${prev_ver}.txt" \
       "${snapshot_dir}/envvars-${ver}.txt" | grep '^>'
fi

if [ -n "$prev_codex" ] && [ -n "${codex_ver:-}" ]; then
  prev_codex_ver=$(basename "$prev_codex" | sed 's/help-codex-//;s/.txt//')
  echo "=== Diffing Codex ${prev_codex_ver} -> ${codex_ver} ==="

  diff <(grep '^\s*--' "${snapshot_dir}/help-codex-${prev_codex_ver}.txt" | sort) \
       <(grep '^\s*--' "${snapshot_dir}/help-codex-${codex_ver}.txt" | sort) | grep '^>'

  diff "${snapshot_dir}/envvars-codex-${prev_codex_ver}.txt" \
       "${snapshot_dir}/envvars-codex-${codex_ver}.txt" | grep '^>'
fi

if [ -n "$prev_agy" ] && [ -n "${agy_ver:-}" ]; then
  prev_agy_ver=$(basename "$prev_agy" | sed 's/help-agy-//;s/.txt//')
  echo "=== Diffing Antigravity (agy) ${prev_agy_ver} -> ${agy_ver} ==="

  diff <(grep '^\s*--' "${snapshot_dir}/help-agy-${prev_agy_ver}.txt" | sort) \
       <(grep '^\s*--' "${snapshot_dir}/help-agy-${agy_ver}.txt" | sort) | grep '^>'

  diff "${snapshot_dir}/envvars-agy-${prev_agy_ver}.txt" \
       "${snapshot_dir}/envvars-agy-${agy_ver}.txt" | grep '^>'
fi

if [ -n "$prev_cursor" ] && [ -n "${cursor_ver:-}" ]; then
  prev_cursor_ver=$(basename "$prev_cursor" | sed 's/help-cursor-//;s/.txt//')
  echo "=== Diffing Cursor ${prev_cursor_ver} -> ${cursor_ver} ==="

  diff <(grep '^\s*--' "${snapshot_dir}/help-cursor-${prev_cursor_ver}.txt" | sort) \
       <(grep '^\s*--' "${snapshot_dir}/help-cursor-${cursor_ver}.txt" | sort) | grep '^>'

  diff "${snapshot_dir}/envvars-cursor-${prev_cursor_ver}.txt" \
       "${snapshot_dir}/envvars-cursor-${cursor_ver}.txt" | grep '^>'
fi

Any new flags or env vars found = classify as "AFFECTS YOU" automatically, even if no changelog mentions them. These are undocumented changes that the changelog fetch in Step 3 might miss.

Why this matters: Claude Code publishes to npm faster than changelogs update. Versions 2.1.102-104 had zero release notes but contained actual new flags (--bare, --tmux, --brief, CLAUDE_CODE_AGENT_COST_STEER, CLAUDE_CODE_AUTO_COMPACT_WINDOW) discoverable only through binary introspection.

Step 1: Gather Current State

Run ALL of these in parallel (independent data gathering):

# Current versions
claude --version
codex --version 2>/dev/null || echo "codex: check npx @openai/codex --version"
cursor --version 2>/dev/null || echo "cursor: not installed or not in PATH"

# Settings
cat ~/.claude/settings.json

# Skills count
ls ~/.claude/skills/ | wc -l

# Hooks
ls ~/.claude/hooks/

# Plugins list
cat ~/.claude/settings.json | python3 -c "import json,sys; d=json.load(sys.stdin); [print(k) for k in d.get('enabledPlugins', {}).keys()]"

# repoGolem registry (launcher configs)
: "${ORCHESTRATOR_REPO:?ORCHESTRATOR_REPO must be set}"
cat "$ORCHESTRATOR_REPO/repoGolem/registry.json" 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'{len(d)} launchers registered')"

Step 2: Check BrainLayer for Last Review

brain_search("whats-new changelog review last version")

If a prior review exists, note the last-reviewed versions. Only analyze entries AFTER those versions.

Step 3: Fetch Changelogs

Use the last-reviewed version from Step 2 (BrainLayer) to scope what you fetch. For each product, follow the tiered fetch strategy — try each step in order, stop when you get useful results.

Claude Code (3-tier):

# Tier 1 (PRIMARY): GitHub Releases API — structured, reliable, always current
curl -s "https://api.github.com/repos/anthropics/claude-code/releases?per_page=5"

# Tier 2 (FALLBACK): exa search with freshness cascade
mcp__exa__web_search_exa(query: "Claude Code changelog [INSTALLED_VERSION]", freshness: "week", includeDomains: ["docs.anthropic.com", "github.com/anthropics"])
# If empty, try freshness: "month"
mcp__exa__web_search_exa(query: "Claude Code changelog latest release", freshness: "month", includeDomains: ["docs.anthropic.com", "github.com/anthropics"])

# Tier 3 (LAST RESORT): Crawl only the top of the changelog page
mcp__exa__crawling_exa(urls: ["https://docs.anthropic.com/en/docs/claude-code/changelog"], maxCharacters: 3000)

Wispr Flow:

mcp__exa__crawling_exa(urls: ["https://releasebot.io/updates/wispr-flow"], maxCharacters: 3000)

Codex CLI (2-tier):

# Tier 1: exa search with freshness cascade
mcp__exa__web_search_exa(query: "OpenAI Codex CLI changelog latest release", freshness: "week", includeDomains: ["developers.openai.com", "github.com/openai"])
# If empty, try freshness: "month"
mcp__exa__web_search_exa(query: "OpenAI Codex CLI changelog latest release", freshness: "month", includeDomains: ["developers.openai.com", "github.com/openai"])

# Tier 2: Crawl only the top of the changelog page
mcp__exa__crawling_exa(urls: ["https://developers.openai.com/codex/changelog"], maxCharacters: 3000)

Cursor CLI (2-tier):

# Tier 1: exa search with freshness cascade
mcp__exa__web_search_exa(query: "Cursor IDE CLI changelog latest release agent mode", freshness: "week", includeDomains: ["cursor.com", "cursor.sh"])
# If empty, try freshness: "month"
mcp__exa__web_search_exa(query: "Cursor IDE CLI changelog latest release agent mode", freshness: "month", includeDomains: ["cursor.com", "cursor.sh"])

# Tier 2: Crawl only the top of the changelog page
mcp__exa__crawling_exa(urls: ["https://www.cursor.com/changelog"], maxCharacters: 3000)

Step 4: Cross-Reference and Classify

Step 0 schema diffs are pre-classified as AFFECTS YOU. Merge them with changelog findings -- if a flag appears in BOTH the schema diff AND the changelog, prefer the changelog description.

For EACH changelog entry, classify into exactly one category:

AFFECTS YOU (priority: critical) The change touches a specific config you have. Examples:

• "Fixed PreToolUse hooks..." -- you have 4 PreToolUse hooks
• "MCP tool descriptions capped at 2KB" -- you have 5 MCP servers
• "Skill descriptions capped at 250 chars" -- you have 50+ skills
• "Fixed hooks on macOS" -- you're on macOS
• "Voice push-to-talk fix" -- you have voiceEnabled: true

NEW CAPABILITY (priority: medium) The change adds something you don't use yet but should consider. Examples:

• "Added conditional if field for hooks" -- you could optimize your PreToolUse hooks
• "Added TaskCreated hook" -- you have subagent workflows that could benefit
• "New env var for MCP headers" -- you manage multiple MCP servers

FYI (priority: low) Everything else. Windows fixes, VSCode-only changes, features for plans you don't have, etc.

Step 5: Generate Report

Use this exact format:

# What's New -- YYYY-MM-DD

## Versions Checked
- **Claude Code:** vX.Y.Z (installed) | changelog up to vA.B.C
- **Codex CLI:** vX.Y.Z (installed) | changelog up to vA.B.C
- **Cursor CLI:** vX.Y.Z (installed) | changelog up to vA.B.C
- **Wispr Flow:** latest release (YYYY-MM-DD)
- **Last reviewed:** vX.Y.Z (Claude Code) / YYYY-MM-DD (others)

---

## AFFECTS YOU

### [Claude Code / Wispr Flow] -- Short description
**What changed:** One-line summary
**Your config:** Which specific file/setting is affected
**Action needed:** What to check, change, or test
**Risk:** HIGH / MEDIUM / LOW

---

## NEW CAPABILITIES

### [Claude Code / Wispr Flow] -- Short description
**What's new:** One-line summary
**Why it matters for you:** How this intersects with your current setup
**Adoption effort:** TRIVIAL / SMALL / MEDIUM
**Suggested action:** Concrete next step

---

## FYI
- [CC] Fixed VSCode extension showing "Not responding" during long ops
- [CC] Improved PowerShell dangerous command detection
- [WF] Android early access launched
- ...

---

## VoiceBar Competitive Notes
_(Only if Wispr Flow had relevant updates; template in references/products-and-targets.md)_

Step 6: Store in BrainLayer

brain_store(
  content: "whats-new review YYYY-MM-DD: Claude Code vX.Y.Z, Codex vX.Y.Z, Cursor vX.Y.Z, Wispr Flow latest. AFFECTS: [count] items ([summary]). NEW CAPABILITIES: [count] items ([summary]). Key actions: [list]. VoiceBar notes: [summary].",
  tags: ["whats-new", "changelog", "claude-code", "codex-cli", "cursor-cli", "wispr-flow", "<YYYY-MM-DD>"],
  importance: 7
)

Step 7: Notify if Critical

If any AFFECTS YOU item has risk HIGH:

notify "Whats New" "HIGH risk change in [product]: [summary]. Check [config file]."

Usage Examples

Default: Check everything since last review

/whats-new

Check specific Claude Code version

/whats-new 2.1.85

(Shows only changes from that version onward)

Quick check after update

/whats-new --quick

(Only AFFECTS YOU items, skip FYI)

Wispr Flow only

/whats-new --wispr

When to Run

• After claude --version shows a new version -- mandatory
• Weekly during maintenance -- as part of ecosystem-health routine
• After hearing about updates in community channels
• When something breaks unexpectedly -- check if a recent update caused it
• Proactively -- the changelog moves fast, don't fall behind

For a release-day rules check, use a clean temporary worktree or sandbox: record a baseline, temporarily remove two or three candidate rule files there, and keep a deletion only after a predefined non-destructive task matrix passes without changing the active workspace.

Edge Cases

• Exa is down: Fall back to WebSearch or WebFetch for changelog URLs. Report that live data was unavailable.
• GitHub API rate-limited: Fall through to exa Tier 2/3. Note the rate limit in the report.
• No prior review in BrainLayer: Assume first run. Show last 2-3 versions of Claude Code + last 2 Wispr Flow releases.
• Changelog format changed: If the page structure doesn't match expected format, flag it and attempt best-effort parsing.
• Version not found: If --version flag doesn't match any changelog entry, show the closest match and note the gap.
• Exa search returns nothing for "week": Expand to "month". If "month" also empty, use crawling with maxCharacters: 3000 as last resort.
• No previous schema snapshot: First run. Save snapshot, skip diff, note "baseline established" in the report.