Project Files

Written & tested for accuracy by a developer (not AI) · Updated November 2026

What Is a Work Ledger?

A work ledger is a folder of handoff notes for AI coding agents. What goes in a note, how it differs from a changelog, and how it keeps work going between sessions.

A work ledger is a folder of short handoff notes that lets a new session with an AI agent pick up where the last one stopped. The folder is named work-ledger. It holds one dated note for each work session, saying what was done, why, and what comes next.

We need a work ledger because an AI agent remembers almost nothing from one session to the next. Even within one session, an agent's working memory, or context, has a limit. On a long task the context fills up. Claude and Codex then compact the conversation, replacing it with a summary to make room. Details get lost. If you start a new session, the context holds only your prompt and the project's instruction file. Without a work ledger, decisions you made, approaches you tried and dropped, and necessary next steps are lost in an earlier conversation the agent can no longer see.

Experienced users ask the agent to write a handoff note before the context runs out, or before they stop work for the day. The note is kept as a file. A fresh session reads the latest note and carries on, the way a nurse beginning a shift reads the notes left from a previous shift. A different AI agent can read it too, so you can switch among models, or between Claude and Codex, or pause the project and come back to it weeks later.

The work ledger is one of the documents in a project folder that guide an AI agent. Other documents in numbered project folders hold the lasting plans, decisions, and specifications. The work ledger is used specifically to record the work in progress, one session at a time. The project's AGENTS.md file tells the agent to read the work ledger and the numbered project folders (Agent Instructions explains that file).

What's in a Project Folder? explains the other files and folders you'll find beside a work ledger in a project. Keeping a work ledger is part of working with AI agents on a Mac set up for coding. See the full Mac setup roadmap.

What goes in a note

A note tells an agent or person what you did, why you did it that way, and what comes next. The "why" matters most, because it records the decisions and the paths you tried and dropped, which the files themselves may not show. Here's a short work ledger note, written the way the "Set Up Your Mac" starter project writes them:

# Greeting by name

**Summary:** Wrote SPEC-002 and built the greet-by-name feature from its playbook.

## What was done

- Wrote SPEC-002 (greet by name) and its playbook, PB-003.
- Built the feature in source/hello.py. Every check in the spec passes.

## Why

- Kept the name optional, so the program still runs with no input.
- Tried reading the name from a file, and dropped it as more than the spec asked for.

## Next

- Add a test for an empty name, then update the examples in the README.

Each note gets a dated file name, such as 2026-11-04-greeting-by-name.md, so the notes sort in order. The folder's index.md gets one line for each note, with a link to it, newest first. Longer notes add sections for the evidence behind a decision and for anything that blocked the work.

The work-ledger folder has no dot at the start of its name, so the Finder shows it without showing hidden files. The notes are plain Markdown files, which you can read in a Markdown editor.

When to write a note

Write a note at the end of a task, before you take a break in the middle of a task, or whenever you want the next session to know where things stand. Don't write one after every prompt. A good test is whether a fresh session, or a different AI agent, could continue the work from the notes alone.

Start a work ledger

I ask AI agents to write a short handoff note in a work ledger folder after every work session. It is the most effective way I know to give an AI agent memory for a project.

Here's how to set it up:

  1. Ask an AI agent to write a skill named preserve-our-work that updates the changelog and writes a work ledger note with a line in the index. The AI-Coding-Project starter project in the "Set Up Your Mac" apps already includes one. Developer Setup for Agent Skills explains what a skill is.
  2. Add a line to the project's AGENTS.md that says where the work ledger is, and tells the AI agent to read the index and the newest notes before it starts work. Anthropic Claude and ChatGPT Codex read a work ledger only when the instructions point them to it.
  3. When you take a break or finish a task, type /preserve-our-work in Claude (in Codex, $preserve-our-work), or just type "preserve our work".

The folder can sit in the project's top folder or inside 0-project-management, as long as the AGENTS.md file says where it is. Numbered Project Folders explains both layouts.

Work ledger, changelog, and Git

Task progress can be recorded four ways (or more). Each has a different job:

  • The Git commit message - the full story of the change, kept in the project's history.
  • The changelog - one to three sentences on what changed and in which files, for anyone who reads the project. What Is a Changelog? explains the file.
  • The work ledger's index - one line that points to the note.
  • The work ledger note - the decisions, the paths not taken, the evidence, and the next steps, for whoever continues the work.

A new session reads the short versions first, and opens a full note only when it needs one, to conserve context.

A work ledger is different from Claude's auto memory, the notes Claude keeps for itself in ~/.claude/projects in your home directory. Only Claude reads those, and only on your Mac. A work ledger lives in the project and goes into Git, so any AI agent, or any person, who opens the project can read it.

Where the idea comes from

The name comes from the Future of Software Development retreat, hosted by Martin Fowler and Thoughtworks in Deer Valley, Utah, in February 2026. The retreat's published findings describe a work ledger that records an AI agent's future, current, and past work, as the core building block of a future "operating system" for agents, an idea much larger than a folder of notes. I adopted the name and its central purpose in May 2026, scaling it down to something you can use in any project today.

Similar practices

Scientists keep a lab notebook, and many engineers an engineering notebook, a dated record of their work. A work ledger extends the idea to work with AI.

Anthropic's engineers describe how each session of a long task reads a progress file and the Git log before it starts work (Effective harnesses for long-running agents). OpenAI's execution plans for Codex suggest a running record of progress, surprises, and decisions in a plan, so a new session can restart from a plan alone. Thoughtworks' Technology Radar of April 2026 lists "a durable work ledger" as an emerging pattern for coding agent swarms, large groups of AI agents working on one codebase. Its example is Beads, Steve Yegge's task tracker for coding agents, which keeps its ledger in a database rather than in Markdown files.

Now you can set up a work ledger in any project, and start each new session with a record of what was done and what comes next. Try it at the end of your next session. Ask an AI agent to read the note when you start again.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.