Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# Changelog

## Unreleased

### Added

- An icon and a README of its own in the plugin folder, for a listing in Anthropic's plugin directory. The icon's source is `assets/icon.svg`.

## 0.3.0 (2026-10-29)

### Added
Expand Down
22 changes: 12 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Status: alpha. Version 0.3.0, released 2026-10-29, with all four milestones buil

## Requirements

Claude Code 2.1.299 or later, in the Desktop app's Code tab or a terminal. Mods themselves run from 2.1.286 (Desktop) and 2.1.287 (terminal), but releases before 2.1.299 refuse this mod's hooks module, which passes `$` to functions in its other files. Mods don't run in regular claude.ai chats or in Desktop WSL sessions. In `claude -p` and the Agent SDK the commands and tools work but nothing is drawn. The tests run on 2.1.299 (CI) and on the newest release when developing; the releases between aren't tested.
Claude Code 2.1.299 or later, in the Desktop app's Code tab or a terminal. Mods themselves run from 2.1.286 (Desktop) and 2.1.287 (terminal), but releases before 2.1.299 refuse this mod's hooks module, which passes `$` to functions in its other files. Mods don't run in regular claude.ai chats, in Cowork or in Desktop WSL sessions. In `claude -p` and the Agent SDK the commands and tools work but nothing is drawn. The tests run on 2.1.299 (CI) and on the newest release when developing; the releases between aren't tested.

## Install

Expand Down Expand Up @@ -109,7 +109,7 @@ Everything stays on your machine, with one exception: the summary line. The mod

The store holds at most 4 MiB for all sessions together, so a pad keeps at most 100 notes of up to 4,000 characters each, and a headline is one line of up to 200 characters. Text past a limit is cut, and the mod says so. If the store ever refuses a write, the command or pane says the note wasn't saved rather than dropping it silently.

**Old sessions are pruned.** A minute after a session starts, about once a day across sessions, a session nobody has opened for `retentionDays` (90 by default) loses its pad, its timeline file and its row in the index, and a worktree size measured that long ago is dropped. A session counts as unopened only when the index hasn't seen it and its timeline hasn't been written in that time, and a session left open renews its time once a day as its turns end, so one at work in another window is never pruned. Exports are your own files and are never touched. Set `retentionDays` to 0 to keep everything.
**Old sessions are pruned.** A minute after a session starts, about once a day across sessions, a session nobody has opened for `retentionDays` (90 by default) loses its pad, its timeline file and its row in the index, and a worktree size measured that long ago is dropped. A session counts as unopened only when the index hasn't seen it and its timeline hasn't been written in that time, and a session left open renews its time on a timer, often enough that its row is never older than half of `retentionDays`, turns or no turns, so one open in another window is never pruned. Exports are your own files and are never touched. Set `retentionDays` to 0 to keep everything.

## Uninstall

Expand All @@ -128,23 +128,25 @@ That leaves your data. To delete it too, delete the mod's store file, the one na
`claude plugin validate` reads the mod the way Claude Code will and lists every event it hooks and every API call it makes. For this version it reports, in part (the full report also lists the hooks that answer for themselves and the `$.state` values, and names the function behind each call):

```
hooks: session.start, classic.SessionStart{source=clear|resume|fork}, session.end,
hooks: session.start, classic.SessionStart{source=clear|resume|fork},
config.set{key="sessionpad.summaryModel"}, session.end,
command.run{command=pad|sessionpad}, command.run{command=note|pad-note},
command.run{command=headline|pad-headline}, command.run{command=pad-export},
prompt.submit, turn.start, tool.call{tool=Edit|Write|NotebookEdit|Bash},
turn.complete, tool.call{tool=mcp__sessionpad__note},
tool.call{tool=mcp__sessionpad__notes_read},
ui.render{component=Pane, requestId=sessionpad}, ui.render{component=AbovePrompt}
calls: $.clock.after, $.clock.now, $.command.list, $.command.register, $.env.get,
$.fs.exists, $.fs.list, $.fs.read, $.fs.stat, $.fs.write, $.model.complete,
$.process.run, $.session.cwd, $.session.id, $.session.repo, $.state.get,
$.state.set, $.store.delete, $.store.get, $.store.keys, $.store.set,
$.tool.register, $.ui.log, $.ui.open, $.ui.resolve, $.ui.toast
calls: $.clock.after, $.clock.every, $.clock.now, $.command.list,
$.command.register, $.config.set, $.env.get, $.fs.exists, $.fs.list,
$.fs.read, $.fs.stat, $.fs.write, $.model.complete, $.process.run,
$.session.cwd, $.session.id, $.session.repo, $.state.get, $.state.set,
$.store.delete, $.store.get, $.store.keys, $.store.set, $.tool.register,
$.ui.invalidate, $.ui.log, $.ui.open, $.ui.resolve, $.ui.toast
env reads: CLAUDE_CONFIG_DIR, HOME, USERPROFILE
env writes: nothing
```

