claude-code-journal

claude-code-journal

A Claude Code plugin that records every assistant turn as one greppable line of markdown, so you can recall what you did yesterday without trawling chat history.

What you get

After every assistant turn, a Stop hook appends one line to a daily file in your project:

- 14:23 | USER 'fix the broken header on the lean-to page' | DID Bash(fetch header), Edit(rewrite copy), Bash(push to test)
- 14:31 | USER 'looks good, push to prod' | DID Bash(re-push with --production)
- 14:55 | USER 'check sales for last 30 days' | DID Bash(query orders), Bash(format table)

Plain markdown. No JSON to parse. No per-session directories. No cloud dependency. cat, grep, tail -f - all the old tools work.

Why

When you're working on a long-running project with Claude Code, conversations span days or weeks across many sessions. The chat history is volatile and hard to grep. Without an artifact you can search later, you and Claude both end up jumping the gun on the same diagnoses repeatedly.

This plugin gives you a permanent, attributable record of what was tried, in plain markdown that lives next to your code.

Install

From inside Claude Code (easiest)

Run these two slash commands in any Claude Code session:

/plugin marketplace add Clinteastman/claude-code-journal
/plugin install claude-code-journal@claude-code-journal

From your terminal

claude plugin marketplace add Clinteastman/claude-code-journal
claude plugin install claude-code-journal@claude-code-journal

Either way: install runs once per machine + per user. After that, the hook fires automatically in every Claude Code session you start, in every project, until you uninstall.

To update later: claude plugin update claude-code-journal (or via /plugin update).

Use it

Just work normally. The hook captures every turn. To read entries back:

/journal              # today's entries
/journal yesterday    # yesterday
/journal 2026-04-27   # specific date
/journal user matt    # someone else's journal (per-user mode only)

Or just open the file directly: journal/2026-04-27.md (or journal/<your-gh-username>/2026-04-27.md in per-user mode).

How it works across machines and team members

The plugin writes the journal into the project directory. Combined with normal git workflow, that gives you some genuinely useful properties for free:

Solo + multi-machine

You work on the same project from a desktop AND a laptop. Same git repo on both.

1. Desktop session: hook writes a few lines to journal/2026-04-27.md
2. You commit + push (alongside whatever code work prompted those entries)
3. Switch to laptop, git pull
4. Laptop session: hook reads the same file, appends new lines
5. Commit + push from laptop
6. Back at desktop, git pull brings the laptop's additions down

Result: one continuous timeline per day, attributed to you, persisted in git, surviving any machine wipe. No third-party sync, no extra credentials, no setup beyond what you already do for the code.

Team + per-user mode

Multiple devs working in the same repo. Add .claude/journal.json with {"per_user": true} and each teammate's entries land in their own subdirectory keyed by GitHub username:

journal/
├── alice/
│   └── 2026-04-27.md
├── bob/
│   └── 2026-04-27.md
└── chris/
    └── 2026-04-27.md

Identity is resolved via gh api user --jq .login, so the same person on different machines converges in the same folder. No collisions between teammates' files = no merge conflicts. You can cat journal/bob/2026-04-27.md to see what Bob was doing today, without having to ask him.

git log journal/ and git blame work as expected on these files - so you literally get an attributed, time-stamped, version-controlled log of every action across the team.

Configuration

Optional .claude/journal.json in your project root tunes per-project behaviour:

{
  "per_user": true
}

Key	Default	Effect
per_user	false	When true, writes to journal/<gh-username>/<date>.md instead of journal/<date>.md. Use this in shared work repos.
llm	false	EXPERIMENTAL: spawns a background claude -p subprocess for an LLM-summarised second line per turn. Uses your Claude Code subscription (no API key). Currently flaky - leaves orphan subprocesses on Windows. Don't enable unless you want to debug it.

If neither file nor key is set: single-user mode, no LLM enrichment, journal at journal/<date>.md.

Output format

Each line is one of:

- HH:MM | USER '<first 100 chars of prompt>' | DID Tool(desc), Tool(desc) +N more
- HH:MM | USER '<prompt>' | SAID '<first 100 chars of assistant final reply>'   (when no tools used)
- HH:MM * <LLM-summarised one-liner>                                              (only if llm:true)