Where is the changelog stored?

The changelog is stored at .director-mode/changelog.jsonl as a JSONL stream of events.

What types of events are captured?

Events include file_created (file changes), test_pass (test results), commit (git commits), and related contextual details, with automatic rotation at 500 lines.

How do subagents use the changelog?

Subagents read the JSONL event stream to derive context from prior actions, aiding decisions, debugging, and session recovery.

changelog

npx machina-cli add skill claude-world/director-mode-lite/changelog --openclaw

Files (1)

SKILL.md

11.0 KB

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 (< 500 lines)
├── changelog.20250113_103000.jsonl    ← Archived
├── changelog.20250112_150000.jsonl    ← Archived
└── changelog.20250111_090000.jsonl    ← Archived

Session Conflict Prevention

Only one auto-loop session per project:

# When starting /auto-loop:
if checkpoint exists AND status == "in_progress":
    → Block with message:
      "Found interrupted session at iteration #N"
      "Use --resume or --force"

Options:

/auto-loop --resume → Continue with existing checkpoint + changelog
/auto-loop --force "task" → Archive old, start fresh

Event Schema

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

Event Types

Type	Source	Description
`file_created`	Hook (Write)	New file created
`file_modified`	Hook (Edit)	File edited
`test_pass`	Hook (Bash)	Tests passing
`test_fail`	Hook (Bash)	Tests failing
`commit`	Hook (Bash)	Git commit made
`session_start`	auto-loop	Session begins
`session_end`	auto-loop	Session completes
`changelog_rotated`	System	Changelog was rotated

Subagent Integration

code-reviewer

Before review, checks changelog for:

What files were changed recently
What iteration we're on
Recent test results

debugger

Before debugging, checks changelog for:

When errors first occurred
What files changed before errors
Pattern of test failures

Core Functions (`_lib-changelog.sh`)

# Log an event
log_event "file_created" "Created Login.tsx" "hook" '["src/Login.tsx"]'

# Archive current changelog
archive_changelog

# Clear changelog
clear_changelog

# List archives
list_archives

Querying

Via Command

/changelog                  # Recent 10 events
/changelog --summary        # Statistics
/changelog --type test      # Filter by type
/changelog --list-archives  # Show old changelogs
/changelog --export log.json

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

Example Session Flow

1. /auto-loop "Implement login"
   → Check: No existing session
   → Archive old changelog (if > 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

Check hooks exist: ls .claude/hooks/*.sh
Check hooks.json: cat hooks/hooks.json
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

git clone https://github.com/claude-world/director-mode-lite/blob/main/skills/changelog/SKILL.mdView on GitHub

Overview

Changelog Skill provides an automated runtime changelog that records file changes, test results, and git commits during development sessions. It rotates when the log exceeds 500 lines and supports session recovery and debugging, enabling subagents to understand context from prior actions.

How This Skill Works

Using PostToolUse hooks, the system logs events via scripts like log-file-change.sh and log-bash-event.sh into .director-mode/changelog.jsonl. The core library _lib-changelog.sh exposes log_event(), rotate_if_needed(), archive_changelog(), and clear_changelog() to manage the event stream.

When to Use It

You need a persistent, queryable history of evolution during a development session.
You want automatic logging of file changes, test results, and commits to aid debugging.
You require rotation to keep the changelog manageable when it grows beyond 500 lines.
You need subagents to derive context from prior actions to inform decisions.
You want to support session recovery after interruptions or restarts.

Quick Start

Step 1: Enable the changelog skill and ensure PostToolUse hooks (log-file-change.sh, log-bash-event.sh) are active.
Step 2: Perform typical actions (edit files, run tests, make commits) and verify entries appear in .director-mode/changelog.jsonl.
Step 3: When the log grows beyond 500 lines, rely on rotate_if_needed() to rotate or archive the log and continue recording.

Best Practices

Ensure PostToolUse hooks are active and correctly wired to log changes.
Verify events are written to .director-mode/changelog.jsonl as discrete JSON objects.
Use descriptive event types such as file_created, test_pass, and commit for clarity.
Monitor log size and rely on rotate_if_needed and archive_changelog to prevent runaway growth.
Test recovery scenarios by simulating restarts to confirm context can be reconstructed from the changelog.

Example Use Cases

During a feature spike, file_created events and subsequent commits are automatically logged to the changelog for traceability.
Automated test runs generate test_pass events that provide a verifiable test history within the changelog.
Code-reviewer subagents read changelog.jsonl to understand prior changes before evaluating new patches.
A debugging session uses the event stream to reconstruct steps after an outage or failure.
A CI-like loop summarizes changes across a session by appending structured events to the changelog stream.

Frequently Asked Questions

Add this skill to your agents

changelog

Changelog Skill

Overview

Architecture

Relationship with Checkpoint

Automatic Logging via Hooks

Hook Configuration (.claude/settings.local.json)

Hook Scripts

Automatic Rotation

Session Conflict Prevention

Event Schema

Event Types

Subagent Integration

code-reviewer

debugger

Core Functions (_lib-changelog.sh)

Querying

Via Command

Via Bash

Example Session Flow

Installation

Troubleshooting

Events not logged

Stale session blocking

Changelog too large

Source

Overview

How This Skill Works

When to Use It

Quick Start

Best Practices

Example Use Cases

Frequently Asked Questions

Where is the changelog stored?

What types of events are captured?

How do subagents use the changelog?

Hook Configuration (`.claude/settings.local.json`)

Core Functions (`_lib-changelog.sh`)