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: 5 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
# Changelog

## Unreleased
## 0.4.0 (not released yet)

### Changed

- The Timeline tab's summary offer says how to turn summary lines on (set `summaryModel` to `haiku`) and has a **Got it** button, instead of a **Turn on summaries** button that changed the setting: the plugin directory accepts no settings call from a mod that keeps its engine for later, as every button and timer in this one does. A change in `/config` reloads the mod with the new value.

### Added

Expand Down
21 changes: 13 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,15 @@ A Claude Code mod that gives every session a small notepad: a one-line headline
> [!NOTE]
> **Summary lines spend some of your Claude usage, so they are off until you turn them on.** With them on, the mod asks Claude Haiku for a one-line summary after each turn. A call sends about 500 tokens and gets about 20 back. At the API prices of October 2026 that is about $0.00006 a turn on Haiku 5.5 ($0.10 and $0.50 per million tokens in and out), or about 6 cents per 1,000 turns; if your Claude Code's `haiku` is Haiku 4.5 ($1 and $5), ten times that. On a Pro or Max plan it counts against your usage limits instead of costing money, and a single turn of your own conversation usually uses thousands of times as much. The Timeline tab's last line shows the running total.
>
> To turn them on, press **Turn on summaries** in the Timeline tab, or set `summaryModel` to `haiku` in `/config` (or with `/plugin configure sessionpad@sessionpad`). To turn them off, set it back to `off`. Sessions already open in other windows may keep the old setting until they start again. While they are off, each turn's line in the Timeline is its prompt's first line, and the mod makes no model calls at all.
> To turn them on, set `summaryModel` to `haiku`: in a terminal session with `/config` or `/plugin configure sessionpad@sessionpad`, or from a shell (which serves the Desktop app's sessions too) with
>
> ```bash
> echo '{"summaryModel":"haiku"}' | claude plugin configure sessionpad@sessionpad --values-stdin
> ```
>
> To turn them off, set it back to `off` the same way. Sessions already open in other windows may keep the old setting until they start again. While they are off, each turn's line in the Timeline is its prompt's first line, and the mod makes no model calls at all.

Status: alpha. Version 0.3.0, released 2026-10-29, with all four milestones built (notes, timeline, workspace, pruning).
Status: alpha. Version 0.4.0, not released yet; 0.3.0 was released 2026-10-29, with all four milestones built (notes, timeline, workspace, pruning).

## What it does

Expand Down Expand Up @@ -128,16 +134,15 @@ 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},
config.set{key="sessionpad.summaryModel"}, session.end,
hooks: session.start, classic.SessionStart{source=clear|resume|fork}, 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.every, $.clock.now, $.command.list,
$.command.register, $.config.set, $.env.get, $.fs.exists, $.fs.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,
Expand All @@ -146,7 +151,7 @@ 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. `$.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.
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 mod changes no settings: the plugin directory accepts no settings call from a mod that, as this one does in its buttons and timers, keeps the engine for later, so the Timeline tab says how to turn summary lines on instead of doing it. 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 @@ -177,11 +182,11 @@ Decisions made while building, and places where this build of Claude Code (2.1.3
- **The input field sits under the headline**, above the notes, so it stays in view however many notes there are.
- **The tools wait behind tool search**, as MCP tools do, so they cost nothing on requests that don't use them. Their names (`mcp__sessionpad__note`, `mcp__sessionpad__notes_read`) are enough for Claude to find them.
- **Bold text uses `bold`**, which every surface draws; the Desktop app's table turns it into its own weight.
- **How it looks.** The pane follows the Cards design, `mockups/pane_as_drawn/02-cards.html` (the choice is recorded in `DECISION.md` beside it), drawn only with what a design test page (`/pad-demo`, removed once the look was settled) showed each surface can draw, as `mockups/sessionpad_pane/RENDERING.md` records. On Desktop the headline, each note, each day of the timeline and the current worktree sit on soft filled cards: a faint round border around a see-through grey fill (`rgba(128, 128, 128, 0.12)`), which reads as a light grey on the light pane and a dark grey on the dark one, so it follows the mode where an opaque raw color would turn unreadable in one of them; the Undo card is tinted red the same way. The cards were first filled with the theme's `promptBorder` shade, which drew too dark for the dim text and the buttons on them. A terminal would fill those with a mid grey block, so there a card is a grey frame, and the headline and the note being edited take the accent frame. The open tab is the app's primary pill on Desktop; a colored or bold label inside a Button draws only in a terminal, which shows the open tab that way. Hover can't reveal anything on Desktop and a terminal has none, so every button says what it does in its own label. An edited note's Save is its field's own submit button, since Desktop draws that button whatever else is beside it. Both fields, the note field and an edited note's, ask for three rows; 2.1.299, the oldest release the mod supports, has no `rows` for a field and draws them as one line. Times sit in a fixed-width column, since runs of spaces collapse on both surfaces. Text in the timeline wraps rather than being cut, and the pane is sized to `100%` of its body rather than a count of cells, since the Desktop app's proportional text doesn't keep to one. What the note field and an open note's field hold is kept as it is typed, so a redraw for any other reason (a note added from another window, say) puts it back; it is kept in the module rather than in `$.state`, because a `$.state` write draws the pane again and the Desktop app then draws the field afresh, which made its border flash at every keystroke. Emptying the note field after a note is added takes two draws, since the app sets a field's text only when the value it is drawn with changes and typing drew nothing: one with what the field holds, then, a quarter of a second later, one empty. A reload of the mod starts them over: it comes with an update of the mod and with a change to its settings (**Turn on summaries** is one), and then the note field empties, and a note open for editing stays open but shows its own text again, losing what was typed in it and not saved.
- **How it looks.** The pane follows the Cards design, `mockups/pane_as_drawn/02-cards.html` (the choice is recorded in `DECISION.md` beside it), drawn only with what a design test page (`/pad-demo`, removed once the look was settled) showed each surface can draw, as `mockups/sessionpad_pane/RENDERING.md` records. On Desktop the headline, each note, each day of the timeline and the current worktree sit on soft filled cards: a faint round border around a see-through grey fill (`rgba(128, 128, 128, 0.12)`), which reads as a light grey on the light pane and a dark grey on the dark one, so it follows the mode where an opaque raw color would turn unreadable in one of them; the Undo card is tinted red the same way. The cards were first filled with the theme's `promptBorder` shade, which drew too dark for the dim text and the buttons on them. A terminal would fill those with a mid grey block, so there a card is a grey frame, and the headline and the note being edited take the accent frame. The open tab is the app's primary pill on Desktop; a colored or bold label inside a Button draws only in a terminal, which shows the open tab that way. Hover can't reveal anything on Desktop and a terminal has none, so every button says what it does in its own label. An edited note's Save is its field's own submit button, since Desktop draws that button whatever else is beside it. Both fields, the note field and an edited note's, ask for three rows; 2.1.299, the oldest release the mod supports, has no `rows` for a field and draws them as one line. Times sit in a fixed-width column, since runs of spaces collapse on both surfaces. Text in the timeline wraps rather than being cut, and the pane is sized to `100%` of its body rather than a count of cells, since the Desktop app's proportional text doesn't keep to one. What the note field and an open note's field hold is kept as it is typed, so a redraw for any other reason (a note added from another window, say) puts it back; it is kept in the module rather than in `$.state`, because a `$.state` write draws the pane again and the Desktop app then draws the field afresh, which made its border flash at every keystroke. Emptying the note field after a note is added takes two draws, since the app sets a field's text only when the value it is drawn with changes and typing drew nothing: one with what the field holds, then, a quarter of a second later, one empty. A reload of the mod starts them over: it comes with an update of the mod and with a change to its settings (in `/config`, say), and then the note field empties, and a note open for editing stays open but shows its own text again, losing what was typed in it and not saved.
- **The tab digits are the terminal's.** A digit presses a tab only while the pane holds the keyboard, which a terminal gives it with ctrl+x tab; elsewhere a digit goes to the prompt, so the Desktop app's tabs are drawn without them.
- **The band's width.** The band refuses Claude Code's own row under a Box with a width, so the width is on the row that holds the headline and, on Desktop, the **Open pad** button.
- **Open pad lives in the band.** A mod can't add a button to the app's toolbar or title bar: the places it can draw are the transcript's messages, the prompt's hints, the band above the prompt and panes. The band is the one always in view, so the button goes there, on every surface but the terminal.
- **Summaries are off by default.** `summaryModel` ships as `off`, since each call spends some of the person's usage and spending it should be their choice. The line Haiku writes is what makes the Timeline worth reading after a few days away, so the Timeline tab offers it once, with **Turn on summaries** and **Not now**; the answer is kept for every session under the store key `summary-offer`, which pruning leaves alone. Changing `summaryModel` in `/config` counts as an answer too, and the next turn follows it without a reload.
- **Summaries are off by default.** `summaryModel` ships as `off`, since each call spends some of the person's usage and spending it should be their choice. The line Haiku writes is what makes the Timeline worth reading after a few days away, so while it is off the Timeline tab says what it costs and how to turn it on, until **Got it** dismisses that for every session (the store key `summary-offer`, which pruning leaves alone). The tab can't turn it on itself: the plugin directory accepts no settings call from a mod that keeps its engine for later, as every button and timer here does. A change in `/config` reloads the mod with the new value.
- **The pane opens only when asked:** with `/pad`, or with the band's **Open pad** button on Desktop. Opening it unasked at the start of a session with notes is still an open question.
- `$.fs.write` creates missing directories, which the timeline file relies on. The home folder comes from `HOME`, else `USERPROFILE` on Windows, and `CLAUDE_CONFIG_DIR` wins over both. With none of them set, no timeline is kept and `/pad-export` asks for a path.
- **A turn's prompt comes from `turn.start`**, not `prompt.submit` as the spec had it. `turn.start` carries the turn's id, the same one `turn.complete` carries, so the prompt and the end are paired exactly; `prompt.submit` also fires for prompts typed while a turn runs, which join that turn rather than starting one.
Expand Down
10 changes: 9 additions & 1 deletion justfile
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,15 @@ clean:

# Run every check: formatting, types, tests. CI runs this recipe on pull
# requests into main, and you run it before pushing.
check: format_check validate type_check test
check: format_check validate type_check dollar_check test

# Fail when a call on $ is split across lines or a property of $ is read:
# the plugin directory reads $ only as whole $.noun.method(...) calls
dollar_check:
#!/usr/bin/env bash
set -euo pipefail
found=$(grep -rnE '\$\.[a-z]+(\.[a-zA-Z]+)?\s*$|\$\.[a-z]+\.[a-zA-Z]+[^a-zA-Z(]' sessionpad/src sessionpad/hooks | grep -vE '^[^:]+:[0-9]+:\s*(//|\*|/\*)' || true)
if [ -n "$found" ]; then echo "$found"; echo "Write each call on \$ whole, on one line: \$.noun.method(...)"; exit 1; fi

# Check formatting of the mod, the marketplace file and the docs
format_check:
Expand Down
2 changes: 1 addition & 1 deletion sessionpad/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "sessionpad",
"displayName": "Session Pad",
"version": "0.3.0",
"version": "0.4.0",
"description": "A notepad for each Claude Code session: a headline and notes, a timeline of every turn, and the session's worktree and disk use, in a pane and above the prompt.",
"author": {
"name": "J"
Expand Down
15 changes: 13 additions & 2 deletions sessionpad/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Session Pad is a Claude Code mod: it runs in Claude Code 2.1.299 or later, in th
## 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.
- **Summary lines are off until you turn them on**, with the `summaryModel` setting (see [Settings](#settings)). 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:**
Expand All @@ -32,7 +32,10 @@ Session Pad is a Claude Code mod: it runs in Claude Code 2.1.299 or later, in th
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 it changes:** none. It reads its own settings, and a change you make in `/config` reloads it.
- **The model call** goes through Claude Code's own model access, on the plan or API key the session already uses; the mod never reads a key, token or credential itself.
- **What its hooks change:** nothing that passes through them, with two exceptions that are the mod's own: its hooks on its two tools, `note` and `notes_read`, answer those tools, which is how they work, and its commands answer `/pad`, `/note`, `/headline` and `/pad-export`.
- **Files it writes outside its own folders:** only the `/pad-export` file you name. An export never replaces a file that isn't an earlier export: each one starts with the line `<!-- sessionpad export -->`, and a file without it is left alone.

## Settings

Expand All @@ -44,6 +47,14 @@ Session Pad is a Claude Code mod: it runs in Claude Code 2.1.299 or later, in th
| `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 |

To change a setting, run `/config` in a terminal session, or `/plugin configure <id>`. From a shell, which also serves the Desktop app's sessions, this turns summary lines on:

```bash
echo '{"summaryModel":"haiku"}' | claude plugin configure <id> --values-stdin
```

`<id>` is the name `claude plugin list` shows for Session Pad: `sessionpad@sessionpad` when it came from the author's marketplace. Set `summaryModel` back to `off` the same way to turn them off. A change reloads the mod with the new value.

## 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.
Expand Down
Loading
Loading