claude-yaad 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rahmangamer12
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# claude-yaad
+
+**Session memory and usage savers for Claude Code. One command, zero tokens.**
+
+*Yaad* means "memory" in Urdu. Claude Code forgets everything on `/clear`, and long sessions burn your usage limit because every message re-sends the whole conversation. `claude-yaad` fixes both:
+
+- **Each project remembers where it was.** A fresh session (after `/clear`, a compact, a crash or a new day) starts by reading that project's own small state file.
+- **Long sessions get flagged.** You get a one-line warning when the context passes ~200k tokens, so you can `/save` and `/clear` before every message gets expensive.
+- **Sessions never grow huge.** Auto-compact runs at a 150k-token window, so a long chat can't creep to 200k+ tokens re-read on every message (this was the single biggest usage drain we measured: one chat re-read 216 million tokens in a night). Your state file keeps the continuity after each compact.
+- **Subagents default to Sonnet** instead of the main model. Pass a model explicitly when one piece really needs the big one.
+- **Three skills:** `/save`, `/yaad` and `/kharcha` (find what is eating your usage).
+
+The hooks are plain Node scripts. They read only the tail of the transcript, finish in under a second, and print nothing unless there is something to say. They cost **zero model tokens** except the short state they print at session start.
+
+---
+
+## Install
+
+You need **Node.js 18+** and **Claude Code**.
+
+```bash
+npx claude-yaad
+```
+
+Not on npm yet? Install straight from GitHub; it works the same:
+
+```bash
+npx github:rahmangamer12/claude-yaad
+```
+
+Then **restart Claude Code**. That's it.
+
+What the installer does:
+
+| | Where |
+|---|---|
+| Hook script `ck_state.js` | `~/.claude/scripts/` |
+| Skills `save`, `yaad`, `kharcha` | `~/.claude/skills/` (an older skill with the same name is moved to `~/.claude/skill-backups/`) |
+| Hooks: SessionStart, PreCompact, SessionEnd, UserPromptSubmit | `~/.claude/settings.json` (backed up first as `settings.json.bak-claude-kit-<time>`) |
+| `CLAUDE_CODE_AUTO_COMPACT_WINDOW=150k` | `env` in `~/.claude/settings.json`; skipped if you already set a window, or with `--keep-compact-window` |
+| `CLAUDE_CODE_SUBAGENT_MODEL=sonnet` | `env` in `~/.claude/settings.json`; skipped if you already set one, or with `--keep-subagent-model` |
+
+Your other hooks, settings and skills are left alone. Running it again updates the kit in place.
+
+### Options
+
+```bash
+npx claude-yaad --keep-subagent-model   # do not touch the subagent model
+npx claude-yaad --keep-compact-window   # do not touch the auto-compact window
+npx claude-yaad --zips                  # put the skill zips for claude.ai in the current folder
+npx claude-yaad --uninstall             # remove the hooks and the script (keeps skills and state)
+npx claude-yaad --uninstall --purge     # also remove the three skills
+```
+
+---
+
+## Daily use
+
+| You want to… | Do this |
+|---|---|
+| Stop for now, or `/clear` | `/save`, then `/clear`. Nothing is lost. |
+| Pick up where you left off | Just start. The state shows at the top of the session. Ask `/yaad` for a short summary. |
+| The hook says the context is heavy | Finish the current step, `/save`, `/clear`. |
+| Usage limit going too fast | `/kharcha`: it checks the usual culprits and fixes the safe ones. |
+
+### How the memory works
+
+One file per project: `~/.claude/state/projects/<project-slug>.md`. The slug is the working directory with every character that is not a letter or digit turned into `-`, e.g. `F:\Work\Shop Site` → `F--Work-Shop-Site.md`.
+
+The file has two parts:
+
+1. **Your part, written by `/save`:** what we are doing, key paths, done, next, the commands to run, and gotchas. 60 lines max.
+2. **The auto part, written by the hook** on every compact and session end: your last few requests, the files edited, and the last reply. It needs no model call, so it is free.
+
+Because every project has its own file, two Claude windows on two projects never overwrite each other's memory.
+
+### Settings you can change
+
+Set these as environment variables, or in `env` in `settings.json`:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `CK_WARN_TOKENS` | `200000` | Warn when the context passes this many tokens |
+| `CK_SHOW_CHARS` | `3500` | How much of the state file to show at session start |
+
+---
+
+## claude.ai (web) and the Claude desktop app
+
+Chat on claude.ai and in the desktop app has no hooks and no lasting disk, so only the skills apply there:
+
+1. `npx claude-yaad --zips` puts `save.zip`, `yaad.zip` and `kharcha.zip` in your folder. They are also in the [`claude-ai/`](claude-ai) folder of this repo.
+2. claude.ai → **Settings → Capabilities → Skills → Upload skill**, one zip at a time.
+3. In chat, `/save` prints a state block. Paste it into your **Project instructions** (or the first message of the next chat), and `/yaad` reads it from there.
+
+The **Claude Code tab** of the desktop app and the IDE extensions use the same `~/.claude` folder as the terminal, so the full kit works there after the normal install.
+
+---
+
+## Why this saves usage
+
+- The biggest cost is **context length × number of messages**. A 400k-token session costs about 10× a 40k one *per message*. Cheap memory makes `/clear` painless, so you clear more.
+- **Subagents are full extra sessions.** Running them on Sonnet by default cuts their cost a lot. Your main session keeps the model you chose.
+- Older autosave hooks parsed the whole transcript, which can be hundreds of MB, and wrote one global file that every window overwrote. This reads the last 3 MB and keeps one file per project.
+
+## Uninstall
+
+```bash
+npx claude-yaad --uninstall --purge
+```
+
+Your state files in `~/.claude/state/projects/` are kept. Delete them by hand if you want.
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// claude-yaad installer: npx claude-yaad            -> install / update
+//                       npx claude-yaad --uninstall -> remove hooks + kit files (skills kept unless --purge)
+//                       npx claude-yaad --zips      -> copy claude.ai skill zips to the current folder
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const CLAUDE = path.join(os.homedir(), '.claude');
+const SETTINGS = path.join(CLAUDE, 'settings.json');
+const SCRIPT = path.join(CLAUDE, 'scripts', 'ck_state.js');
+const SKILLS = ['save', 'yaad', 'kharcha'];
+const args = process.argv.slice(2);
+const has = (f) => args.includes(f);
+const log = (s) => console.log('  ' + s);
+
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, e.name), d = path.join(dst, e.name);
+    e.isDirectory() ? copyDir(s, d) : fs.copyFileSync(s, d);
+  }
+}
+function readSettings() {
+  try { return JSON.parse(fs.readFileSync(SETTINGS, 'utf8')); } catch (e) {
+    if (fs.existsSync(SETTINGS)) { console.error('settings.json is not valid JSON; fix it first: ' + SETTINGS); process.exit(1); }
+    return {};
+  }
+}
+function backup() {
+  if (!fs.existsSync(SETTINGS)) return;
+  const b = SETTINGS + '.bak-claude-kit-' + Date.now();
+  fs.copyFileSync(SETTINGS, b);
+  log('backup: ' + b);
+}
+const cmd = () => `node "${SCRIPT.replace(/\\/g, '/')}"`;
+// Old hooks this kit replaces (the earlier python autosave and the global CURRENT.md loader).
+const isOurs = (h) => /ck_state\.js|autosave\.py|state\/CURRENT\.md|state\\CURRENT\.md/.test((h && h.command) || '');
+
+function stripOurs(s) {
+  for (const ev of Object.keys(s.hooks || {})) {
+    s.hooks[ev] = s.hooks[ev]
+      .map((g) => ({ ...g, hooks: (g.hooks || []).filter((h) => !isOurs(h)) }))
+      .filter((g) => g.hooks.length);
+    if (!s.hooks[ev].length) delete s.hooks[ev];
+  }
+}
+function addHook(s, ev, matcher, timeout) {
+  s.hooks = s.hooks || {};
+  s.hooks[ev] = s.hooks[ev] || [];
+  const g = { hooks: [{ type: 'command', command: cmd(), timeout }] };
+  if (matcher) g.matcher = matcher;
+  s.hooks[ev].unshift(g);
+}
+
+if (has('--zips')) {
+  const src = path.join(ROOT, 'claude-ai');
+  for (const f of fs.readdirSync(src)) fs.copyFileSync(path.join(src, f), path.join(process.cwd(), f));
+  console.log('Skill zips copied here. claude.ai → Settings → Capabilities → Skills → Upload skill (one zip at a time).');
+  process.exit(0);
+}
+
+if (has('--uninstall')) {
+  const s = readSettings(); backup(); stripOurs(s);
+  if (s.env && s.env.CLAUDE_CODE_SUBAGENT_MODEL === 'sonnet') delete s.env.CLAUDE_CODE_SUBAGENT_MODEL;
+  if (s.env && s.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW === '150k') delete s.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW;
+  fs.writeFileSync(SETTINGS, JSON.stringify(s, null, 2));
+  try { fs.unlinkSync(SCRIPT); } catch {}
+  if (has('--purge')) for (const k of SKILLS) fs.rmSync(path.join(CLAUDE, 'skills', k), { recursive: true, force: true });
+  console.log('claude-kit removed. Your state files in ~/.claude/state/projects are kept.');
+  process.exit(0);
+}
+
+console.log('claude-kit: installing into ' + CLAUDE);
+copyDir(path.join(ROOT, 'kit', 'scripts'), path.join(CLAUDE, 'scripts'));
+log('hook script: ' + SCRIPT);
+for (const k of SKILLS) {
+  const dst = path.join(CLAUDE, 'skills', k);
+  if (fs.existsSync(dst) && !has('--force')) {
+    const old = path.join(CLAUDE, 'skill-backups', k + '-' + Date.now());
+    fs.mkdirSync(path.dirname(old), { recursive: true });
+    fs.renameSync(dst, old);
+    log(`skill ${k}: previous version kept at ${old}`);
+  }
+  copyDir(path.join(ROOT, 'kit', 'skills', k), dst);
+  log('skill: /' + k);
+}
+const s = readSettings(); backup(); stripOurs(s);
+addHook(s, 'SessionStart', 'startup|clear|compact|resume', 10);
+addHook(s, 'PreCompact', 'auto|manual', 20);
+addHook(s, 'SessionEnd', null, 20);
+addHook(s, 'UserPromptSubmit', null, 10);
+s.env = s.env || {};
+if (!has('--keep-subagent-model') && !s.env.CLAUDE_CODE_SUBAGENT_MODEL) {
+  s.env.CLAUDE_CODE_SUBAGENT_MODEL = 'sonnet';
+  log('subagents default to Sonnet (pass a model explicitly for hard work)');
+}
+if (!has('--keep-compact-window') && !s.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW && !s.autoCompactWindow) {
+  s.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = '150k';
+  log('auto-compact window 150k: sessions never grow huge, so every message stays cheap');
+}
+fs.mkdirSync(CLAUDE, { recursive: true });
+fs.writeFileSync(SETTINGS, JSON.stringify(s, null, 2));
+log('hooks: SessionStart, PreCompact, SessionEnd, UserPromptSubmit');
+console.log('\nDone. Restart Claude Code. Use /save before /clear, /yaad to pick up, /kharcha to find waste.');
+console.log('claude.ai web / Claude desktop chat: run  npx claude-yaad --zips  and upload the zips there.');

