Copied from the repo’s CHANGELOG.md, which is generated by just release using timbers draft changelog | claude -p --model opus.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.16.3 - 2026-03-28

Fixed

• Fixed doctor --fix targeting wrong settings scope when cleaning up stale Claude hooks — Detect() found stale hooks in global settings but Install(true) always wrote to project-local, so retired hooks in global settings survived --fix

Changed

• Released v0.16.2 changelog, regenerated site examples, and cleaned leaked LLM commentary from prior release notes

0.16.2 - 2026-03-28

Fixed

• Fixed hook deadlock during rebase, merge, cherry-pick, and revert where agents were blocked by pending-commit checks and couldn’t log or continue
• Fixed --range silently dropping entries when only some anchor commits were stale; v0.15.3 fallback only triggered on zero anchor matches, missing the partial-stale case

Technical

• Added git.IsInteractiveGitOp() that detects in-progress interactive git operations by checking .git state files; all hooks early-return during these operations
• Changed --range entry discovery to run both anchor-based and diff-based discovery unconditionally and union results by entry ID

0.16.0 - 2026-03-23

Fixed

• Fixed query --range returning empty results after squash merge, where entry anchor_commit SHAs from feature branches disappear from main history
• Added fallback discovery via git diff --name-only when commit-ancestry matching finds zero entries in a range

Technical

• Added DiffNameOnly to GitOps interface to support file-based entry discovery in getEntriesByRange

0.15.3 - 2026-03-22

Fixed

• Fixed query --range returning empty results after squash merge by falling back to file-based entry discovery when anchor commit SHAs are no longer in main’s history

0.14.4 - 2026-03-05

Fixed

• Respected core.hooksPath git config for hook installation instead of hardcoding .git/hooks/, fixing compatibility with tools like beads that set a custom hooks directory
• Updated GeneratePreCommitHook to accept a dynamic hooksDir parameter for correct --chain backup paths

0.14.3 - 2026-03-05

Fixed

• Fixed chained pre-commit hook silently overriding timbers exit code, allowing commits to succeed even when pending entries should have blocked them

0.14.2 - 2026-03-05

Fixed

• Expanded stop hook reason to include full timbers log syntax with --why/--how flags so agents receive an actionable command instead of a bare timbers log that would fail

0.14.0 - 2026-03-04

Changed

• Simplified hook enforcement by dropping PreToolUse handler in favor of pre-commit blocking, which works universally across all git clients
• Kept Stop hook as a session-end backstop for agents that bypass pre-commit
• Updated hooks install help text from “warns” to “blocks” to reflect actual behavior

Fixed

• Fixed uninstall leaving retired hooks (PostToolUse, PreToolUse) in settings by adding retiredEvents cleanup loop

Removed

• Removed PreToolUse handler, dispatch case, and associated tests from hook enforcement

0.13.2 - 2026-03-03

Fixed

• Fixed timbers log hard-erroring on stale anchor after squash merge, now warns and proceeds with fallback commits
• Fixed timbers log --batch treating ErrStaleAnchor as fatal, matching the graceful degradation already used by pending, prime, and MCP

0.13.1 - 2026-03-03

Added

• Added quick health check to timbers prime output that surfaces missing hooks and integration issues at session start
• runQuickHealthCheck validates post-commit hook and agent environment, displaying a Health section with doctor --fix hint when issues are found

0.13.0 - 2026-03-02

Added

• Added timbers hook run post-commit command that prints a one-line reminder to run timbers log after commits
• Added timbers init --hooks flag to install the post-commit git hook
• Added timbers doctor check for post-commit hook presence, with --fix to auto-install it

Fixed

• Fixed slice capacity mismatch (5→6) in post-commit hook setup
• Added missing IsRepo guard to prevent hook operations outside git repositories

Technical

• Added unit tests for hook Generate, Check, and Install functions
• Added integration tests for init --hooks post-commit workflow

0.12.2 - 2026-03-02

Fixed

