Changelog Skill

Status: Experimental — uses Claude Code PostToolUse hooks; the hook interface may change in future versions. If hooks don't fire, events can still be logged manually via auto-loop prompts.

Runtime observability changelog that records every change during a development session, so subagents can understand prior context and sessions can be recovered or debugged.

Overview

Automatically, via PostToolUse hooks, the changelog:

Records file changes (Write / Edit)
Logs test results when tests run (Bash)
Records git commits (Bash)
Rotates itself when it exceeds 500 lines

Events are stored as append-only JSONL at .director-mode/changelog.jsonl.

Usage

Via `/changelog` command

/changelog                  # Recent 10 events
/changelog --summary        # Statistics
/changelog --type test      # Filter by event type
/changelog --list-archives  # Show rotated changelogs
/changelog --export log.json
/changelog --archive        # Manually archive current changelog
/changelog --clear          # Clear current changelog

Via Bash

# Last 5 events
tail -n 5 .director-mode/changelog.jsonl | jq '.'

# All file changes
grep '"event_type":"file_' .director-mode/changelog.jsonl

# Count by type
jq -r '.event_type' .director-mode/changelog.jsonl | sort | uniq -c

Event Schema

{
  "id": "evt_1705142400_12345",
  "timestamp": "2025-01-13T10:30:00.000Z",
  "event_type": "file_edit",
  "agent": "hook",
  "iteration": 3,
  "summary": "file_edit: Login.tsx",
  "files": ["src/components/Login.tsx"]
}

Event Types

Type	Source	Description
`file_write`	Hook (Write)	File written via the Write tool
`file_edit`	Hook (Edit)	File edited via the Edit tool
`test_pass`	Hook (Bash)	Tests passing
`test_fail`	Hook (Bash)	Tests failing
`test_run`	Hook (Bash)	Tests ran, result undetermined
`commit`	Hook (Bash)	Git commit made
`session_start`	auto-loop	Session begins
`session_end`	auto-loop	Session completes
`changelog_rotated`	System	Changelog was rotated

Automatic Logging via Hooks

Configured in .claude/settings.local.json (the shipped template is hooks/settings-hooks.json):

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Write", "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/log-file-change.sh" }] },
      { "matcher": "Edit",  "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/log-file-change.sh" }] },
      { "matcher": "Bash",  "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/log-bash-event.sh" }] }
    ]
  }
}

$CLAUDE_PROJECT_DIR keeps paths portable (resolved at runtime by Claude Code).

Script	Trigger	Events Logged
`log-file-change.sh`	Write, Edit	`file_write`, `file_edit`
`log-bash-event.sh`	Bash	`test_pass`, `test_fail`, `test_run`, `commit`

Core helpers live in _lib-changelog.sh:

log_event "file_write" "Wrote Login.tsx" "hook" '["src/Login.tsx"]'
archive_changelog   # move current changelog to a timestamped archive
clear_changelog     # empty the current changelog
list_archives       # list rotated changelogs

Rotation & Archiving

Two independent thresholds keep the changelog bounded. They are complementary, not contradictory:

Trigger	Threshold	Who does it	When
Session-start archive	> 100 lines	`/auto-loop` init	At the start of each auto-loop session, so the new session begins with a fresh log
Runtime auto-rotation	> 500 lines (`MAX_LINES`)	`_lib-changelog.sh` (`rotate_if_needed`)	Continuously, as events are appended within a session

On rotation the current file is moved to changelog.YYYYMMDD_HHMMSS.jsonl, a fresh changelog.jsonl is started, and a changelog_rotated event is logged:

.director-mode/
├── changelog.jsonl                    ← Current
├── changelog.20250113_103000.jsonl    ← Archived
└── changelog.20250112_150000.jsonl    ← Archived

Checkpoint vs Changelog

Aspect	Checkpoint	Changelog
Location	`.auto-loop/checkpoint.json`	`.director-mode/changelog.jsonl`
Purpose	Current state snapshot ("where am I now?")	Historical event stream ("how did I get here?")
Used by	Stop hook (continue/stop decision)	Subagents (context)
Format	Single JSON object	JSONL (append-only)
Persistence	Overwritten each iteration	Accumulated, then rotated

Only one auto-loop session runs per project. Starting /auto-loop while a session is in_progress blocks with a prompt to use --resume (continue with the existing checkpoint + changelog) or --force (archive the old session, start fresh).

Subagent Integration

code-reviewer — before reviewing, checks recent file changes, the current iteration, and recent test results.
debugger — before debugging, checks when errors first appeared, which files changed just before them, and the pattern of test failures.

Installation

These legacy observability hooks ship as an explicit automation option. They are absent from the default zero-hook install. After intentionally running ./install.sh --hooks automation, verify:

ls .claude/hooks/
# _lib-changelog.sh  auto-loop-stop.sh  log-bash-event.sh  log-file-change.sh  pre-tool-validator.sh

cat .claude/settings.local.json | jq '.hooks'

Troubleshooting

Events not logged

Check hooks exist: ls .claude/hooks/*.sh
Check the live hook config: cat .claude/settings.local.json | jq '.hooks' (the shipped template is hooks/settings-hooks.json)
Check scripts are executable: chmod +x .claude/hooks/*.sh

Stale session blocking

cat .auto-loop/checkpoint.json | jq '.status'
/auto-loop --force "New task"

Changelog too large

/changelog --archive   # manual archive
/changelog --clear     # or clear

changelog