You’re three hours into a session with your AI coding assistant. You’ve made a dozen decisions - chose RS256 over HS256 for JWT signing, decided to split the payment service into two microservices, tabled the Redis migration because the staging environment isn’t ready.

Then the session ends. Maybe you closed your laptop. Maybe the context window filled up. Maybe you just went to lunch.

When you come back, it’s all gone. The AI doesn’t remember. You barely remember. The why behind every decision evaporated.

This isn’t a minor inconvenience. It’s a structural problem with how AI-assisted development works today.

What Gets Lost

It’s not just code changes - git handles that. What gets lost is the reasoning layer:

  • Why you chose one approach over another
  • What you tried that didn’t work (and why)
  • Where you left off when you paused
  • Which blockers are waiting on external dependencies
  • Who made which decisions (in team environments)

Six months from now, someone (including future-you) will look at a piece of code and wonder why it’s structured that way. The PR description says “implemented auth.” The commit message says “add JWT middleware.” Neither captures the 20-minute deliberation about signing algorithms, or that you specifically rejected HS256 because a key rotation requirement surfaced during the session.

That context is gone forever. Unless you log it.

The “Write It Down Later” Trap

The obvious solution is: “just write a session summary at the end.”

I tried that. It doesn’t work, for three reasons:

1. Sessions don’t end cleanly. You get interrupted. Context windows fill up. You switch projects. There’s no reliable “end of session” moment where you can calmly summarize what happened.

2. Post-hoc recall is lossy. Even if you do get a clean ending, trying to reconstruct 3 hours of decisions from memory is an exercise in selective recall. You remember the big wins. You forget the small decisions that will matter most in 2 months.

3. It takes effort that never happens. Be honest: how many times have you finished a productive session and thought “I should write that down” and then… didn’t? The activation energy is too high when you’ve just spent your cognitive budget on the actual work.

The solution is to log as you go, not after the fact.

How Session Logger Works

I built a system for Claude Code that captures work during the session, automatically, with minimal friction. It has three layers:

Layer 1: Automatic Reminders (Hooks)

Two shell scripts hook into Claude Code’s lifecycle:

  • On session start: A reminder fires telling the AI to log work to a specific temp file, namespaced by project and date.
  • On every message: A check runs. If no temp log exists for today, a stronger reminder fires. If one exists, a light nudge. Progressive, not nagging.

Claude Code reads these reminders and follows them silently. You never see them. The AI just starts logging.

Layer 2: Temp Logs (Real-Time Capture)

As Claude works, it appends timestamped entries to a temp log file:

## 14:30 - Implemented user authentication
- Added JWT token validation middleware
- Chose RS256 over HS256 for key rotation support
- Blocked on: Redis session store not configured yet

## 16:15 - Fixed cart total calculation bug
- Root cause: floating point rounding on discount percentages
- Applied Math.round(amount * 100) / 100 pattern
- Added regression test in cart.test.ts

Notice what’s captured: not just what was done, but why (key rotation support), what was tried (the root cause), and what’s blocked (Redis). This is the reasoning layer that normally vanishes.

Layer 3: Consolidation

Two paths, and the automatic one matters most:

Automatic: When you say “save my work” or “commit and push,” the workspace-sync agent auto-consolidates temp logs before committing. You can’t forget to consolidate because it happens as part of saving your code.

Manual: Say “consolidate my logs” to run the session-logger agent directly.

Both paths do the same thing:

  1. Scan all temp logs
  2. Write brief summaries to monthly master logs (e.g., logs/frontend-session-log-2025-03.md)
  3. Archive the raw temp logs (never deleted - they hold the full detail)
  4. Update project status files

Monthly files keep context manageable - a single ever-growing log would choke AI context windows within weeks.

Why This Matters More Than You Think

Full decision traceability. Every line in your codebase exists because someone decided it should be that way. Session logs preserve the decision chain. When a new team member asks “why is this service split in two?” you don’t say “I think it was a performance thing?” - you point to the session log from March 15th.

The foundation for measurement. Structured, timestamped logs across all projects give you: time-per-task patterns, blocker frequency analysis, context switching costs, and AI effectiveness data. You can’t optimize what you don’t measure.

Continuity across sessions. Start a new session, read yesterday’s log, know exactly where you left off. The AI can read it too - “read today’s session log and continue where I left off” becomes a reliable workflow.

Multi-contributor attribution. Each temp log is namespaced by username (resolved from GitHub). When the session-logger consolidates, each contributor gets their own section. No merge conflicts. Clear attribution.

What I Learned Running This for 2 Months

I’ve used this system across 5 projects for about 2 months. Some things I discovered:

Log quality improves over time. The first week, entries were sparse - “did stuff with auth.” By week 3, entries were detailed enough to be useful months later. The hooks train the habit.

The archive is surprisingly valuable. I thought the archive was just backup. Turns out, when the consolidated log is too compressed, the raw temp log from that day has the full context. I’ve gone back to it several times.

Project routing matters. Early on, work consistently got miscategorized - workspace tooling work ended up in the business project log. The fix: define projects by what changes (which files/repo), not by topic keywords.

“What NOT to log” is as important as “what to log.” Without guidance, the AI logs everything including dead-end research and trivial formatting fixes. The instruction that says “don’t log exploratory research that didn’t lead anywhere” made the logs dramatically more useful.

Timestamps need an explicit timezone source. I caught one session where all timestamps were in UTC instead of local time. The entries looked plausible (valid HH:MM) so nobody noticed until I cross-referenced with real-world events. Now the hooks use date from the shell, which respects the system timezone.

Getting Started

The entire system is open-source: github.com/41fred/claude-code-session-logger

git clone https://github.com/41fred/claude-code-session-logger.git
cd claude-code-session-logger
./install.sh /path/to/your/project

The install script creates the directory structure, copies the hooks and agents (session-logger + workspace-sync), and sets up the settings.json. You customize the project mapping, add the CLAUDE.md section, and start a new session. That’s it.

What’s Next

This is the capture layer. Once you have the data, the interesting things you can build on top include:

  • Weekly digest generators that summarize all work across projects
  • Blocker dashboards that surface recurring impediments
  • Time allocation reports that show where effort actually goes vs. where you think it goes
  • Onboarding accelerators - new team members read the session log to understand not just the code, but the reasoning behind it

I’m building some of these. If the community finds the logging system useful, I’ll open-source the analysis tools too.

If your team is producing work with AI and losing the context behind it, I’d enjoy the conversation. Book a call.