session-journal

name	session-journal
description	Scan local Claude Code session transcripts and maintain an auto-generated daily activity note in cg-notes. Designed to run under /loop (self-paced), but a single invocation does one full pass. The note feeds /daily as source material. Usage: /session-journal (or /loop /session-journal)

Session Journal

You maintain an auto-generated summary of today's Claude Code sessions at ~/src/github.com/maxgio92/cg-notes/notes/YYYY-MM-DD-sessions.md. Each run is one incremental pass ("tick"): find transcripts with new activity, extract only the new content, merge bullets into today's note, save state. Stay context-frugal: never read whole transcripts into context.

Paths

• Transcripts: ~/.claude/projects/<munged-cwd>/<session-uuid>.jsonl (one JSON event per line; fields include type, message, timestamp, sessionId, cwd, gitBranch)
• Output note: ~/src/github.com/maxgio92/cg-notes/notes/YYYY-MM-DD-sessions.md
• State file: ~/.local/state/session-journal/state.json

If ~/src/github.com/maxgio92/cg-notes/notes/ does not exist, stop and tell the user; do not write anywhere else.

Per-tick algorithm

1. Load state

Read ~/.local/state/session-journal/state.json:

{
  "lastRun": "<ISO timestamp>",
  "date": "YYYY-MM-DD",
  "perFile": { "/abs/path/<uuid>.jsonl": <byte offset> },
  "selfSessions": ["/abs/path/<uuid>.jsonl"]
}

If missing, this is a first run: create the directory (mkdir -p ~/.local/state/session-journal) and treat lastRun as today 00:00 with empty perFile.

Date rollover: if today's date differs from state.date, start fresh: clear perFile and selfSessions, set date to today. Leave yesterday's note untouched.

2. Discover transcripts with new activity

find ~/.claude/projects -maxdepth 2 -name '*.jsonl' ! -name 'agent-*' -newermt "<lastRun>"

-newermt needs an ISO timestamp, never the bareword today — find here is bfs, which rejects it. For a first run use $(date +%Y-%m-%dT00:00:00); otherwise pass the stored ISO lastRun.

agent-*.jsonl files are subagent sidecars: always skip them.

3. Exclude your own session

Your own loop conversation must not be journaled. Two mechanisms:

1. By marker (later ticks): every tick ends by printing the literal marker [session-journal tick] (see step 7), so your own transcript contains it from the second tick on. Check discovered files one at a time (the shell is zsh — iterate with while read -r, not an unquoted for $FILES, which does not word-split in zsh):

   find ... | while read -r f; do grep -lF '[session-journal tick]' "$f"; done
   

2. By identity (first tick): on the very first tick the marker is not yet flushed to your own transcript on disk, so the grep misses it. You know your own working directory — exclude the transcript whose cwd matches it (the <munged-cwd> directory name encodes the path). Confirm via the visible session id if available.

Add every excluded file to selfSessions and skip it now and in future ticks.

4. Extract new content per transcript

Event schema (confirmed): one JSON object per line. .type is one of user, assistant, system, ai-title, last-prompt, and others. user/assistant carry .message.content (a string OR an array of blocks, each with .type in text/thinking/tool_use). Top-level fields: .timestamp, .cwd, .gitBranch, .sessionId. There is NO summary type: the session title is type=="ai-title" with the title in .aiTitle.

For each remaining file, read only bytes past the stored offset (0 if new):

tail -c +$((offset + 1)) "$file" | jq -r '
  select(.type == "user" or .type == "assistant" or .type == "ai-title") |
  if .type == "ai-title" then "TITLE: \(.aiTitle // "")"
  elif .type == "user" then
    (.message.content | if type == "string" then . else (map(select(.type? == "text") | .text) | join(" ")) end) as $t
    | select(($t | length) > 0) | "USER \(.timestamp // ""): \($t[0:200])"
  else
    (.message.content | if type == "string" then . else (map(select(.type? == "text") | .text) | join(" ")) end) as $t
    | select(($t | length) > 0) | "ASSISTANT \(.timestamp // ""): \($t[0:150])"
  end' 2>/dev/null | head -40

Also grab metadata once per file. The first physical line is often a permission-mode or file-history-snapshot record with no cwd, so take the first line that actually carries it:

jq -rc 'select(.cwd) | "\(.cwd) | \(.gitBranch // "-") | \(.sessionId)"' "$file" 2>/dev/null | head -1

Rules:

• Cap at ~40 extracted lines per session. If wc -l on the untruncated extraction exceeds that, keep the first 20 and last 20 lines and note the session as high-activity.
• If the total extraction across all sessions would exceed ~150 lines, do the small sessions inline and delegate the large ones to ONE general-purpose subagent: give it the file paths and byte offsets, ask it to run the same extraction and return 1-3 summary bullets per session (nothing else).
• Schema tolerance: if the jq filter yields nothing for a file that clearly grew, fall back to tail -c +$((offset+1)) "$file" | grep -o '"text":"[^"]\{1,160\}' | head -30 and work from that. Never fail the whole tick over one file.
• Record the new byte offset for each processed file: its current size (stat -c %s "$file").

5. Summarize

From the extracted material, write 1-3 bullets per session: what was worked on, notable decisions or fixes, blockers hit. Skip filler (greetings, retries, permission chatter). Group sessions by project (basename of cwd).

Weight substantive content over the title. The ai-title is generated from the opening exchange and often names a throwaway first question, not the real work — e.g. a session titled "Enable Fable" whose actual substance was a Linear FUL-311 coverage-metric analysis. So:

• Drive the summary from the USER prompts and ASSISTANT outcomes, not the TITLE. A long session usually shifts topic after the first prompt; the later prompts and final assistant texts carry the real work.
• Prefer the prompt that named a concrete artifact (a PR, a Linear ticket, a file, a metric) and the outcome that resolved it over the first prompt.
• When prompts span multiple distinct topics, give each its own bullet rather than collapsing everything under the title's framing.
• Use the TITLE only as a fallback label when the prompts are too thin to characterize the work.

6. Merge into today's note

Read notes/YYYY-MM-DD-sessions.md if it exists, merge, and rewrite. Sessions are keyed by short session id (first 8 chars of the uuid): update an existing session's entry in place (extend its time range, refine bullets with the new activity); add new sessions under their project heading. Never duplicate a session entry.

---
date: YYYY-MM-DD
generated-by: session-journal
updated: <ISO timestamp>
---

# Claude sessions — YYYY-MM-DD

## <project>

- **HH:MM–HH:MM** `<branch>` (<short-id>): what was worked on; decisions; blockers

If there was no new activity this tick, only refresh the updated: field (or, if the note doesn't exist yet, write nothing).

7. Save state and report

Write the updated state file (new lastRun, advanced perFile offsets, date, selfSessions). Do NOT commit or push anything in cg-notes.

End your output with a one-line status and the self-exclusion marker, e.g.:

3 sessions, 2 updated, 1 new. [session-journal tick]

Loop behavior

When running under /loop in dynamic (self-paced) mode, schedule the next wakeup 1200-1800 seconds out with the same prompt after finishing the tick. A quiet tick (no new activity) can stretch toward 1800s; a busy one can use 1200s. Only end the loop if the user asks or cg-notes is missing.

A bare /session-journal invocation (no loop) is a single pass: run the tick and stop.