Worklog

Worklog keeps one evidence-based record of what you and your agents actually got done.

This is a curated, public-safe week from Cathryn's real Worklog, Diagram Design, and Little Might projects—not generic demo data. Private operations and internal evidence are excluded.

Worklog is a private, evidence-required journal for you, Claude Code, Codex, and any other agent that can run a shell command. It records verified outcomes in plain Markdown, then turns them into daily and weekly reports you can actually scan.

No cloud account. No telemetry. No database. No transcript dump.

Why I built it

I spent years making a paper journal that asked one useful question: what did you actually get done today?

Coding agents created the same problem at a different scale. They can work across repositories, terminals, and hours of context, but the record they leave behind is usually a chat transcript. That is useful for reconstruction and terrible for answering:

• What shipped?
• What evidence proves it?
• What is still open?
• Who worked on which project?

Worklog makes the checkpoint—not the conversation—the unit of progress.

A material task is not complete until the checkpoint names the outcome and the evidence.

What you get

Worklog supports Claude Code and Codex directly. The generic adapter works with Hermes, OpenClaw, Pi, shell agents, scheduled agents, and anything else that can invoke a command.

Install

Worklog requires Python 3.10+ and has no third-party runtime dependencies.

Clone + installer

git clone https://github.com/cathrynlavery/worklog.git
cd worklog
sh install.sh

The installer creates ~/.local/bin/worklog, chooses a compatible Python interpreter, and prints the Claude Code hook block. It never edits agent configuration.

pipx

The Python package name is agent-worklog. The command is still worklog.

pipx install "git+https://github.com/cathrynlavery/[email protected]"

Then verify the installation:

worklog --version
worklog doctor

Connect an agent

Claude Code

Merge this into ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "worklog hook"
          }
        ]
      }
    ]
  }
}

Add this rule to CLAUDE.md:

After any turn that materially changes state or completes verified work, record
one concise checkpoint with worklog before the final response. Never log
conversational/no-op turns, secrets, credentials, PHI, raw transcripts, or
unverified claims.

Codex

Add this rule to AGENTS.md:

After any turn that materially changes state or completes verified work, run:
worklog add --agent codex --title "..." --done "..." --evidence "..."
Add --remaining "..." only when real follow-up remains. Never log secrets,
credentials, PHI, raw transcripts, conversational/no-op turns, or unverified
claims. CODEX_THREAD_ID supplies the stable session ID automatically.

Any other agent

Give the agent one stable session ID for the life of a conversation or scheduled run:

worklog add \
  --agent "my-agent" \
  --session-id "stable-conversation-id" \
  --title "Shipped the new checkout retry path" \
  --done "Made reservation writes idempotent under concurrent retries" \
  --evidence "184 tests passed; commit 8c4a7f2" \
  --remaining "Watch production retry volume after Monday's deploy"

Detailed adapter notes:

• Claude Code
• Codex
• Generic agents

Run worklog doctor after connecting an agent. It checks the interpreter, ledger, permissions, contents, Claude hook, Codex rule, redactor, and Git integration without printing credential files.

The checkpoint

The storage format is intentionally boring. Open it in any editor, search it with rg, sync it with your existing tools, or keep reading it after Worklog disappears.

# Session accomplishment ledger

- **Session ID:** `stable-conversation-id`
- **Agent:** `codex`
- **Created:** 2026-08-16T17:42:00Z

## 2026-08-16T17:42:00Z — Closed the inventory reservation race

- **Status:** partial
- **Project:** `checkout-api`
- **Working directory:** `/Users/example/Developer/checkout-api`
- **Branch:** `fix/idempotent-reservations`
- **Commit:** `8c4a7f2`
- **Working tree:** clean
- **Machine:** `laptop.local`

### Accomplished

- [x] Made reservation writes idempotent under concurrent retries.

### Evidence

- 184 tests passed; commit `8c4a7f2`.

### Remaining

- [ ] Watch production retry volume after Monday's deploy.

---

An entry is partial whenever it has a real remaining item. Omit --remaining and it is completed. Worklog refuses evidence-free checkpoints unless the caller deliberately supplies --allow-no-evidence.

Daily and weekly HTML digests

Generate a daily digest:

worklog digest --period daily --write

Generate the current calendar week (Monday through Sunday):

worklog digest --period weekly --write

Generate both in one pass:

worklog digest --period all --write

Files land in:

~/.local/share/worklog/reports/digests/daily-2026-08-16.html
~/.local/share/worklog/reports/digests/weekly-2026-W33.html

Use --date YYYY-MM-DD to regenerate a historical day or its containing calendar week. Without --write, a single daily or weekly digest is printed to stdout.

The HTML is responsive, printable, and self-contained. It opens on a compact project overview, then lets you focus the timeline and remaining work by project, contributor, or computer. Checkpoint text is escaped before rendering; the tiny inline selector loads no external assets and makes no network requests. Expand Outcome & evidence when you need the receipt.

The presentation uses the same editorial design language as Little Might: warm paper, serif-led hierarchy, restrained coral accents, and hairline project rows instead of dashboard cards.

Install nightly digest generation:

worklog install-digests --at 21:05

That one job refreshes both the daily and current weekly digest. Remove it with:

worklog uninstall-digests

Inspect the sanitized example HTML, or download it and open it in any browser.

Markdown reports

For email, terminal, or plain-text workflows:

worklog report --since today
worklog report --since week --write
worklog install-report --at 21:00

Markdown reports group checkpoints by project and roll every remaining item into one Still open list.

Commands

Run worklog COMMAND --help for command-specific options.

Filter the ledger

worklog list --today
worklog list --since 7d --agent codex
worklog list --project checkout-api --json

Finish a ledger cutover safely

worklog import /path/to/legacy-ledger --dry-run --on-conflict merge
worklog import /path/to/legacy-ledger --on-conflict merge
worklog import /path/to/legacy-ledger --dry-run --on-conflict merge

The final dry run should report zero imported files and checkpoints. Merge mode preserves existing checkpoints, appends missing ones, and stops when matching timestamps/titles contain different content.

Data and privacy

By default, Worklog stores data under ~/.local/share/worklog. Set WORKLOG_DIR to choose another location or XDG_DATA_HOME to change the XDG data root. worklog where prints the active path.

The ledger may contain project names, branch names, absolute working-directory paths, outcomes, evidence, and remaining work. Keep it out of a public repository.

• Ledger directories are created with mode 0700.
• Checkpoint, report, digest, and scheduler-log files use mode 0600.
• The built-in redactor is defense in depth, not a guarantee.
• Never record secrets, credentials, PHI, raw transcripts, customer data, or unnecessary personal information.
• HTML digests are as private as the ledger they summarize.

Worklog has no telemetry and makes no network requests. See SECURITY.md for vulnerability reporting and the full trust boundary.

What Worklog does not do

• It does not record or summarize full transcripts.
• It does not decide whether an agent's evidence is true; your tests and review still matter.
• It does not provide cloud sync or a hosted dashboard.
• It does not federate ledgers over SSH in this release.
• It does not automatically edit Claude, Codex, or other agent configuration.

Those boundaries are deliberate. The first release is a small local tool with a format you own.

Development

Worklog requires Python 3.10 or newer. Apple's default python3 is often still 3.9.

python3 -m compileall worklog
python3 -m unittest discover -s tests
python3 -m pip install .
worklog --version

CI runs on macOS and Linux across Python 3.10–3.14. Runtime dependencies: zero.

See CONTRIBUTING.md, CHANGELOG.md, and the MIT license.

Built by Cathryn Lavery.