reminder-hook

Your coding agent forgets your rules. This puts them back, once every 64k
tokens.

You write rules in CLAUDE.md. The agent follows them for a while. Past about
100k tokens it starts to forget. You remind it. It forgets again.

CLAUDE.md is read once, at the start of the session. It is never read again.

I am not a native English speaker. My rules are mostly about language: short
sentences, no idioms, no invented terms, plain words. When the agent forgets
them, its answers become hard for me to read, and I have to stop and ask again.
That is what made me build this.

Install

Give INSTALL.md to your agent and say "install this". It
contains the script, the settings change, and a test. The agent does the work.

Or do it by hand, three steps, also in that file.

How it works

The hook measures the session transcript file size. About 4 bytes is 1 token, so
262144 bytes is about 64k tokens. It divides the size by that step. If the
result grew since last time, it injects your rules and saves the new number. If
not, it prints nothing.

Between steps it costs zero tokens. Injecting on every prompt also works,
and wastes your context on repetition.

Why 64k: an educated guess. Long context became real when models crossed 64k,
then 100k, now 1M. 64k is a reasonable point to refresh. It is a parameter.
Change it with REMINDER_STEP_BYTES.

Two levels

~/.claude/reminder.md          your rules, in every project
<project>/.claude/reminder.md  that project's rules, appended after

Both apply. The global file is not replaced.

Global is for how you want the agent to talk and behave. Project is for facts
about that codebase:

- Never edit files under generated/. The build step rebuilds them.
- Tests run with `make test`, not pytest directly.
- The staging database is read only. Ask before any write.

Those are the facts an agent forgets at 100k tokens, right before it breaks
something.

reminders/

A collection of reminder files people actually use. Take one, change it, or add
your own with a pull request. See CONTRIBUTING.md.

• plain-english.md mine. Simplified Technical
  English, answer only what was asked, no half-finished jobs.

Who wrote this

I am Uncle Code, author of
Crawl4AI
.
I use Claude Code every day and I write my rules in plain English because I have
to.

Find me on X: @unclecode.

License

MIT. Use it, change it, no need to ask.