• Fixed timbers pending treating all pre-timbers commit history as undocumented work in new installations
• Fixed timbers doctor reporting false warnings about pending commits when no ledger entries exist yet

Changed

• timbers pending and timbers doctor now detect first-use state (no entries) at the display layer and show a friendly onboarding message instead of listing every historical commit
• Added status field to timbers pending --json output to distinguish pending, clean, and no_entries states
• timbers init now suggests running timbers log --batch to document recent work as a catchup tip

0.12.1 - 2026-02-28

Added

• Added LLM output sanitization (SanitizeLLMOutput()) to strip thought-process leakage from --model output, plus “output discipline” prompting added to all 7 built-in templates
• Added notes field to site landing page marketing content
• Added static example generation for dense date ranges to avoid redundant LLM calls on every release

Changed

• Replaced auth examples with cursor-based pagination examples across README and landing page
• Split site example generation into dynamic (per-release) and static (fixed date range) justfile recipes
• Parallelized site example generation
• Replaced declare -A with parallel arrays in example recipes for macOS bash 3.2 compatibility
• Updated standup examples to use --since 1d
• Bumped go-sdk to v1.3.1 for CVE-2026-27896 (case-insensitive JSON parsing)

Fixed

• Removed leaked LLM commentary and duplicate sections from CHANGELOG.md and site examples

0.12.0 - 2026-02-28

Added

• Added --models flag to timbers draft to list supported LLM providers, model aliases, and required API keys
• Added --json support for timbers draft --models for agent consumption
• Added internal/llm package with provider metadata and alias resolution

Changed

• Updated README, tutorial, and docs/llm-commands.md with verified piping syntax for all three supported LLM CLIs (claude, gemini, codex)

Fixed

• Fixed Codex CLI flag placement in docs — -m belongs to codex exec, not the root codex command
• Fixed release dirty-tree check to exclude CHANGELOG.md and site/content/examples/ (outputs of the release process)
• Fixed release recipe to skip already-modified site examples, avoiding redundant LLM calls on partial reruns
• Fixed defensive alias copy in ProviderInfos() using maps.Copy to prevent callers from mutating package state

0.11.0 - 2026-02-27

Added

• Added govulncheck as a Go tool dependency with just vulncheck recipe for vulnerability scanning
• Added automatic landing page version update during just release
• Added generation capability check to timbers doctor with CLI/API key detection via llm.APIKeyEnvVars()
• Added just examples recipe to justfile

Changed

• Renamed exec-summary template to standup for better discoverability
• Rewrote pr-description template (v4) to focus on intent and decisions rather than diff review
• Updated prime workflow coaching to recommend pipe-first generation defaults for subscription users

Fixed

• Fixed devblog workflow generating empty “apology” posts when no entries exist by adding entry count check before LLM invocation
• Fixed terminal colors invisible on dark backgrounds (e.g., Solarized Dark) by replacing hardcoded lipgloss.Color with AdaptiveColor across all output formatting

0.10.2 - 2026-02-26

Fixed

• Fixed timbers prime treating stale anchor as fatal error after squash merges — now handles ErrStaleAnchor gracefully like pending and MCP already do
• Improved stale anchor warning messages in CLI and MCP to be actionable: explains that squash-merged branches with timbers entries are already documented, advises against catch-up logging, and notes that the anchor self-heals on next timbers log
• Synced MCP defaultWorkflowContent with CLI version — MCP had a stale 4-line checklist instead of the full coaching content

Added

• Added <stale-anchor> coaching section to prime workflow, guiding agents through the correct response when anchor commits are missing from history after squash merges

0.10.1 - 2026-02-16

Changed

• Regenerated site examples and devblog from 69-entry ledger, replacing stale content from v0.9.0
• Added provenance note to agent DX guide subtitle crediting pattern origins
• Updated landing page to v0.10.0 with terminal indentation fix

Fixed

• Removed PostToolUse hook that fired but whose stdout was not surfaced by Claude Code — Stop hook already covers the same case via timbers pending at session end

Technical

• Added retired event cleanup list for graceful hook removal on upgrade

0.10.0 - 2026-02-14