package/kit/scripts/ck_state.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// claude-kit: zero-token session memory for Claude Code.
+// One state file per project: ~/.claude/state/projects/<project-slug>.md
+//   SessionStart      -> prints that file (capped) so a fresh session knows where we were
+//   PreCompact/SessionEnd -> rewrites only the AUTO part (last asks, files touched, last reply)
+//   UserPromptSubmit  -> one-line warning when the context is getting expensive
+// It reads only the tail of the transcript, so it stays fast on 200 MB transcripts.
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const HOME = os.homedir();
+const DIR = path.join(HOME, '.claude', 'state', 'projects');
+const MARK = '<!-- AUTO: written by claude-kit hook, everything below is replaced -->';
+const WARN = parseInt(process.env.CK_WARN_TOKENS || '200000', 10);
+const SHOW = parseInt(process.env.CK_SHOW_CHARS || '3500', 10);
+const TAIL = 3 * 1024 * 1024;
+
+function readStdin() {
+  try { return JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { return {}; }
+}
+const slug = (p) => String(p || process.cwd()).replace(/[^A-Za-z0-9]/g, '-');
+const stamp = () => {
+  const d = new Date(), z = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${z(d.getMonth() + 1)}-${z(d.getDate())} ${z(d.getHours())}:${z(d.getMinutes())}`;
+};
+
+function tailLines(file) {
+  try {
+    const size = fs.statSync(file).size;
+    const len = Math.min(size, TAIL);
+    const fd = fs.openSync(file, 'r');
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, size - len);
+    fs.closeSync(fd);
+    const lines = buf.toString('utf8').split('\n');
+    if (size > len) lines.shift(); // first line is probably cut
+    return lines;
+  } catch { return []; }
+}
+
+function parse(lines) {
+  const asks = [], replies = [], files = [];
+  let tokens = 0;
+  for (const raw of lines) {
+    let m; try { m = JSON.parse(raw); } catch { continue; }
+    const msg = m.message || {};
+    if (msg.usage) {
+      const u = msg.usage;
+      tokens = (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0);
+    }
+    const c = msg.content;
+    if (m.type === 'user' && !m.isMeta) {
+      let t = typeof c === 'string' ? c
+        : Array.isArray(c) && !c.some((x) => x && x.type === 'tool_result')
+          ? c.filter((x) => x && x.type === 'text').map((x) => x.text).join(' ') : '';
+      t = (t || '').trim();
+      if (t && !t.startsWith('<') && !t.startsWith('[Request interrupted') && !t.startsWith('Caveat:'))
+        asks.push(t.replace(/\s+/g, ' ').slice(0, 280));
+    } else if (m.type === 'assistant' && Array.isArray(c)) {
+      for (const x of c) {
+        if (x && x.type === 'text' && x.text && x.text.trim()) replies.push(x.text.trim());
+        if (x && x.type === 'tool_use' && /^(Write|Edit|MultiEdit|NotebookEdit)$/.test(x.name) && x.input) {
+          const f = x.input.file_path || x.input.notebook_path;
+          if (f) { const i = files.indexOf(f); if (i >= 0) files.splice(i, 1); files.push(f); }
+        }
+      }
+    }
+  }
+  return { asks, replies, files, tokens };
+}
+
+function stateFile(cwd) {
+  fs.mkdirSync(DIR, { recursive: true });
+  return path.join(DIR, slug(cwd) + '.md');
+}
+
+const d = readStdin();
+const ev = d.hook_event_name || process.argv[2] || '';
+const cwd = d.cwd || process.cwd();
+const file = stateFile(cwd);
+
+if (ev === 'SessionStart') {
+  let txt = '';
+  try { txt = fs.readFileSync(file, 'utf8'); } catch {}
+  console.log(`[claude-kit] Is project ki state file: ${file}`);
+  console.log('/save isi file ka upar wala hissa likhta hai; /yaad isi ko padhta hai.');
+  if (txt.trim()) {
+    console.log('=== Pichli dafa kahan the ===');
+    console.log(txt.length > SHOW ? txt.slice(0, SHOW) + '\n…(baqi file mein)' : txt);
+  }
+  process.exit(0);
+}
+
+const lines = d.transcript_path ? tailLines(d.transcript_path) : [];
+
+if (ev === 'UserPromptSubmit') {
+  const { tokens } = parse(lines.slice(-400));
+  if (tokens > WARN)
+    console.log(`[claude-kit] Context ~${Math.round(tokens / 1000)}k tokens: har message mehnga ho raha hai. Ye kaam khatam kar ke /save phir /clear karo (state yaad rahegi).`);
+  process.exit(0);
+}
+
+if (ev === 'PreCompact' || ev === 'SessionEnd' || ev === 'Stop') {
+  const { asks, replies, files } = parse(lines);
+  if (!asks.length && !replies.length) process.exit(0);
+  let hand = '';
+  try { hand = fs.readFileSync(file, 'utf8').split(MARK)[0].trimEnd(); } catch {}
+  const last = (replies[replies.length - 1] || '').slice(0, 1200);
+  const auto = [
+    MARK,
+    `## Auto — ${stamp()} (${ev})`,
+    'Last asks:',
+    ...asks.slice(-4).map((a) => '- ' + a),
+    files.length ? 'Files touched:' : '',
+    ...files.slice(-12).map((f) => '- ' + f),
+    'Last reply:',
+    last,
+  ].filter((l) => l !== '').join('\n');
+  fs.writeFileSync(file, (hand ? hand + '\n\n' : '') + auto + '\n');
+  try {
+    fs.appendFileSync(path.join(HOME, '.claude', 'state', 'LOG.md'), `- ${stamp()}: auto-save ${ev} → ${path.basename(file)}\n`);
+  } catch {}
+}
+process.exit(0);

