session-continuity 0.1.3

package/LICENSE

@@ -0,0 +1,116 @@
+PolyForm Noncommercial License 1.0.0
+
+Copyright (c) 2026 Waycraft (https://github.com/100615056)
+
+This software is provided under the PolyForm Noncommercial License 1.0.0.
+Full license text: https://polyformproject.org/licenses/noncommercial/1.0.0
+
+---
+
+Acceptance
+
+In order to get any license under these terms, you must agree to them as both
+strict obligations and conditions to all your licenses.
+
+Copyright License
+
+The licensor grants you a copyright license for the software to do everything
+you might do with the software that would otherwise infringe the licensor's
+copyright in it for any permitted purpose. However, you may only distribute
+the software according to Distribution License and make changes or new works
+based on the software according to Changes and New Works License.
+
+Distribution License
+
+The licensor grants you an additional copyright license to distribute copies
+of the software. Your license to distribute covers distributing the software
+with changes and new works permitted by Changes and New Works License.
+
+Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms or the URL for them above, as well as
+copies of any plain-text lines beginning with Required Notice: that the
+licensor provided with the software. For example:
+
+    Required Notice: Copyright Waycraft (https://github.com/100615056)
+
+Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and
+new works based on the software for any permitted purpose.
+
+Patent License
+
+The licensor grants you a patent license for the software that covers patent
+claims the licensor can license, or becomes able to license, that you would
+infringe by using the software.
+
+Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public
+knowledge, personal study, private entertainment, hobby projects, amateur
+pursuits, or religious observance, without any anticipated commercial
+application, is use for a noncommercial purpose.
+
+Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research
+organization, public safety or health organization, environmental protection
+organization, or government institution is use for a noncommercial purpose
+regardless of the source of funding or obligations resulting from the funding.
+
+Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do
+not limit them.
+
+No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses
+to anyone else, or prevent the licensor from granting licenses to anyone else.
+These terms do not imply any other licenses.
+
+Patent Defense
+
+If you make any written claim that the software infringes or contributes to
+infringement of any patent, your patent license for the software granted under
+these terms ends immediately. If your employer makes such a claim, your patent
+license ends immediately for work on behalf of your employer.
+
+Violations
+
+The first time you are notified in writing that you have violated any of these
+terms, or done anything with the software not covered by your licenses, your
+licenses can nonetheless continue if you come into full compliance with these
+terms, and take practical steps to correct past violations, within 32 days of
+receiving notice. Otherwise, all your licenses end immediately.
+
+No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+Definitions
+
+The licensor is the entity offering these terms, and the software is the
+software the licensor makes available under these terms.
+
+You refers to the individual or entity agreeing to these terms.
+
+Your company is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+
+Your licenses are all the licenses granted to you for the software under
+these terms.
+
+Use means anything you do with the software requiring one of your licenses.
+
+Trademark means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,175 @@
+# sc — session continuity for Claude Code
+
+Pick up exactly where you left off across Claude sessions. No re-explaining context, no copy-pasting summaries — just open a new session and keep working.
+
+---
+
+## How it works
+
+When a Claude session ends, `sc` automatically writes a snapshot to `.claude/session.md`:
+- **Git state** — branch, status, recent commits, diff stat
+- **Narrative** — what was being worked on, decisions made, next steps, blockers (generated by `claude -p`)
+
+When a new session starts, Claude reads `session.md` automatically via a `CLAUDE.md` import — no action needed.
+
+```
+Session ends → Stop hook → sc snapshot → .claude/session.md
+New session starts → CLAUDE.md @import → full context loaded ✓
+```
+
+---
+
+## Install
+
+```bash
+npm install -g session-continuity
+```
+
+> Requires Node.js ≥ 18 and the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code).
+
+---
+
+## Quickstart
+
+**One-time setup per project:**
+
+```bash
+cd your-project
+sc init
+```
+
+That's it. `sc init` does three things:
+1. Creates `.claude/session.md` (the snapshot file)
+2. Adds `@.claude/session.md` to `CLAUDE.md` so Claude reads it on every session start
+3. Registers a `Stop` hook in `.claude/settings.json` so `sc snapshot` runs automatically when a session ends
+
+**From then on, every session:**
+- Ends by writing a snapshot automatically
+- Starts with full context from the last snapshot
+
+---
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `sc init` | Wire up a project (run once) |
+| `sc snapshot` | Write a snapshot now (called automatically by the Stop hook) |
+| `sc status` | Show the current session state |
+| `sc rotate` | Manually trigger a snapshot — use this before force-quitting Claude |
+| `sc clear` | Reset session history |
+| `sc decide "<why>"` | Pin a permanent decision that survives the rolling session window |
+
+---
+
+## Snapshot format
+
+Each snapshot is a dated markdown block. Up to 3 sessions are kept (newest first); older sessions roll off automatically.
+
+```markdown
+---
+## Session — 2026-05-24T21:30:00Z | branch: feat/auth
+
+**Git status:**
+...
+
+**Recent commits:**
+...
+
+**Narrative:**
+**Status:** Implementing JWT refresh token flow — middleware done, route handler in progress.
+
+**Decisions made:**
+- Storing refresh tokens in httpOnly cookies (not localStorage) to prevent XSS
+- Using a 15-minute access token TTL based on security requirements
+
+**Next steps:**
+- Wire up the /auth/refresh route
+- Add token rotation on each refresh
+
+**Blockers:** None
+---
+```
+
+---
+
+## Pinning decisions
+
+Use `sc decide` to record architectural choices, tradeoffs, or rejected ideas that should survive past the 3-session rolling window:
+
+```bash
+sc decide "Chose Postgres over SQLite — need concurrent writes in production"
+sc decide "Rejected Redis for session storage — adds ops complexity we don't need yet"
+```
+
+Pinned decisions appear at the top of `session.md` under a `## Pinned decisions` block and are never trimmed.
+
+---
+
+## .gitignore recommendation
+
+Session state is personal — add this to your project's `.gitignore`:
+
+```
+.claude/session.md
+.claude/session.md.tmp
+```
+
+Do commit `.claude/settings.json` (it contains the Stop hook config other contributors need).
+
+---
+
+## Troubleshooting
+
+**Narrative says `[unavailable]`**
+
+The `claude` CLI is not in your PATH. Check with `claude --version`. If not installed, follow the [Claude Code setup guide](https://docs.anthropic.com/en/docs/claude-code). Without it, `sc snapshot` still writes objective git state — just no AI-generated narrative.
+
+**Context not loading in new sessions**
+
+Check that `CLAUDE.md` contains `@.claude/session.md`. If the line is missing, re-run `sc init` — it's safe to run multiple times.
+
+**Hook not firing**
+
+Verify `.claude/settings.json` has a `Stop` hook pointing to `sc snapshot`:
+
+```json
+{
+  "hooks": {
+    "Stop": [{ "hooks": [{ "type": "command", "command": "sc snapshot" }] }]
+  }
+}
+```
+
+If it's missing, run `sc init` again. Also confirm `sc` is in your PATH (`which sc`).
+
+**Session ended without a snapshot (crash / force-quit)**
+
+Run `sc rotate` manually to write a snapshot from the current git state. To avoid this in future, run `sc rotate` before closing Claude if you know you'll be force-quitting.
+
+**`sc init` breaks my existing hooks**
+
+It won't — `sc init` merges into `.claude/settings.json` rather than overwriting it. Your existing hooks are preserved.
+
+---
+
+## How sessions are bounded
+
+- **Rolling window:** 3 sessions kept, newest first. Older sessions roll off.
+- **Per-session token cap:** ~200 tokens per session entry (~600 tokens total). Well within Claude's context budget.
+- **Pinned decisions:** Never trimmed — use `sc decide` for anything you want to keep long-term.
+
+---
+
+## Roadmap
+
+- `PostToolUse` incremental checkpointing (crash safety without `sc rotate`)
+- `sc history` — list past session headers
+- `sc diff` — show git diff since last snapshot
+- Configurable rolling window size
+
+---
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+import{existsSync as R,readFileSync as z,writeFileSync as k}from"fs";import{readFileSync as B,writeFileSync as I,existsSync as D,mkdirSync as H,renameSync as G}from"fs";import{execSync as J}from"child_process";import{join as v}from"path";var p=".claude",n=v(p,"session.md"),x=v(p,"settings.json"),h="CLAUDE.md",w="@.claude/session.md",N=3,_=150,u=`<!-- sc: no previous session recorded -->
+`;function S(e){D(e)||H(e,{recursive:!0})}function L(e,o={}){if(!D(e))return o;try{return JSON.parse(B(e,"utf8"))}catch{return o}}function O(e,o){I(e,JSON.stringify(o,null,2)+`
+`,"utf8")}function m(e,o){let t=e+".tmp";I(t,o,"utf8"),G(t,e)}function f(e,o=""){try{return J(`git ${e}`,{encoding:"utf8",stdio:["pipe","pipe","pipe"]}).trim()}catch{return o}}function C(e,o){let t=e.split(/\s+/).filter(Boolean);return t.length<=o?e:t.slice(0,o).join(" ")+" \u2026[trimmed]"}var q="## Pinned decisions";function $(e){if(!e.includes(q))return{pinned:"",rest:e};let o=e.indexOf(`
+---
+`);return o===-1?{pinned:e.trim(),rest:""}:{pinned:e.slice(0,o).trim(),rest:e.slice(o)}}function b(e){return e.split(/^---$/m).map(o=>o.trim()).filter(o=>o&&!o.startsWith("<!--"))}function A(e){return e.map(o=>`---
+${o}
+`).join(`
+`)+`
+`}async function P(){let e=[];S(p),e.push("\u2713 .claude/ directory ready"),R(n)?e.push("\xB7 .claude/session.md already exists"):(k(n,u,"utf8"),e.push("\u2713 .claude/session.md created"));let o=R(h),t=o?z(h,"utf8"):"";t.includes(w)?e.push("\xB7 CLAUDE.md already has @import"):(t=`
+<!-- sc: session continuity -->
+${w}
+`+t,k(h,t,"utf8"),e.push(`\u2713 CLAUDE.md ${o?"updated":"created"} with @import`));let s=L(x,{}),d={type:"command",command:"sc snapshot"};s.hooks||(s.hooks={}),s.hooks.Stop||(s.hooks.Stop=[]),s.hooks.Stop.some(r=>Array.isArray(r.hooks)&&r.hooks.some(a=>a.command&&a.command.includes("sc snapshot")))?e.push("\xB7 Stop hook already registered"):(s.hooks.Stop.push({hooks:[d]}),O(x,s),e.push("\u2713 Stop hook registered in .claude/settings.json"));let c=!1;try{let{execSync:r}=await import("child_process");r("claude --version",{stdio:"pipe"}),c=!0,e.push("\u2713 claude CLI found \u2014 narrative snapshots enabled")}catch{e.push("\u26A0 claude CLI not found \u2014 snapshots will be objective-only (git state, no narrative)")}console.log(`
+sc init complete
+`),e.forEach(r=>console.log(" ",r)),console.log(`
+How it works:`),console.log("  \u2022 When a Claude session ends, sc snapshot runs automatically"),console.log("  \u2022 The snapshot is saved to .claude/session.md"),console.log("  \u2022 CLAUDE.md imports it, so every new session starts with full context"),c||(console.log(`
+  To enable narrative summaries, install the Claude CLI:`),console.log("  https://docs.anthropic.com/en/docs/claude-code")),console.log()}import{spawnSync as X}from"child_process";import{existsSync as Y,readFileSync as V}from"fs";var K=`You are summarizing a Claude Code development session for the developer who just finished it.
+Given the git state below, write a concise session snapshot in this exact format (no other text):
+
+**Status:** <one sentence \u2014 what was being worked on and where things stand>
+
+**Decisions made:**
+- <decision 1 \u2014 include the "why" if inferable from context>
+- <decision 2>
+
+**Next steps:**
+- <most important thing to do next>
+- <second thing if applicable>
+
+**Blockers:** <"None" or a brief description>
+
+Rules:
+- Total response must be under 120 words
+- Be specific \u2014 name files, functions, or commands if relevant
+- If git state shows no meaningful changes, say "No significant changes this session"
+- Do not add headings, preamble, or closing remarks \u2014 just the five fields above
+
+Git state:
+`;function Q(){let e=f("branch --show-current","unknown"),o=f("status --short","(no changes)"),t=f("log --oneline -5","(no commits)"),s=f("diff --stat HEAD","").split(`
+`).slice(0,10).join(`
+`);return{branch:e,status:o,log:t,diffStat:s}}function Z(e,o){let{branch:t,status:s,log:d,diffStat:i}=o;return[`## Session \u2014 ${e} | branch: ${t}`,"","**Git status:**","```",s||"(clean)","```","","**Recent commits:**","```",d||"(none)","```",i?`
+**Diff stat:**
+\`\`\`
+${i}
+\`\`\``:""].filter(c=>c!==void 0).join(`
+`).trim()}function ee(e){let o=[`Branch: ${e.branch}`,`Status:
+${e.status}`,`Recent commits:
+${e.log}`,e.diffStat?`Diff stat:
+${e.diffStat}`:""].filter(Boolean).join(`
+
+`),t=K+o,s=X("claude",["-p",t],{encoding:"utf8",timeout:15e3,stdio:["pipe","pipe","pipe"]});return s.status!==0||s.error||!s.stdout.trim()?null:s.stdout.trim()}async function g(){S(p);let e=new Date().toISOString(),o=Q(),t=Z(e,o),s=ee(o);if(s){let E=C(s,_);t+=`
+
+**Narrative:**
+`+E}else t+="\n\n**Narrative:** [unavailable \u2014 run `claude --version` to enable]";let d=Y(n)?V(n,"utf8"):"",{pinned:i,rest:c}=$(d),r=b(c),a=[t,...r].slice(0,N),y=(i?i+`
+`:"")+A(a);m(n,y),process.stderr.write(`[sc] snapshot written \u2014 ${e}
+`)}import{existsSync as oe,readFileSync as te}from"fs";async function W(){if(!oe(n)){console.log("No session file found. Run `sc init` first.");return}let e=te(n,"utf8").trim();if(!e||e.startsWith("<!--")){console.log("No session recorded yet. End a Claude session to generate the first snapshot.");return}console.log(`
+\u2500\u2500 Current session state (`+n+`) \u2500\u2500
+`),console.log(e),console.log(`
+\u2500\u2500 end \u2500\u2500
+`)}import{existsSync as se}from"fs";import{createInterface as ne}from"readline";async function j(){if(!se(n)){console.log("Nothing to clear \u2014 .claude/session.md does not exist.");return}if(!await ie("Clear all session history? This cannot be undone. (y/N) ")){console.log("Aborted.");return}m(n,u),console.log("Session history cleared.")}function ie(e){return new Promise(o=>{let t=ne({input:process.stdin,output:process.stdout});t.question(e,s=>{t.close(),o(s.trim().toLowerCase()==="y")})})}async function F(){console.log("Writing snapshot\u2026"),await g(),console.log("Done. Run `sc status` to review.")}import{existsSync as re,readFileSync as ce}from"fs";var T="## Pinned decisions",ae="<!-- sc: pinned decisions survive the rolling session window -->";async function M([e]){(!e||!e.trim())&&(console.error('Usage: sc decide "Your decision or rationale here"'),process.exit(1));let o=e.trim(),t=`- ${o}`,s=new Date().toISOString(),d=`${t} _(${s})_`,i=re(n)?ce(n,"utf8"):u,c;if(i.includes(T))c=i.replace(/(## Pinned decisions\n(?:<!--[^>]*-->\n)?)([\s\S]*?)(\n---|\n<!-- sc:|$)/,(r,a,y,E)=>`${a}${y}
+${d}${E}`);else{let r=`${T}
+${ae}
+${d}
+
+`,a=i.indexOf(`---
+`);a===-1||i.trim()===u.trim()?c=r+(i.startsWith("<!--")?"":i):c=i.slice(0,a)+r+i.slice(a)}m(n,c),console.log(`Decision pinned: "${o}"`)}var[,,l,...le]=process.argv,U={init:P,snapshot:g,status:W,clear:j,rotate:F,decide:M};(!l||l==="--help"||l==="-h")&&(console.log(`
+sc \u2014 session continuity for Claude Code
+
+Commands:
+  sc init              Wire up this project (run once per project)
+  sc snapshot          Write a session snapshot (called automatically by Stop hook)
+  sc status            Show the current session state
+  sc clear             Reset session history
+  sc rotate            Manually trigger a snapshot write (use before force-quit)
+  sc decide "<why>"    Pin a permanent decision that survives the rolling window
+
+Options:
+  --version, -v  Print version
+  --help, -h     Show this help
+`),process.exit(0));if(l==="--version"||l==="-v"){let{createRequire:e}=await import("module"),t=e(import.meta.url)("../package.json");console.log(t.version),process.exit(0)}U[l]||(console.error(`Unknown command: ${l}. Run 'sc --help' for usage.`),process.exit(1));try{await U[l](le)}catch(e){console.error(`sc ${l} failed:`,e.message),process.exit(1)}

package/dist/server.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+import{McpServer as C}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as L}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as r}from"zod";import{existsSync as x,readFileSync as y,readdirSync as N,mkdirSync as O}from"fs";import{join as d,basename as S}from"path";import{homedir as k}from"os";import{createHash as I}from"crypto";import{readFileSync as M,writeFileSync as j,existsSync as W,mkdirSync as F,renameSync as v}from"fs";import{join as h}from"path";var l=".claude",U=h(l,"session.md"),X=h(l,"settings.json");var m=3;function f(e,s){let t=e+".tmp";j(t,s,"utf8"),v(t,e)}var c=d(k(),".sc","sessions");function g(){x(c)||O(c,{recursive:!0})}function A(e){return I("sha1").update(e).digest("hex").slice(0,12)}function w(e){return d(c,`${A(e)}.json`)}function u(e){let s=w(e);if(!x(s))return{path:e,name:S(e),pinned:[],sessions:[]};try{return JSON.parse(y(s,"utf8"))}catch{return{path:e,name:S(e),pinned:[],sessions:[]}}}function b(e,s){g(),f(w(e),JSON.stringify(s,null,2)+`
+`)}function $(e,s){let t=u(e);return t.sessions=[s,...t.sessions].slice(0,m),b(e,t),t}function _(e,s){let t=u(e);return t.pinned=t.pinned||[],t.pinned.push({text:s,timestamp:new Date().toISOString()}),b(e,t),t}function D(){return g(),N(c).filter(e=>e.endsWith(".json")).map(e=>{try{return JSON.parse(y(d(c,e),"utf8"))}catch{return null}}).filter(Boolean).sort((e,s)=>{let t=e.sessions[0]?.timestamp??"";return(s.sessions[0]?.timestamp??"").localeCompare(t)})}import{createRequire as P}from"module";var{version:R}=P(import.meta.url)("../package.json"),a=new C({name:"session-continuity",version:R});a.tool("load_session","Load the previous session context for a project. Call this at the start of every session to restore context without re-explanation.",{project_path:r.string().describe("Absolute path to the project root. Defaults to current working directory.").optional()},async({project_path:e})=>{let s=e||process.cwd(),t=u(s);if(t.sessions.length===0&&t.pinned.length===0)return{content:[{type:"text",text:`No previous session found for ${t.name}. This appears to be a fresh start.`}]};let n=[`# Session context \u2014 ${t.name}`,`**Project:** ${t.path}`,""];return t.pinned.length>0&&(n.push("## Pinned decisions"),t.pinned.forEach(o=>n.push(`- ${o.text} *(${o.timestamp})*`)),n.push("")),t.sessions.forEach((o,p)=>{n.push(`## ${p===0?"Last session":`Session ${p+1} ago`} \u2014 ${o.timestamp}`),n.push(`**Branch:** ${o.branch}`),n.push(`**Status:** ${o.status}`),o.decisions?.length&&(n.push("**Decisions made:**"),o.decisions.forEach(i=>n.push(`- ${i}`))),o.next_steps?.length&&(n.push("**Next steps:**"),o.next_steps.forEach(i=>n.push(`- ${i}`))),o.blockers&&n.push(`**Blockers:** ${o.blockers}`),n.push("")}),{content:[{type:"text",text:n.join(`
+`)}]}});a.tool("save_session","Save the current session context. Call this at the end of a session or at any checkpoint. Claude should summarize what happened, decisions made, and what comes next.",{project_path:r.string().describe("Absolute path to the project root. Defaults to current working directory.").optional(),status:r.string().describe("One sentence: what was being worked on and where things stand."),decisions:r.array(r.string()).describe("Key decisions made this session, each with the reason why.").optional(),next_steps:r.array(r.string()).describe("Ordered list of what to do next session, most important first.").optional(),blockers:r.string().describe('Current blockers, or "None".').optional(),branch:r.string().describe("Current git branch.").optional()},async({project_path:e,status:s,decisions:t,next_steps:n,blockers:o,branch:p})=>{let i=e||process.cwd(),E={timestamp:new Date().toISOString(),branch:p||"unknown",status:s,decisions:t||[],next_steps:n||[],blockers:o||"None"};return $(i,E),{content:[{type:"text",text:`Session saved for ${i}.
+Next session will start with: "${s}"`}]}});a.tool("pin_decision","Pin a permanent decision or architectural choice that should survive the rolling session window. Use for tradeoffs, rejected alternatives, and why-choices.",{project_path:r.string().describe("Absolute path to the project root. Defaults to current working directory.").optional(),decision:r.string().describe('The decision to record. Include the "why" \u2014 e.g. "Chose X over Y because Z."')},async({project_path:e,decision:s})=>{let t=e||process.cwd();return _(t,s),{content:[{type:"text",text:`Decision pinned: "${s}"`}]}});a.tool("list_projects","List all projects with tracked session history, sorted by most recently active.",{},async()=>{let e=D();if(e.length===0)return{content:[{type:"text",text:"No projects tracked yet. Save a session first."}]};let s=[`# Tracked projects
+`];return e.forEach(t=>{let n=t.sessions[0];s.push(`**${t.name}**`),s.push(`  Path: ${t.path}`),n&&(s.push(`  Last session: ${n.timestamp}`),s.push(`  Status: ${n.status}`)),t.pinned?.length&&s.push(`  Pinned decisions: ${t.pinned.length}`),s.push("")}),{content:[{type:"text",text:s.join(`
+`)}]}});var T=new L;await a.connect(T);

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "session-continuity",
+  "version": "0.1.3",
+  "description": "Pick up where you left off across Claude sessions — zero re-explanation.",
+  "bin": {
+    "sc": "./dist/cli.js",
+    "sc-mcp": "./dist/server.js"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "node build.js",
+    "prepare": "node build.js",
+    "test": "node --test src/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "claude-code",
+    "session",
+    "context",
+    "memory",
+    "continuity",
+    "ai-native",
+    "workflow",
+    "developer-tools"
+  ],
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.0"
+  }
+}