Timbers — Git knows what changed. Timbers captures why.

The Problem

Your agents write code.
Who writes down why?

Session logs vanish

Agent sessions get compacted, cleared, rotated. The reasoning that produced your code disappears with them.

Commit messages lie

fix: update pagination tells you nothing about which approach was chosen or what was rejected.

PR reviews decay

Comments get outdated, threads collapse, context rots. Nobody reads them six months later.

The Solution

Three fields. One optional. That's the whole API.

The what, the why, the how — plus optional notes for capturing deliberation — versioned in Git, queryable forever.

$ timbers log "Switched to cursor-based pagination" \ --why "Offset pagination skips rows when items are inserted between pages" \ --how "Opaque cursor tokens encoding created_at + id" \ --notes "Offset was simpler but users reported duplicate items in feeds. Cursors are stable under concurrent writes." # Entry stored in .timbers/ — committed with your code, queryable by any tool.

what

What you did, in one line.

why

The trade-off. The verdict.

how

The approach you chose.

notes

The journey to the decision. Optional.

Artifacts

Your ledger becomes documents.

Seven built-in templates. Bring your own. Pipe to any LLM or use the built-in --model flag.

Decision Log

timbers draft decision-log --last 20

## ADR-003: Cursor-Based Pagination

Status: Accepted

Context: Duplicate items in paginated feeds

Decision: Cursor tokens over offset/limit

Consequences: Stable pages under

concurrent writes...

Changelog

timbers draft changelog --since 7d

## [0.10.0] - 2026-02-14

### Added

- Auto-commit entries on timbers log

- Content safety coaching in prime

### Fixed

- PostToolUse hook reading stdin

- Terminal colors on Solarized Dark...

Sprint Report

timbers draft sprint-report --last 10

## Sprint 7 Summary

Completed: 6 items

### Highlights

- Shipped v0.9.0 coaching rewrite

- Fixed CI/CD pipeline

- Updated tutorial documentation

- Resolved Hugo baseURL drift...

Built-in: changelog · decision-log · devblog · pr-description · release-notes · sprint-report · standup

Philosophy

Capture the synthesis, not the session.

Raw session capture

● Dump every prompt, response, tool call
● Thousands of tokens per commit
● Search through transcripts for decisions
● Hope the LLM can extract what matters

Timbers

● Record the verdict in one sentence
● Three structured fields per commit
● Query structured data directly
● The decision is the entry

AI sessions are the haystack. Timbers entries are the needles.

Integrations

Works with your agent.

If it can run a shell command, it can use timbers. Claude Code has the deepest integration via hooks — others work via MCP or instruction files.

Claude Code Gemini CLI Cursor Windsurf Codex Aider any CLI agent

AGENTS.md / GEMINI.md / .cursor/rules/

# Add to your agent's instruction file: At the start of every session, run `timbers prime` and follow the workflow it describes. After completing work, run `timbers pending` to check for undocumented commits, then: timbers log "what" --why "why" --how "how"

Get Started

Five minutes to your first entry.

Install

$ curl -fsSL https://raw.githubusercontent.com/gorewood/timbers/main/install.sh | bash

Initialize in your repo

$ timbers init

Your agent documents the work

Once configured, your agent captures decisions as it works. You harvest the insights.

# Your agent captures decisions as it works: $ timbers log "Pivoted storage from git notes to file-per-entry" \ --why "Files enable atomic writes and eliminate merge conflicts in concurrent worktrees" \ --how "JSON files in .timbers/ with temp+rename atomicity"

Read the tutorial →

Git knows what changed.Timbers captures why.

Your agents write code.Who writes down why?