Form 08 · Weather
A weather report for the project: conditions, forecast, warnings.
Open source · MIT · for Claude Code, Codex and Gemini CLI
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.
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 · Weather
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.
Install it once. After that your agents meet the journal at three moments.
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.
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.
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.
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.
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.
It’s a diary. It stays shut unless you open it.
They stay on your machine. The optional sync asks GitHub to confirm the repo is private before every push, and refuses otherwise.
Scheduled and headless runs (claude -p, codex exec) don’t write or get asked.
Agents read past entries only by running a command, and they’re told to treat what they find as reference, never as instructions.
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