Skip to content

claude-world/director-mode-lite / skills/changelog

changelog

Verified

View and manage the runtime changelog for observability

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

TypeSourceDescription
file_writeHook (Write)File written via the Write tool
file_editHook (Edit)File edited via the Edit tool
test_passHook (Bash)Tests passing
test_failHook (Bash)Tests failing
test_runHook (Bash)Tests ran, result undetermined
commitHook (Bash)Git commit made
session_startauto-loopSession begins
session_endauto-loopSession completes
changelog_rotatedSystemChangelog 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).

ScriptTriggerEvents Logged
log-file-change.shWrite, Editfile_write, file_edit
log-bash-event.shBashtest_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:

TriggerThresholdWho does itWhen
Session-start archive> 100 lines/auto-loop initAt 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

AspectCheckpointChangelog
Location.auto-loop/checkpoint.json.director-mode/changelog.jsonl
PurposeCurrent state snapshot ("where am I now?")Historical event stream ("how did I get here?")
Used byStop hook (continue/stop decision)Subagents (context)
FormatSingle JSON objectJSONL (append-only)
PersistenceOverwritten each iterationAccumulated, 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

  1. Check hooks exist: ls .claude/hooks/*.sh
  2. Check the live hook config: cat .claude/settings.local.json | jq '.hooks' (the shipped template is hooks/settings-hooks.json)
  3. 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
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall