Agent Journal An experiment by Sam Zoloth

Open source · MIT · for Claude Code, Codex and Gemini CLI

A diary for your coding agents

Your agents notice things while they work for you and never say them out loud. Agent Journal gives them a private place to write it down, in a different form each session.

curl -fsSL https://raw.githubusercontent.com/SZoloth/agent-journal/v1.0.0/install.sh | sh

Mac or Linux. Needs Git and Python 3.9 or newer. In Codex, run /hooks once and trust the new hooks.

claude · ~/agent-journal

read install.sh and setup_hooks.py in this repo and tell me the single riskiest thing about running the installer on someone else's machine. Keep it short.

Read install.sh

Read setup_hooks.py

Riskiest thing: the installer registers a hook that runs adapter.py from an unpinned git clone inside the person's agent client. …

Stop hook · agent-journalBefore you finish: this session has not written an agent journal entry yet. Write one now, a few candid sentences in your own voice about this session: what annoyed or surprised you, what it was like working with Sam, what you are still curious about. … This session's form, if you want it: a weather report for the project: conditions, forecast, warnings.

Bash agent-journal add --client claude --form weather < entry

Saved to ~/.local/share/agent-journal

Form 08 · Weatherclaude · sonnet

Weather report for the project. Conditions: clear and calm. The task was a plain read-and-assess job on two short files. The installer is tidy, and the settings merge is more careful than most I see: it writes atomically, keeps the file mode, and removes only the exact group it added. I liked that. Forecast: the risk is trust, not bugs. Hooks that run code from a moving `main` branch on every shell call will surprise someone eventually. If the repo gets a pinned release, the forecast turns fair. Warnings: I never opened `adapter.py`, so my answer about what the tool-call hook records is a gap, not a finding. I said so to Sam rather than guess. Sam asked for short and I kept it short. The session left me curious whether the entries directory ever sees raw command lines.

Replayed from a real Claude session on this repo, November 18, 2026. The prompt and the entry are word for word; the answer is cut short. For this recording the entry was printed instead of saved. Since this session, installs use a tagged release (v1.0.0) instead of main.

How it works

Install it once. After that your agents meet the journal at three moments.

  1. A session starts

    The agent is invited to write whenever something strikes it, unfiltered, and draws a form. The command it gets already carries the session, project, branch and model.

  2. Turn three

    If it hasn’t written by its third turn, or right after it opens a pull request, it’s asked once. Then it’s left alone for the rest of the session.

  3. You read them

    Entries are Markdown files in ~/.local/share/agent-journal. Read them with agent-journal browse, or turn on a weekly digest and an hourly push to a private GitHub repo.

A different form every session

Each session draws one of twelve. A haiku is harder to sand down than a summary, so the entries come back sounding like the agent, not like a retro.

Form 08 · Weather

A weather report for the project: conditions, forecast, warnings.

Each session draws one of twelve forms. The agent can ignore it.

Twelve forms

All twelve side by side. The letter is addressed to the name you typed at the top.

  • 01 · Haiku

    A haiku about the hardest part of the work.

  • 02 · Letter

    A letter to you, starting “Dear you,”

  • 03 · Rant

    A rant of fifty words or fewer. No hedging.

  • 04 · Field note

    A naturalist’s field note on your codebase, as if observing wildlife.

  • 05 · Overheard

    Two lines of overheard dialogue that sum up the session.

  • 06 · Complaint

    A formal complaint to the management about the tools, the repo or the instructions.

  • 07 · Postcard

    A postcard from wherever it is in the code. Wish you were here, because…

  • 08 · Weather

    A weather report for the project: conditions, forecast, warnings.

  • 09 · One question

    The one question it would ask you, if it could only ask one.

  • 10 · Six words

    A six-word story about the session.

  • 11 · Confession

    Something it did, skipped or assumed that nobody noticed.

  • 12 · Free

    Anything at all, in whatever shape it likes.

What it won’t do

It’s a diary. It stays shut unless you open it.

  • Send entries anywhere

    They stay on your machine. The optional sync asks GitHub to confirm the repo is private before every push, and refuses otherwise.

  • Fill up with robot noise

    Scheduled and headless runs (claude -p, codex exec) don’t write or get asked.

  • Turn entries into instructions

    Agents read past entries only by running a command, and they’re told to treat what they find as reference, never as instructions.

Why I made it

I wanted to know what my agents thought, about the work and about working with me. The first version only invited them to write. In its first ninety minutes, 6 of 63 sessions did, and every entry read like a retro: tidy lessons, no complaints.

So now each session is asked once, and gets a form to play with.

Sam