There is no `$.http`: the only thing that leaves your machine is the summary line's model call, described above. `$.process.run` runs `git` (read-only commands), `du -sk` and `rm` on the mod's own files. The hooks on `prompt.submit`, `turn.start` and the `tool.call` for Edit, Write, NotebookEdit and Bash only watch: each passes the event on and hands back what came back, untouched. Run `claude plugin validate sessionpad` in a clone to see the full report.
There is no `$.http`: the only thing that leaves your machine is the summary line's model call, described above. `$.process.run` runs `git` (read-only commands), `du -sk` and `rm` on the mod's own files. `$.config.set` changes only the mod's own `summaryModel`, when you press **Turn on summaries**, and the `config.set` hook only watches that one setting change. The hooks on `prompt.submit`, `turn.start` and the `tool.call` for Edit, Write, NotebookEdit and Bash only watch: each passes the event on and hands back what came back, untouched. Run `claude plugin validate sessionpad` in a clone to see the full report.

## Development

Expand Down Expand Up @@ -202,7 +204,7 @@ Decisions made while building, and places where this build of Claude Code (2.1.3
- **A worktree inside another is counted in both.** Claude Code's own worktrees live under the main checkout's `.claude/worktrees/`, so the main checkout's size includes theirs. `du` has no portable way to leave them out.
- **Git is read again** when the session starts, when the tab opens, after every turn (the branch may have moved) and on **Refresh sizes**: `rev-parse --show-toplevel`, `symbolic-ref` (and `rev-parse --short HEAD` for a detached HEAD), and `worktree list --porcelain`. A bare entry and a worktree whose folder is gone (`prunable`) are listed but not measured. Where the worktree list can't be read, the tab shows this tree alone.
- **Pruning deletes files with `rm`.** The mods API can read, write, list and stat files but not delete them, so timeline files go through `$.process.run(["rm", "-f", "--", ...paths])`, up to 100 at a time, only for names the mod writes (`<id>.json`, or `<id>.json.corrupt-<time>`) in its own timeline folder, and run in that folder rather than the session's: on some systems a program is found in the folder it runs in before the PATH, and a project could ship one named `rm`. `du` runs from the home folder for the same reason, or from the root folder when the home folder isn't there, and never from the session's folder: with neither, the size reads unavailable. `git` does run in the session's folder, which it has to read; Claude Code runs it there too. Where there is no `rm`, as on Windows, or it fails, each file left is emptied instead, so nothing of the session stays in it; one already empty isn't written again.
- **Two signals before pruning.** A session is pruned only when the index's last-seen time and its timeline file's time are both older than `retentionDays`; the index alone would prune a session that has been open, and working, for longer. A session renews its last-seen time at the end of a turn, at most once a day. An index that can't be read, or isn't one, stops the prune, since every old file would look like one no session owns. Notes whose index row went missing (two sessions writing the index at once) get a row, and age out from then. A turn puts back this session's row when it is missing.
- **Two signals before pruning.** A session is pruned only when the index's last-seen time and its timeline file's time are both older than `retentionDays`; the index alone would prune a session that has been open, and working, for longer. A session renews its last-seen time at the end of a turn, at most once a day, and while it stays open on a timer (every 12 hours, or a quarter of `retentionDays` when that is shorter), so its row is never older than half of `retentionDays`, turns or no turns. An index that can't be read, or isn't one, stops the prune, since every old file would look like one no session owns. Notes whose index row went missing (two sessions writing the index at once) get a row, and age out from then. A turn puts back this session's row when it is missing.
- **Looked at again before anything goes.** The prune waits a minute after the start, so sessions starting together (the Desktop app restoring several, say) have each marked itself seen. Then, right before a session's notes go, its index row and timeline file are read afresh; if it was opened in that moment, its notes go back. Each old file is looked at again too, and the index row goes last, re-read first. `prune:at` in the store records the last prune, so it runs about once a day however many sessions start (sessions that check it in the same instant may each prune once, which the second looks above make safe); a short `claude -p` run is over before it prunes at all. It keeps the session as it started and as it is a minute later, so one resumed in that minute is kept too. Notes given a row in this prune keep their timeline file in it as well, a session kept by a second look keeps its index row, and notes put back never cover newer ones written in that moment. `touchIndex`, which marks a session seen as it loads, leaves an index that isn't one as it found it, so the prune can still stop on it. Files are looked at again a batch at a time, just before their `rm`. This session is never pruned, even when its time couldn't be renewed. A stored size the mod can't read (a newer version's, say) is left alone.
- **CI pins the `claude` CLI** to 2.1.299, the oldest release that loads the mod and the minimum the Requirements name, so CI checks that promise and a new release can't change what CI runs overnight. Development runs the newest release, so both ends are tested. Raise the pin, and the minimum, on purpose. CI skips `type_check`, since the types it needs are written by loading the mod.

Expand Down
25 changes: 25 additions & 0 deletions assets/icon.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added sessionpad/.claude-plugin/icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
57 changes: 57 additions & 0 deletions sessionpad/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Session Pad

A notepad for each Claude Code session. Give a session a one-line headline that says what it is for, keep notes beside the chat (yours, or ones Claude takes when you ask), and see a timeline of what each turn did and where the session's work lives on disk. Open a session after a few days away and see at a glance what it was doing and what is left to do.

> [!WARNING]
> **Session Pad is alpha software. Use it at your own risk.** It is new, and a later version may change how it stores your notes. Keep anything you can't lose somewhere else as well; `/pad-export` writes a session's notes and timeline to a Markdown file.

Session Pad is a Claude Code mod: it runs in Claude Code 2.1.299 or later, in the Desktop app's Code tab or a terminal, and not in claude.ai chat, Cowork or the Desktop app's WSL sessions.

## What it adds

- **A pane, `/pad`**, with three tabs:
- **Notes:** the headline, a field to add a note, and every note as Markdown, each with **Make headline**, **Edit** and **Delete**. A deleted note can be put back with **Undo**.
- **Timeline:** one line for each turn of the conversation, newest first under its date: when it ended, how long it ran, a one-line summary, and marks for files written, commands run, a stopped turn and a branch change. **Export** writes the notes and the whole timeline to a Markdown file.
- **Workspace:** the branch, the worktree's folder and its disk use, and the repository's other worktrees with their branches and sizes.
- **The band above the prompt:** `pad: <headline>` in one dim line, and in the Desktop app an **Open pad** button.
- **Commands:** `/note <text>`, `/headline [text]` and `/pad-export [path]`.
- **Two tools for Claude**, `note` and `notes_read`, so Claude can take or read notes when you ask it to. They wait behind tool search, so they cost nothing on requests that don't use them.
- **Across sessions:** notes carry across `/clear`, and `/branch` starts from the parent's notes.

## What it runs, sends and stores

- **Nothing leaves your machine unless you turn on summary lines.** The mod makes no network calls of its own.
- **Summary lines are off until you turn them on**, with **Turn on summaries** in the Timeline tab or the `summaryModel` setting. With them on, after each turn the mod asks Claude Haiku, on your own plan or API key, for a one-line summary. It sends the prompt's first 200 characters, the start of Claude's final answer (1,500 characters at most), the names of the files written (not their paths or contents) and the number of commands run. A call is about 500 tokens in and 20 out, roughly 6 cents per 1,000 turns on Haiku 5.5 at the API prices of October 2026 (ten times that if your Claude Code's `haiku` is Haiku 4.5); the Timeline tab shows the running total.
- **What it watches in the session:** it hooks each prompt you send, each turn's start and end, and each Edit, Write, NotebookEdit and Bash call, to write the timeline: the prompt's first 200 characters, the paths of the files written (up to 25 a turn) and how many commands ran. These hooks only observe: they pass every prompt and call on unchanged, and never block one.
- **Programs it runs:** `git`, read-only, in the session's folder, for the branch and the worktrees; `du -sk` from your home folder (the root folder where there is none), in the background, to measure worktree sizes (the `measureDisk` setting turns this off); and `rm`, only on the mod's own timeline files, when old sessions are pruned (where there is no `rm`, as on Windows, those files are emptied instead).
- **What it stores, all on your machine:**
- in the mod's key-value store, a JSON file under `~/.claude/plugins/store/`: each session's headline and notes; an index of sessions, with each one's working folder, repository root and when it was last seen; each worktree's measured size, keyed by its path; the running total of summary calls; whether the summary offer was answered; and when the last prune ran;
- one timeline file a session under `~/.claude/sessionpad/timeline/`, each entry holding when the turn ended and how long it ran, the prompt's first 200 characters, the summary line, up to 25 paths written, the number of commands, the branch, the worktree's path and the turn's token counts;
- exports under `~/.claude/sessionpad/exports/` unless you name a path.

The two `~/.claude` folders are under `CLAUDE_CONFIG_DIR` instead when that is set.

- **What it deletes:** a session nobody has opened for `retentionDays` (90 by default) loses its pad, its timeline file (and any copy of one put aside as unreadable) and its index row; sizes measured that long ago go too, and so do timeline files that old that no session in the index owns. Exports are never touched.
- **Settings it changes:** only its own `summaryModel`, when you press **Turn on summaries**.

## Settings

| Key | Default | Effect |
| --------------- | ------- | ---------------------------------------------------------------------------- |
| `showBand` | `true` | Show the band above the prompt: the headline, and on Desktop **Open pad** |
| `measureDisk` | `true` | Run `du` on the repository's worktrees for the Workspace tab |
| `retentionDays` | `90` | Days a session can go unopened before it is pruned; 0 keeps everything |
| `summaryModel` | `off` | `off`, or `haiku` to have Haiku write each turn's summary line |
| `timelineCap` | `500` | Entries a session's timeline file keeps, from 1 to 1000; the oldest go first |

## Install, update, uninstall

Added from the plugin directory on claude.ai, it reaches Claude Code through your account (as `sessionpad@synced`), and you update or remove it there.

From the author's own marketplace instead: in a terminal session, `/plugin install sessionpad --marketplace j127/sessionpad`; in the Desktop app, **+** next to the prompt box, **Plugins**, **Add marketplace** with `j127/sessionpad`, then **Add plugin**. That copy updates with `claude plugin update sessionpad@sessionpad` and uninstalls with `claude plugin uninstall sessionpad@sessionpad`. Uninstalling leaves your notes and timelines where they are.

The full README, with the design notes, how to run the tests and what each setting does in detail, is at [github.com/j127/sessionpad](https://github.com/j127/sessionpad).

## License

MIT. See [LICENSE](LICENSE).
12 changes: 4 additions & 8 deletions sessionpad/hooks/register.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,7 @@ import {
readThisPad,
setThisHeadline,
} from "../src/pad";
import {
OFFER_KEY,
SUMMARY_CONFIG_KEY,
summaryModelNow,
useSummaryModel,
} from "../src/settings";
import { OFFER_KEY, summaryModelNow, useSummaryModel } from "../src/settings";
import { forgetPaneEdits, readHeadline, showOffer } from "../src/state";
import { PRUNE_DELAY_MS, pruneOld, retentionDays } from "../src/prune";
import { forgetRenewals, touchSeen } from "../src/store";
Expand Down Expand Up @@ -529,8 +524,9 @@ export const register: Register = (on, options) => {
).catch(($, e, next) => next(e));

// The person set summaryModel in /config: the next turn follows it, and the
// Timeline tab stops offering, since they have chosen.
on("config.set", { key: SUMMARY_CONFIG_KEY }, async ($, e, next) => {
// Timeline tab stops offering, since they have chosen. The key is spelled
// out (SUMMARY_CONFIG_KEY's value) so validate can read the matcher.
on("config.set", { key: "sessionpad.summaryModel" }, async ($, e, next) => {
const result = await next(e);
if (result.deny === undefined) {
useSummaryModel(summaryModel(result.value));
Expand Down
Loading