package/kit/skills/kharcha/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: kharcha
+description: Tokens ka kharcha kahan ja raha hai — find and fix what is eating usage and the context window. Use when the user says usage zyada hai, weekly limit khatam ho rahi hai, tokens bach jayein, kharcha zyada hai, context bhar gaya, kaunsa MCP band karun, or hits a compact.
+---
+
+# /kharcha — cut the fixed cost, not the useful work
+
+Measure before prescribing. A fix that saves nothing still costs the user something.
+
+## 1. The big four (check these first — they are usually 90% of the bill)
+1. **Long sessions.** Every message re-sends the whole context. A 400k-token session costs ~10x a 40k one *per message*. Fix: `/save` then `/clear` between unrelated jobs; one session per project. The claude-kit hook warns when the context passes ~200k.
+2. **Parallel workers and subagents.** Each background session or Agent is a full extra context. Fix: stop finished workers; no Agent/Explore for anything a `grep` answers; run subagents on a smaller model (`CLAUDE_CODE_SUBAGENT_MODEL=sonnet` in settings `env`, already set by claude-kit) and pass a bigger model only for the hard piece.
+3. **Model and effort.** Opus/Fable at high effort for routine edits is the most expensive habit. Use Sonnet for normal coding, Haiku for mechanical work, `/model` to switch; keep effort medium for routine work.
+4. **Screenshots and big tool output.** An image costs more than a page of text; a 2,000-line log dump stays in context forever. Cap output with `head`/`tail`; take a screenshot only when you will act on it.
+
+## 2. MCP servers — check whether they are deferred
+Run `/context`. If MCP tools show as **deferred**, only their names are loaded: disabling servers saves almost nothing, so say so and do not push a cleanup. If they are **loaded** (tens of thousands of tokens): delete dead servers (`claude mcp remove <name>`), scope servers to the project that needs them, prefer a CLI (`gh`, `curl`, `ffmpeg`) over an MCP server. Always name a server and ask before removing it.
+
+## 3. Things that reload every turn
+CLAUDE.md, MEMORY.md, and any hook that prints text on every prompt. Keep them short; a hook should print only when it has something to say.
+
+## Reporting
+A table: item · what it costs · fix · worth doing (yes/no). Then do the safe fixes, and ask before removing any server, skill or worker.

