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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

### Changed

- The READMEs call sessionpad beta software rather than alpha.
- 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
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
A Claude Code mod that gives every session a small notepad: a one-line headline that says what the session is for, plus notes written by you or by Claude. Open any session after a few days away and see at a glance what it was doing and what is left to do.

> [!WARNING]
> **sessionpad is alpha software. Use it at your own risk.** It is new and has had little use beyond its author's, 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.
> **sessionpad is beta software. Use it at your own risk.** 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.

> [!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.
Expand All @@ -16,7 +16,7 @@ A Claude Code mod that gives every session a small notepad: a one-line headline
>
> 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.4.0, not released yet; 0.3.0 was released 2026-10-29, with all four milestones built (notes, timeline, workspace, pruning).
Status: beta. 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
12 changes: 9 additions & 3 deletions justfile
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,17 @@ clean:
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
# the plugin directory reads $ only as whole $.noun.method(...) calls. It
# reads each line with its comments taken off; it doesn't see a $ taken
# apart by destructuring, a call split between noun and method, or anything
# after a "//" inside a string on the same line.
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)
set -uo pipefail
lines=$(grep -rnE '\$\.' sessionpad/src sessionpad/hooks)
status=$?
if [ "$status" -gt 1 ]; then echo "dollar_check: grep failed"; exit "$status"; fi
found=$(printf '%s\n' "$lines" | sed -E 's#//.*$##; s#/\*.*\*/##g' | grep -vE '^[^:]+:[0-9]+:[[:space:]]*\*' | grep -E '\$\.[a-z]+(\.[a-zA-Z]+)?[[:space:]]*$|\$\.[a-z]+\.[a-zA-Z]+[^a-zA-Z(<]|\$\.[a-z]+[^a-zA-Z.]' || 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
Expand Down
2 changes: 1 addition & 1 deletion sessionpad/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
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 beta software. Use it at your own risk.** 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.

Expand Down
178 changes: 48 additions & 130 deletions sessionpad/hooks/register.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
// pieces live in ../src (data in store.ts, $.state in state.ts, actions in
// pad.ts, drawing in ui.tsx).

import type { EngineInterface, Register, Timer } from "claude-code";
import type { EngineInterface, Register } from "claude-code";

import type { Pad } from "../types";
import { emptyNoteField, forgetEditDrafts } from "../src/drafts";
Expand All @@ -19,10 +19,10 @@ import {
readThisPad,
setThisHeadline,
} from "../src/pad";
import { OFFER_KEY } 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";
import { refreshOffer } from "../src/settings";
import { forgetPaneEdits, readHeadline } from "../src/state";
import { retentionDays, schedulePrune } from "../src/prune";
import { forgetRenewals, keepSeen } from "../src/store";
import { summaryModel } from "../src/summary";
import {
carryTimeline,
Expand All @@ -33,7 +33,7 @@ import {
} from "../src/timeline";
import type { TurnLog } from "../src/timeline";
import {
finishTurn,
finishTurnLater,
followersOf,
isSucceeded,
turnTokens,
Expand All @@ -43,9 +43,8 @@ import type { ClearMove, TimelineSettings } from "../src/turns";
import { isBandAlways, openPane, renderBand, renderPane } from "../src/ui";
import {
forgetMeasuring,
scheduleRefresh,
setMeasureDisk,
startWorkspace,
showWorkspace,
} from "../src/workspace";

const NOTE_TOOL_DESCRIPTION = [
Expand Down Expand Up @@ -288,91 +287,6 @@ async function registerTools($: EngineInterface): Promise<void> {
*/
const MAX_WAITING = 8;

/**
* Prunes sessions not seen for `days` on a timer, a minute after the session
* has loaded, so a start never waits on it and sessions starting alongside
* have marked themselves seen first.
*/
function schedulePrune($: EngineInterface, days: number, keepId: string): void {
$.clock.after(PRUNE_DELAY_MS, async () => {
try {
// The session it is now too: a /resume may have moved it.
const current = await $.session.id().catch(() => keepId);
const pruned = await pruneOld($, days, [keepId, current]);
if (pruned.sessions + pruned.files + pruned.sizes > 0) {
$.ui.log(
`sessionpad: pruned ${pruned.sessions} sessions, ${pruned.files} files and ${pruned.sizes} sizes not seen for ${days} days`,
{ to: "debug" }
);
}
} catch (error) {
$.ui.log(`sessionpad: pruning failed: ${String(error)}`, {
to: "debug",
});
}
});
}

/** How often an open session renews its last-seen time, at most. */
const SEEN_TIMER_MS = 12 * 60 * 60 * 1000;

// The timer that keeps this session seen; one per module.
let seenTimer: Timer | undefined;

/**
* Renews this session's last-seen time while it stays open, however long it
* sits idle, so another session's prune never takes the pad it shows: often
* enough that its row is never older than half of `days`. A later
* session.start in this module replaces the timer.
*/
function keepSeen($: EngineInterface, days: number): void {
seenTimer?.cancel();
seenTimer = undefined;
if (days === 0) return;
const every = Math.min(SEEN_TIMER_MS, (days * 24 * 60 * 60 * 1000) / 4);
seenTimer = $.clock.every(every, () => {
(async () => {
// The session it is now: a /clear or /resume may have moved it.
const id = await $.session.id();
await touchSeen($, id, await $.clock.now(), every);
})().catch((error: unknown) => {
$.ui.log(`sessionpad: could not renew the session: ${String(error)}`, {
to: "debug",
});
});
});
}

// Whether summary lines are off in this module's settings; register sets it.
// Kept here so refreshOffer takes $ alone, the one shape the plugin directory
// reads for a function in a hook's file that passes $ on.
let isSummaryOff = true;

/**
* Shows the Timeline tab's offer to turn summary lines on while they are off
* and nobody has dismissed it yet; never fails the caller.
*/
async function refreshOffer($: EngineInterface): Promise<void> {
try {
const isAnswered = (await $.store.get(OFFER_KEY)) !== undefined;
await showOffer($, isSummaryOff && !isAnswered);
} catch {
// No offer this time: the store couldn't say whether it was answered.
}
}

/** Sets the Workspace tab up and reads git into it, never failing the caller. */
async function showWorkspace($: EngineInterface): Promise<void> {
try {
await startWorkspace($);
scheduleRefresh($, "none");
} catch (error) {
$.ui.log(`sessionpad: could not read the workspace: ${String(error)}`, {
to: "debug",
});
}
}

export const register: Register = (on, options) => {
const showBand = options.showBand !== false;
setMeasureDisk(options.measureDisk !== false);
Expand All @@ -382,7 +296,7 @@ export const register: Register = (on, options) => {
summaryModel: summaryModel(options.summaryModel),
cap: timelineCap(options.timelineCap),
};
isSummaryOff = timeline.summaryModel === null;
const isSummaryOff = timeline.summaryModel === null;
// The session id whose pad is loaded, to carry the pad across /clear and
// /branch, which give the conversation a new id without a session.start.
let loadedId: string | undefined;
Expand Down Expand Up @@ -415,7 +329,7 @@ export const register: Register = (on, options) => {
to: "debug",
});
}
await refreshOffer($);
await refreshOffer($, isSummaryOff);
// A new session or a reload: no `du` from before is still this module's.
forgetMeasuring();
forgetRenewals();
Expand All @@ -439,7 +353,8 @@ export const register: Register = (on, options) => {
forgetEditDrafts();
emptyNoteField($);
try {
const id = e.session_id || (await $.session.id());
let id = e.session_id;
if (!id) id = await $.session.id();
const previous = loadedId ?? endedId;
loadedId = id;
if (previous !== undefined && previous !== id) {
Expand All @@ -461,10 +376,13 @@ export const register: Register = (on, options) => {
// Set before the carry, so a turn's entry written meanwhile is
// sent on too; dropped if the new id kept a timeline of its own.
if (how === "clear") {
clearedTo.set(previous, { to: id, at: await $.clock.now() });
const at = await $.clock.now();
clearedTo.set(previous, { to: id, at });
}
let isTaken = false;
if (how !== undefined) {
isTaken = await carryTimeline($, previous, id, how);
}
const isTaken =
how !== undefined && (await carryTimeline($, previous, id, how));
if (how === "clear" && !isTaken) clearedTo.delete(previous);
} catch (error) {
$.ui.log(
Expand All @@ -482,8 +400,12 @@ export const register: Register = (on, options) => {
// $.state was reset, the Workspace tab's with it, whatever the pad did.
// The Undo card and an open note belonged to the pad left behind, so
// they go too, should a host keep $.state.
await forgetPaneEdits($).catch(() => undefined);
await refreshOffer($);
try {
await forgetPaneEdits($);
} catch {
// Left as they were: the next delete or open replaces them.
}
await refreshOffer($, isSummaryOff);
await showWorkspace($);
return next(e);
}
Expand All @@ -495,17 +417,19 @@ export const register: Register = (on, options) => {
return next(e);
});

on("command.run", { command: ["pad", "sessionpad"] }, ($, e, next) =>
served.has(e.command) ? openPane($) : next(e)
).catch(($, e, next) =>
on("command.run", { command: ["pad", "sessionpad"] }, async ($, e, next) => {
if (!served.has(e.command)) return next(e);
return openPane($);
}).catch(($, e, next) =>
next.called || !served.has(e.command)
? next(e)
: { text: "sessionpad: the pane could not be opened." }
);

// The commands do their work in the hook's own body: the plugin directory
// reads $ passed on to another file only from there, or from a function in
// this file that takes $ alone.
// The commands do their work in the hook's own body. The plugin directory
// reads $ handed to another file's function only from a hook's own body; a
// function in this file may use $ in plain $.noun.method(...) calls and hand
// it, alone, only to another function in this file.
on("command.run", { command: ["note", "pad-note"] }, async ($, e, next) => {
if (!served.has(e.command)) return next(e);
try {
Expand Down Expand Up @@ -623,9 +547,11 @@ export const register: Register = (on, options) => {
const log = turn?.turnId === e.turnId ? turn : newTurnLog(e.turnId, "");
turn = undefined;
try {
const sessionId = await $.session.id();
const at = await $.clock.now();
const finished = {
sessionId: await $.session.id(),
at: await $.clock.now(),
sessionId,
at,
log,
durationMs: e.durationMs,
isAborted: e.isAborted,
Expand All @@ -635,24 +561,15 @@ export const register: Register = (on, options) => {
// A turn that wrote files or ran commands may have changed the tree's
// size; any turn may have moved the branch.
const isChanged = log.fileCount > 0 || log.commands > 0;
$.clock.after(0, () => {
scheduleRefresh($, isChanged ? "changed" : "none");
// A session at work stays seen, however long it stays open.
touchSeen($, finished.sessionId, finished.at).catch(() => undefined);
const followers = (id: string) =>
followersOf(clearedTo, id, finished.at);
finishTurn($, finished, timeline, followers).catch((error: unknown) => {
const why = String(error);
$.ui.log(`sessionpad: the turn was not recorded: ${why}`, {
to: "debug",
});
if (warned.has(finished.sessionId)) return;
warned.add(finished.sessionId);
$.ui.toast(
`sessionpad: turns in this session aren't being added to the timeline: ${why}`
);
});
});
// The slow parts (git, the model) run on a timer, from turns.ts.
finishTurnLater(
$,
finished,
timeline,
(id) => followersOf(clearedTo, id, finished.at),
isChanged,
warned
);
} catch (error) {
$.ui.log(`sessionpad: the turn was not recorded: ${String(error)}`, {
to: "debug",
Expand Down Expand Up @@ -683,9 +600,10 @@ export const register: Register = (on, options) => {
return { deny: "sessionpad: the note could not be saved." };
});

on("tool.call", { tool: "mcp__sessionpad__notes_read" }, async ($) => ({
result: describePad(await readThisPad($)),
})).catch(($, e, next) => {
on("tool.call", { tool: "mcp__sessionpad__notes_read" }, async ($) => {
const pad = await readThisPad($);
return { result: describePad(pad) };
}).catch(($, e, next) => {
$.ui.log(
`sessionpad: notes_read failed: ${next.error?.message ?? "unknown error"}`,
{ to: "debug" }
Expand Down
29 changes: 29 additions & 0 deletions sessionpad/src/prune.ts
Original file line number Diff line number Diff line change
Expand Up @@ -287,3 +287,32 @@ async function removeFiles(
}
return removed;
}

/**
* Prunes sessions not seen for `days` on a timer, a minute after the session
* has loaded, so a start never waits on it and sessions starting alongside
* have marked themselves seen first.
*/
export function schedulePrune(
$: EngineInterface,
days: number,
keepId: string
): void {
$.clock.after(PRUNE_DELAY_MS, async () => {
try {
// The session it is now too: a /resume may have moved it.
const current = await $.session.id().catch(() => keepId);
const pruned = await pruneOld($, days, [keepId, current]);
if (pruned.sessions + pruned.files + pruned.sizes > 0) {
$.ui.log(
`sessionpad: pruned ${pruned.sessions} sessions, ${pruned.files} files and ${pruned.sizes} sizes not seen for ${days} days`,
{ to: "debug" }
);
}
} catch (error) {
$.ui.log(`sessionpad: pruning failed: ${String(error)}`, {
to: "debug",
});
}
});
}
Loading
Loading