Teaching Claude to Leave Itself a Note

Every long session ends with amnesia

If you work with an AI coding assistant for more than an hour, you eventually hit the wall. The context window fills up. Responses get slower and vaguer. You type /clear and start fresh — and everything the AI knew about the current work is gone.

The decisions you made together. The dead end you already ruled out. The dev server still running on port 3000. The thing you agreed to do next. All of it.

So you implement a workaround: before clearing, you ask for a summary. The AI writes one. You select it, copy it, hit /clear, and paste it into the empty session. Now the new AI knows what happened.

It works. It’s also three manual steps, and that started to get annoying.

The skill that got me most of the way

A while back I found a shared “session handoff” skill that was pretty solid. Just a set of instructions that tells Claude exactly what a good handoff looks like. Not just “summarize the session,” but a rigid template: decisions locked, files touched, background processes still running, how to verify things still work, open questions nobody answered.

That last part matters more than it sounds. A summary written for a human reads like a status report. A summary written for a future version of the AI is a completely different document — it needs shell IDs and absolute file paths, not narrative. The skill was explicit about this: the audience is a future instance of you.

It was genuinely good. But it ended with this rule:

Chat output only. Never write the handoff to a file.

The person who created it intentionally wanted to see the handoff, copy it, manually clear, and manually paste. Maybe that’s better for them but after a couple successful handoffs I decided I didn’t need to see it anymore and I certainly don’t feel like manually copying and pasting.

So I asked Claude if we could streamline the handoff. Claude said “sure - put it in a file and two of the three steps disappear”.

What a hook actually is

Here’s the piece I didn’t know I had.

Claude Code supports hooks — small shell scripts that run automatically when something happens. A session starts, you submit a prompt, the AI finishes a response. You register a script, and it fires.

The one I needed is SessionStart. It runs the moment a new session begins, including right after you /clear. And critically, it can hand text back to Claude — text that lands right in the AI’s context right when it’s needed.

Which means the second half of the copy-paste is automatable. The AI doesn’t need to be told to look for a handoff note. The note is just there, already read, before it says anything.

The parts that actually took thought

The plumbing was the easy half. Write file, read file, done. The design questions were where the real decisions lived.

Where does the note live? My first instinct was to put it in the project folder — visible, travels with the code, a teammate could read it. Claude pushed back: that pollutes every repo you touch, needs a .gitignore entry each time, and a stale handoff accidentally committed is genuinely dangerous. Better to keep it outside the project entirely, in a global folder, filed under a name derived from the project’s path. Zero footprint in the repo. I went with that.

What happens after it’s read? This is the one that would have bitten me. Imagine writing a handoff on Tuesday, then opening a session in the same folder on Saturday to do something completely unrelated. The note gets injected, and now the AI is confidently oriented around week-old context that has nothing to do with your actual question.

That’s worse than no handoff at all. Wrong context is more expensive than missing context, because you don’t notice it.

The fix: consume it exactly once. The hook injects the note, then immediately moves it to an archive folder. It can never fire twice. The injection also states how old the note is — “written 3 days ago” — and explicitly tells the AI to say out loud what it picked up, and to discard it if it’s irrelevant to what I actually asked.

What if the script breaks? Every failure path exits silently. No file, malformed input, missing dependency — the script gives up quietly and the session starts normally. A handoff tool that can break session startup is a net negative no matter how well it works the rest of the time. This was non-negotiable.

There’s a small race condition too, and the fix is elegant enough to mention: the script moves the file to the archive first, then reads it from there. If two sessions somehow start at the same instant, only one can win the move. Order of operations as a locking mechanism.

The thing I couldn’t automate

One step survives: I still have to say “handoff” before I clear.

There’s no pre-clear hook to fire on. And even if there were, hooks are shell scripts — a shell script can’t make the AI compose a thoughtful summary of a conversation it just had. Writing the note is a thinking task. Only the model can do it.

So the flow is: say “handoff,” then /clear. Two steps down to one, and the clipboard is out of it entirely.

I’d rather have that stated plainly than discover it the hard way. Which brings me to the part I’ve started caring about more than the feature itself.

Verify, or it didn’t happen

One of the four rules I keep in my project instructions is: define success criteria, loop until verified.

Before writing any code, we agreed on what “working” meant. Four things: a note written in project A shows up after clearing. A second clear with no new note does nothing at all and produces no error. Weird content — quotes, backslashes, emoji, $(whoami), Japanese characters — survives the round trip byte-for-byte. And a session in project B never, ever sees project A’s note.

Then Claude ran 21 checks against those criteria and showed me the output. All passed. Including the hostile-content one, which I’d have never thought to test, and which is exactly where this kind of thing usually breaks.

It also told me, unprompted, what it hadn’t verified: it had tested the script by feeding it realistic input directly, but it couldn’t watch Claude Code actually fire the hook on a real /clear — that requires restarting the session, which it can’t do from inside the session.

That admission is worth more to me than the passing tests. “Here’s what I proved, here’s what I’m inferring” is the difference between a tool I trust and a tool I have to re-check.

The takeaway

The interesting move here wasn’t building anything. It was noticing that a rule in someone else’s tool — never write to a file — was the only thing standing between a workflow I tolerated and one I didn’t have to think about.

Now whenever the context window starts to get rediculous I can just “handoff -> clear” and keep on driving without Claude losing anything important.

If you find this handy and would like a copy of the files that make it work just ping me and I’d be happy to share.