repo-notes

On-command external memory for Claude Code. Curated docs about each repo you work in — summary, architecture, active workstreams — kept in a separate local notes repo, outside the codebase.

Unlike CLAUDE.md or automatic memory, nothing loads passively and nothing lives in the code repo. Useful when you can't (or don't want to) commit notes into the repo itself, and it keeps the token cost at zero until you ask for it.

How it works

One notes root (its own git repo), one subdirectory per code repo:

notes-root/
  my-service/
    summary.md              # entrypoint — the only doc `load` always reads
    architecture/           # stable knowledge: code standards, testing, what it does
    workstreams/<slug>/     # active work: checklist.md, implementation.md, bugs.md
    archive/                # stale docs, date-suffixed, ignored unless asked for
  another-repo/
    ...

A config at ~/.claude/repo-notes.json points at the notes root and maps repos to subdirectories. The skill creates it on first use.

Install

This repo is its own plugin marketplace. In Claude Code:

/plugin marketplace add CalciumG/claude-repo-notes
/plugin install repo-notes@repo-notes

Or copy the skill directly — works, but you get no updates and no save reminder (hooks only ship with the plugin):

cp -r skills/repo-notes ~/.claude/skills/repo-notes

Updates

No version pin — every pushed commit is a new version. Pick up the latest with /plugin marketplace update repo-notes, or turn on auto-update once: /plugin → Marketplaces → repo-notes → Enable auto-update. Claude Code then refreshes in the background and reloads the plugin when new commits land.

First run

cd into any repo and run /repo-notes init. It asks where your notes root should live (one git repo holding notes for all your repos), then does a bounded first-pass scan of the codebase to draft the architecture docs and summary. Expect a starting point, not an audit — the docs sharpen as you save real sessions.

Commands

Run from inside any code repo:

Command	Does
/repo-notes init	Scaffold this repo's notes dir; first-pass architecture docs from the code
/repo-notes load [topic]	Read the summary; drill into topic docs if named
/repo-notes save [workstream]	End-of-session write-back: workstreams, drift, summary, commit
/repo-notes archive <path>	Move a doc or workstream to the archive, date-suffixed
/repo-notes status	Staleness report from frontmatter only — no doc bodies loaded

You don't have to use the slash command. Plain language works too — "load my repo notes", "save this session to my notes", "update my repo docs" — Claude matches it to the right command. The slash form is deterministic: it always fires, whereas phrasing relies on Claude recognising the intent. Either way, nothing runs unless you ask.

How I use it

At the start of a piece of work, if I've touched the area before, I load the notes first. Then I give Claude the ticket, or describe what I'm after in my own words, on top of that context. It replaces the slow "go read the codebase and work out how this hangs together" step at the top of every session. Claude still verifies against the code, but it starts from a map instead of a blank page.

While I'm working I don't touch the notes at all. The rhythm is: raise a PR, be happy with it, then save. Each save updates the workstream docs, and I take a quick look over the files to see what's still earning its place.

I archive slowly, on purpose. A feature might stretch over ten hours across days, and even once it ships I want the references close by for a while. Workstreams go to the archive when I stop reaching for them, not the moment they merge.

The payoff comes later. When someone asks how something works months on, or I want to remind myself of the key aspects, the answer is one load away: read the doc, or ask Claude to summarise from it.

Save reminder

The one automated piece. When a session ends, a Stop hook checks three things — you're in a tracked repo, the session actually edited files, and you haven't already been reminded this session. Only if all three pass do you see a single line:

repo-notes: unsaved session work in my-service. /repo-notes save to keep it.

It costs zero tokens: the hook is a shell script that runs outside the model, and the message goes to you, not to Claude. Nothing is written to your notes — saving is still your call. Quick Q&A sessions, read-only sessions, and untracked repos never trigger it.

To turn it off, add "reminder": false to ~/.claude/repo-notes.json.

Ground rules

• No production secrets or PII — mock data and test credentials only.
• Hard length caps (summary ≤60 lines, implementation ≤150) enforced on save; overflow is archived, not deleted.
• Every doc carries an updated: date; anything older than 90 days is flagged stale and verified against the code before being trusted.
• The archive is stale-until-verified and never browsed for context.