Changelog

Changelog Skill

> Status: Experimental > This feature uses Claude Code's PostToolUse hooks. The hook interface may change in future versions. > If hooks don't trigger as expected, events can still be logged manually via auto-loop prompts.

Runtime observability changelog for tracking all changes during development sessions.

---

Overview

This skill provides an automated changelog system that:

• Automatically records file changes via PostToolUse hooks
• Automatically logs test results when tests are run
• Automatically records git commits
• Automatically rotates when exceeding 500 lines
• Enables subagents to understand context from previous actions
• Supports session recovery and debugging

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Observability System                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐     ┌─────────────────────────────┐           │
│  │ Write/Edit  │     │           Bash              │           │
│  │    Tool     │     │   (test/commit/general)     │           │
│  └──────┬──────┘     └──────────────┬──────────────┘           │
│         │                           │                           │
│         ▼                           ▼                           │
│  ┌─────────────────────────────────────────────────────┐       │
│  │              PostToolUse Hooks                       │       │
│  │     log-file-change.sh       log-bash-event.sh      │       │
│  └─────────────────────────┬───────────────────────────┘       │
│                            │                                    │
│                            ▼                                    │
│  ┌─────────────────────────────────────────────────────┐       │
│  │           _lib-changelog.sh                        │       │
│  │  • log_event()      • rotate_if_needed()            │       │
│  │  • archive_changelog()  • clear_changelog()         │       │
│  └─────────────────────────┬───────────────────────────┘       │
│                            │                                    │
│                            ▼                                    │
│  ┌─────────────────────────────────────────────────────┐       │
│  │         .director-mode/changelog.jsonl               │       │
│  │                                                      │       │
│  │  {"event_type":"file_created",...}                  │       │
│  │  {"event_type":"test_pass",...}                     │       │
│  │  {"event_type":"commit",...}                        │       │
│  └─────────────────────────────────────────────────────┘       │
│                            │                                    │
│              ┌─────────────┴─────────────┐                     │
│              ▼                           ▼                     │
│  ┌─────────────────┐         ┌─────────────────┐               │
│  │  /changelog     │         │    Subagents    │               │
│  │   command       │         │ code-reviewer   │               │
│  │                 │         │ debugger        │               │
│  └─────────────────┘         └─────────────────┘               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

Relationship with Checkpoint

| Aspect | Checkpoint | Changelog | |--------|------------|-----------| | Location | .auto-loop/checkpoint.json | .director-mode/changelog.jsonl | | Purpose | Current state snapshot | Historical event stream | | Question answered | "Where am I now?" | "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 |

They complement each other:

• Checkpoint = Save point for resume
• Changelog = Audit trail for observability

---

Automatic Logging via Hooks

Hook Configuration (.claude/settings.local.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" }]
      }
    ]
  }
}

> Note: Uses $CLAUDE_PROJECT_DIR for portable paths (resolved at runtime by Claude Code).

Hook Scripts

| Script | Trigger | Events Logged | |--------|---------|---------------| | log-file-change.sh | Write, Edit | file_created, file_modified | | log-bash-event.sh | Bash | test_pass, test_fail, commit |

---

Automatic Rotation

Prevents unbounded growth:

MAX_LINES=500

# When changelog exceeds 500 lines:
# 1. Move current to changelog.YYYYMMDD_HHMMSS.jsonl
# 2. Start fresh changelog.jsonl
# 3. Log rotation event

Result:

.director-mode/
├── changelog.jsonl                    ← Current ( 100 lines)
   → Create checkpoint (status: in_progress)
   → Log: session_start

2. TDD Iteration #1
   → Write test file
   → Hook logs: file_created
   → Run tests (fail)
   → Hook logs: test_fail
   → Write implementation
   → Hook logs: file_created
   → Run tests (pass)
   → Hook logs: test_pass
   → Commit
   → Hook logs: commit

3. Session interrupted (crash/exit)
   → Checkpoint remains: iteration=1, status=in_progress
   → Changelog has full history

4. /auto-loop "something"
   → Check: Found in_progress session!
   → Block: "Use --resume or --force"

5. /auto-loop --resume
   → Read checkpoint: iteration=1
   → Read changelog: understand context
   → Continue from iteration #2

---

Installation

Hooks are installed with Director Mode Lite:

# After install, verify:
ls .claude/hooks/
# → auto-loop-stop.sh
# → _lib-changelog.sh
# → log-bash-event.sh
# → log-file-change.sh
# → pre-tool-validator.sh

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

---

Troubleshooting

Events not logged

1. Check hooks exist: ls .claude/hooks/*.sh
2. Check hooks.json: cat hooks/hooks.json
3. Check scripts are executable: chmod +x .claude/hooks/*.sh

Stale session blocking

# Check what's there
cat .auto-loop/checkpoint.json | jq '.status'

# Force restart
/auto-loop --force "New task"

Changelog too large

# Manual archive
/changelog --archive

# Or clear
/changelog --clear

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: claude-world
• Source: claude-world/director-mode-lite
• License: MIT
• Homepage: https://claude-world.com

Install and usage instructions live in the source repository linked above.