package/kit/skills/save/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: save
+description: Kaam ka state save karo taake /clear, compact ya band karne par kuch na khoye. Use when the user says save karo, clear karne laga hoon, band kar raha hoon, yaad rakho kahan the, handoff, bas aaj ke liye — and proactively when a piece of work reaches a natural stopping point, before a long or risky operation, or when a hook says the context is getting heavy.
+---
+
+# /save — freeze this project's state in one small file
+
+## Where to write
+
+**Claude Code (terminal / desktop / IDE):** the project's own state file. The SessionStart hook prints its path at the top of every session ("Is project ki state file: …"). If you cannot see it, build it yourself:
+`~/.claude/state/projects/<slug>.md`, where `<slug>` is the working directory with every non-letter/digit replaced by `-`
+(e.g. `F:\Work\Shop Site` → `F--Work-Shop-Site.md`).
+
+The file has two parts:
+- **Top part (yours):** everything above the line `<!-- AUTO: written by claude-kit hook ... -->`. Replace it completely each time.
+- **Auto part (the hook's):** that marker line and everything below it. Never edit it, and keep it in place: the hook rewrites it on its own.
+If the file does not exist, just write the top part.
+
+**claude.ai web / Claude desktop chat (no file system that survives):** do not write a file. Print the same block in a code box and tell the user: "Ye block Project ke instructions/knowledge mein paste kar do, ya naye chat ke pehle message mein." That is the only memory that survives there.
+
+## What goes in (60 lines maximum, hard cap)
+
+Use these headings. Skip an empty heading entirely.
+
+```markdown
+# State — <YYYY-MM-DD HH:MM>
+## Doing
+<one line: the task, for whom>
+## Where
+<absolute paths that matter, one per line, max 5>
+## Done
+<finished things, one line each, newest last>
+## Next
+<the next action, written so it can start without asking anything>
+## Run
+<exact commands to build / test / render>
+## Gotchas
+<only things that already bit us: a flag, a path, a thing not to touch>
+```
+
+## Rules
+- Facts, not story. Absolute paths. Next must be doable without a question.
+- Long-lived facts (a client's rules, how a tool works) belong in memory, not here.
+- Trim: drop finished items nobody will need again; cut the oldest Done lines first.
+
+After writing, tell the user in one line that it is saved and `/clear` is safe. Do not print the file back.

package/kit/skills/yaad/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: yaad
+description: Yaad karo hum kahan the — restore working context cheaply after a /clear, a compact, a crash or a new day. Answers kahan the hum, aaj kya kiya tha, continue karo, where were we, what was I doing. Reads one small file and stops. Use instead of searching the disk to rebuild context.
+---
+
+# /yaad — get oriented for the fewest tokens possible
+
+The point of this skill is to **stop early**.
+
+## Step 1 — the state is probably already in context
+In Claude Code the SessionStart hook already printed this project's state ("=== Pichli dafa kahan the ==="). If you can see it, answer from it: 3-6 lines on what we were doing, what is done, what is next. Then ask whether to continue. Open nothing.
+
+## Step 2 — read the file once
+If it is not in context, read `~/.claude/state/projects/<slug>.md` (`<slug>` = working directory with every non-letter/digit replaced by `-`). Top part = the last /save; the AUTO part = the hook's note of the last asks, files touched and last reply. Answer from it and stop.
+
+## Step 3 — only if the file is missing or stale (older than ~2 days)
+Stop at the first one that answers:
+1. The last lines of `~/.claude/state/LOG.md`.
+2. The 15 newest files in the working directory (`ls -lt | head -15`).
+
+**Never** run a repo-wide grep, a recursive find, or an Agent/Explore search to answer "where were we". That costs more than the conversation you lost.
+
+## claude.ai web / Claude desktop chat
+There is no state file. Look for a "# State —" block in the Project instructions/knowledge or the first message, and answer from it. If there is none, say so in one line and ask the user to paste their last /save block.
+
+## Then
+If the state was missing or wrong, write a fresh one with /save before starting work.

package/package.json

@@ -1,6 +1,34 @@
-{
-  "name": "claude-yaad",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+{
+  "name": "claude-yaad",
+  "version": "1.0.1",
+  "description": "Zero-token session memory and usage savers for Claude Code: per-project state that survives /clear and compaction, /save /yaad /kharcha skills, context-size warning, Sonnet subagents.",
+  "bin": {
+    "claude-yaad": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "kit",
+    "claude-ai",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skills",
+    "hooks",
+    "tokens"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rahmangamer12/claude-yaad.git"
+  },
+  "homepage": "https://github.com/rahmangamer12/claude-yaad#readme",
+  "bugs": {
+    "url": "https://github.com/rahmangamer12/claude-yaad/issues"
+  }
 }