Added

• Added --color flag (never/auto/always) as a global persistent flag for terminal color control, fixing invisible text on Solarized Dark and other non-standard themes — all NewPrinter call sites plumbed through useColor(cmd)
• Added auto-commit in timbers log — entry files are now staged and committed atomically using git commit -m "timbers: document <id>" -- <path>, eliminating the gap where .timbers/*.json files were staged but never committed
• Added <content-safety> coaching section to prime workflow warning agents not to include PII, secrets, or sensitive data in ledger entries
• Added marketing landing page for Hugo site homepage with dark theme, terminal-styled code blocks, and GSAP ScrollTrigger animations

Fixed

• Fixed PostToolUse hook to read JSON from stdin instead of empty $TOOL_INPUT environment variable, which was always empty and made the post-commit reminder a no-op since creation
• Fixed landing page terminal block alignment, continuation indentation, and quick start container width

Technical

• Added legacy hook detection and upgrade logic via hasExactHookCommand and removeTimbersHooksFromEvent for replacing stale hooks automatically
• Added daily devblog automation at 9am UTC with workflow_dispatch chain to pages deploy

0.9.0 - 2026-02-13

Changed

• Rewrote agent coaching text with motivated rules — each instruction now explains why it exists, enabling models to generalize correctly instead of overtriggering on imperative language
• Replaced 11 instances of MUST/CRITICAL/MANDATORY with calm, motivated framing — when everything is critical, nothing is
• Replaced vague --notes guidance (“use when you made a real choice”) with concrete 5-point trigger criteria: 2+ approaches evaluated, obvious approach rejected, surprise encountered, future lock-in, non-obvious to teammates
• Structured coaching with XML section tags (<protocol>, <why-coaching>, <notes-coaching>, <commands>) for cleaner model parsing
• Deleted redundant “Core Rules (MANDATORY)” block that restated instructions already covered above
• Updated tutorial: added decision-log to template list, recommended install script over go install, updated model recommendations to recommend opus for quality content

Fixed

• Fixed Hugo site baseURL from rbergman.github.io to gorewood.github.io after org migration
• Fixed devblog CI workflow failing on stale git fetch refs/notes/timbers — timbers uses .timbers/ directory storage, not git notes
• Fixed devblog posts not triggering site rebuild — GITHUB_TOKEN pushes don’t fire on:push workflows, added explicit workflow_dispatch chain from devblog to pages workflow

Technical

• Switched devblog CI from weekly to daily schedule (9am UTC, --since 1d)
• Regenerated all site example artifacts from 55 real ledger entries with notes, replacing old 30-entry backfilled set

0.8.0 - 2026-02-13

Added

• Added --notes flag to timbers log for capturing deliberation context — the journey to a decision, distinct from --why which captures the verdict
• Added notes coaching to prime output with BAD/GOOD examples teaching “thinking out loud” style over mechanical summaries
• Added AgentEnv interface with registry pattern for agent-environment-neutral integrations, enabling single-file additions for new agent environments (Gemini, Cursor, Windsurf, Codex)
• Added ClaudeEnv as reference implementation of AgentEnv, wrapping existing Claude Code setup/teardown functions

Changed

• Refactored init, doctor, setup, and uninstall commands to iterate AllAgentEnvs() instead of hardcoding Claude-specific logic
• Replaced --no-claude flag with generic --no-agent (deprecated alias preserved for backward compatibility)
• Tightened --why coaching to explicitly differentiate from --notes: why is the verdict, notes is the journey
• Preserved backward-compatible JSON keys (claude_installed, claude_removed) while generalizing step names and flags

Fixed

• Fixed TestCommitFiles to use an isolated temp repo instead of live HEAD, which fails on merge commits where diff-tree returns empty
• Fixed TestRepoRoot to be worktree-compatible by replacing hardcoded directory name assertion with absolute path check

Technical

• Extracted defaultWorkflowContent to prime_workflow.go to stay under 350-line file-length lint limit
• Extracted outputPrimeRecentWork from outputPrimeHuman to stay under cognitive complexity limit of 15
• Added AgentEnvState slice pattern for uninstall to gather and remove all detected environments

0.7.0 - 2026-02-12

Added

• Added MCP server with 6 tools (pending, prime, query, show, status, log) over stdio transport via timbers serve subcommand, enabling integration with Claude Code, Cursor, Windsurf, Gemini CLI, and other MCP-compatible editors
• Added idempotentHint annotation to MCP read tools, allowing clients to optimize with caching and retry logic

Changed

• Updated timbers onboard snippet with command -v guard and install URL for graceful degradation when timbers is not installed
• Replaced all git notes references across documentation with .timbers/ file-based storage

Fixed

• Filtered ledger-only commits from GetPendingCommits to resolve chicken-and-egg problem where .timbers/ entry commits were always reported as undocumented

Technical

• Moved filter functions to internal/ledger/ for sharing between CLI and MCP server
• Added git.CommitFiles() using diff-tree and expanded GitOps interface with isLedgerOnlyCommit helper
• Added validateLogInput to catch empty strings that the MCP SDK’s required-field check does not

0.6.0 - 2026-02-11

Changed

• Pivoted storage from git notes to flat directory files (.timbers/<id>.json), enabling atomic writes and eliminating merge conflicts in concurrent worktrees
• Simplified GitOps interface from 8 methods to 4 (HEAD, Log, CommitsReachableFrom, GetDiffstat)
• Adopted YYYY/MM/DD directory layout for .timbers/ entries to scale beyond flat-directory limits at high commit volumes
• Replaced ReadDir with WalkDir for recursive entry discovery across date-bucketed directories
• Rewrote uninstall command to clean up .timbers/ directory with recursive cleanup

Removed

• Removed all git notes code and references (notes.go, notes_configured, remote_config fields, timbers notes push/fetch commands)

Technical

• Migrated 37 existing ledger entries from git notes to .timbers/ flat files
• Extracted atomicWrite helper using temp-file-plus-rename pattern for crash-safe writes
• Added 14 integration tests proving file-per-entry storage is inherently merge-safe across branches

0.5.0 - 2026-02-11

Added

• Multi-event Claude Code hooks covering the full session lifecycle: SessionStart, PreCompact, Stop, and PostToolUse
• Upgrade path that preserves existing hooks when adding new reinforcement points

Changed

• Expanded hook configuration from single SessionStart hook to four reinforcement points, addressing 0% compliance for undocumented commits with single-hook approach
• Generalized hook management via timbersHookConfig slice with addTimbersHooks/removeTimbersHooks functions

0.4.0 - 2026-02-10

Changed

• Rewrote Claude Code hook integration from shell scripts to JSON settings, fixing session-start context injection that previously had 0% adoption due to format mismatch
• Renamed internal/prompt package to internal/draft to match the draft command name
• Updated agent DX guide with v0.3+ learnings, JSON hook format documentation, and shell-script anti-pattern section

Fixed

• Added graceful degradation when timbers is not installed — Claude Code hook now warns with install URL instead of erroring, unblocking adoption for team members without timbers
• Added isTimbersPrimeCommand() for backward-compatible detection of both legacy shell-script and new JSON hook formats

Removed

• Removed legacy .claude/hooks/user_prompt_submit.sh shell script hook in favor of JSON settings
• Removed history/ artifacts from version control

0.3.0 - 2026-02-10

Added

• Added git.InitNotesRef() to create an empty notes namespace during init, so prime works immediately without requiring a manual first note
• Added tests for the prime guard silent-exit path and doctor --fix auto-install path
• Added TTY-aware lipgloss style sets to doctor and init output, following the existing uninstall pattern
• Added NotesRefExists guard to prime to prevent no-op runs in uninitialized repos

Changed

• Switched Claude hooks from global to project-level by default; global install is now behind the --global flag
• Changed git hooks from default-on (--no-hooks to skip) to opt-in (--hooks to enable), avoiding conflicts with tools like beads that rely on pre-commit
• Renamed warn style to skip in init output styles for consistency
• Renamed gpt-5 model alias to gpt
• Updated agent-dx-guide documentation to reflect opt-in hooks and project-level defaults

0.2.0 - 2026-02-10

Added

• Added --tag filtering to timbers query command with OR semantics, supporting both repeated flags and comma-separated values
• Added timbers changelog command that generates markdown changelogs from ledger entries, grouped by tag
• Added timbers draft command (renamed from prompt) for document generation, with decision-log template in ADR format
• Added .env.local support for API keys via new internal/envfile package, loaded as fallback in root PersistentPreRunE
• Added cross-platform config directory support via new internal/config package with Dir() function, respecting TIMBERS_CONFIG_HOME, XDG_CONFIG_HOME, and Windows AppData
• Added CONFIG section to doctor command with checks for config dir, env files, API keys, and templates
• Added version check to doctor that queries GitHub releases API with graceful failure for dev builds and network errors
• Added draft status hint and stderr routing for errors/warnings when stdout is piped via output.Printer WithStderr()
• Added goreleaser configuration, GitHub Actions release workflow, and install.sh with checksum verification
• Added robustness for non-timbers git notes with ErrNotTimbersNote, schema validation, and ListEntriesWithStats()
• Added Configuration section to README documenting env file resolution, API key setup, and custom templates
• Added Installation section to README with curl|bash and go install methods
• Added MIT LICENSE, CONTRIBUTING.md, and CI workflow for test and lint

Changed

• Renamed prompt command to draft and propagated rename across docs, justfile, and CI
• Surfaced draft command in prime output under a new Generating Documents section
• Rewrote README for open-source audience with badges and dogfood caveat
• Updated agent DX guide with v0.2 learnings
• Fixed org owner references from rbergman to gorewood in goreleaser and install script

Fixed

• Fixed global state issue in status.go by switching to closure pattern
• Fixed amend.go output inconsistency
• Fixed uninstall.go icon usage
• Fixed ListTemplates override bug
• Fixed piped output corruption caused by errors and warnings being written to stdout instead of stderr

0.1.0 - 2026-02-10

Initial public release.

Added

• Core CLI with log, pending, show, status, query, and export commands
• log command for recording work with structured what/why/how fields, --auto mode for extracting from commit messages, --batch mode for grouping by work-item trailers
• pending command showing undocumented commits since last ledger entry
• query command with --last, --since, --until, --tags, and --oneline filtering
• export command for JSON and Markdown output, with --tag filtering and directory output via --out
• draft command (document generation) rendering templates with ledger entries for LLM consumption or direct execution via --model
• Built-in templates: changelog, decision-log, devblog, exec-summary, pr-description, release-notes, sprint-report
• generate command as a composable LLM completion primitive with multi-provider support (Anthropic, OpenAI, Google, local)
• catchup command for auto-generating entries from undocumented commits using LLMs, with --batch-size, --parallel, and --dry-run support
• amend command for updating existing ledger entries (what/why/how/tags)
• prime command for agent session context injection with --verbose flag for recent entry details
• notes subcommands (init, push, fetch, status) for Git notes sync management
• init command for full setup including notes, hooks, and Claude integration
• onboard command for generating CLAUDE.md integration snippets
• doctor command for health checks and diagnostics
• uninstall command for clean removal from repos
• Multi-provider LLM client supporting Anthropic, OpenAI, Google, and local (LM Studio/Ollama) models
• --json flag on all commands for structured output
• --dry-run flag on all write operations
• Structured error JSON with recovery hints and consistent exit codes (0/1/2/3)
• Lipgloss terminal styling with TTY-aware rendering
• Pipe-safe output: errors and warnings routed to stderr when stdout is piped
• Goreleaser configuration for cross-platform binary releases (Linux, macOS, Windows)
• Install script (install.sh) with checksum verification
• GitHub Actions workflows for releases, dev blog generation, and CI (test + lint)
• Comprehensive documentation: tutorial, agent reference, LLM commands guide, publishing artifacts guide, agent DX guide, and spec