claude-session-restore

The rules for anyone who changes this repo, person or agent. Claude Code reads this file through .claude/CLAUDE.md, Codex reads it directly; the gate caps it at 150 lines. What the plugin does for those who use it is in README.md.

What this is

session-restore, a Claude Code plugin (a mod: a hooks module, no MCP server, no skills) that reopens the sessions a crash, a restart or a closed terminal cut off. The repo is its own marketplace.

• The plugin (plugin/): hooks/register.tsx hooks the session's life and draws the band and the pane; hooks/lib.ts holds the pure logic (which sessions count as cut off, the launch flags, the command lines); types/index.d.ts declares the record and the plugin's state.
• It runs inside Claude Code, in an environment with no DOM and no Node: everything outside reaches it through $ ($.fs, $.process, $.session, $.ui). The API is early access and changes between Claude Code releases.
• On every system: Windows Terminal (or console windows) on Windows; Terminal, iTerm2 or tmux on macOS; tmux or the desktop's terminal on Linux; the commands printed where no window can open. docs/design.md says how each part works.

Where things are

A new top-level file or folder adds its row in the same change.

Build and test

You need Node 24, git, and gitleaks for the secret scan. Claude Code itself comes pinned from npm ci.

• The plugin's types come from Claude Code: it writes them to plugin/.claude-plugin/types/ when a session loads the mod. No command writes them, so CI can't check them: gate quick checks them where they are, and skips with the reason where they are not. Load the mod once before a PR that changes plugin/.
• Tests run in the engine's sandbox: $.fs, $.process and the clock are mocks, so no test starts a terminal or a PowerShell. What only a real session shows (a restore, the band) is checked by hand, and the PR says how.

How a change lands

1. An issue for anything beyond a typo.
2. A plan in docs/plans/ for non-trivial work (docs/plans/README.md says when), reviewed with review-plan until approved, then approved by the maintainer.
3. A branch <issue>-<slug> from origin/main, the plan its first commit.
4. The code, with its tests and docs in the same change.
5. finish-work: node tools/gate.ts full, review-code until clean, a PR.
6. The maintainer, @serionist, squash-merges; merging is the approval. main takes PRs only.

The skills in .claude/skills/ run this loop: start-work (1 to 3), review-plan, review-code, finish-work (5), and write-skill for writing or fixing a skill.

Writing

• A lead line, then a table or short bullets. Conclusion first; name the file, the command, the number.
• Plain words. No "ensure", "robust", "comprehensive", "leverage" or "seamless"; spaced hyphens, never em dashes; British spelling (behaviour, licence).
• A comment says why, not what the next line does, and says it in its own words, not only as a plan or review id.
• Docs move in the same change: README.md and plugin/README.md for what users see, docs/design.md for how it works, CHANGELOG.md when users notice, this file for a changed path, command or rule.

Commits and PRs

• A plain imperative subject that says what changed; a body that says why, ending Refs #<n> or Closes #<n>.
• PRs are squash-merged: the PR title becomes the subject on main, its description the body.
• No tool attribution anywhere: no AI co-author trailers, no "Generated with" lines, no session links, in commits, PR titles or PR bodies. commit-msg refuses them, the gate checks every message, and CI checks the PR's text.
• Versions: users get a change only when plugin.json's version moves. A release PR sets it and dates the CHANGELOG section (docs/releasing.md); no other PR touches it.

One-way doors

Users depend on these. Change one only in a PR that names it in its title, after the maintainer agrees in its issue; in 0.x a minor may break one, under CHANGELOG's Breaking.

• the plugin's and the marketplace's name, session-restore;
• the /restore command and its arguments (all, numbers, an id prefix, forget);
• the shell and terminal options, their names and their values;
• the record folder, <config>/session-restore/sessions/, and the record's fields: a new version reads the records an older one wrote, so a field is added, never renamed or retyped.

Traps

What this code already paid for; docs/design.md has the detail.

Look up APIs before coding against them

The hooks API: plugin/.claude-plugin/types/claude-code/index.d.ts, written by the Claude Code that loaded the mod; grep it for the event or noun ('session.end', Pane: {). npm run claude -- plugin validate plugin lists what the module hooks and calls, and what the engine would refuse. Anything else (Windows Terminal, PowerShell, Node): Context7 (.mcp.json) or the vendor's docs, never memory.

Never

• Push to main, or merge with a failing gate.
• Weaken a test, a check, a hook or CI to make a change pass: no skip, no new ignore, no --no-verify.
• Check out, build or run code from outside the maintainers (a contributor's PR or branch) on your machine: read it, and let CI run it. A hooks module runs in every Claude session, with every credential there.
• Put a record's text (a folder, a flag, a path) into a script or a command line a shell parses: it travels as data (psString, crtQuote, posixQuote; docs/design.md).
• Add tool attribution: commits, PR titles, PR bodies.
• Commit secrets, or a real person's session record: tests use invented ones.
• Change a one-way door without the maintainer's agreement.