toldya 0.0.1 → 0.1.0

package/README.md

@@ -1,26 +1,80 @@
-# toldya
+<p align="center"><img src="assets/mark.webp" width="220" height="220" alt="A round green figure sits against a wall covered in chalk tally marks, adding one more, looking straight at you."></p>
 
-**Stop repeating yourself to your AI.**
+<h1 align="center">toldya</h1>
 
-You keep telling your coding agent the same things. "Don't create a new file." "Use pnpm."
-"Run the tests before you say it's done." toldya finds what you keep repeating, writes it into
-the rule file your agent reads (`CLAUDE.md` / `AGENTS.md`), then counts whether it stopped.
+<p align="center"><b>Stop repeating yourself to your AI.</b></p>
 
-## Status
+<p align="center">
+  <a href="https://www.npmjs.com/package/toldya"><img src="https://img.shields.io/npm/v/toldya?color=ffd23f&label=npm" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/dependencies-0-98a179" alt="zero dependencies">
+  <img src="https://img.shields.io/badge/network-none-98a179" alt="no network calls">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-ff90e8" alt="MIT"></a>
+</p>
 
-`0.0.1` reserves the name and does nothing else: it prints what's coming, reads nothing and
-writes nothing. **v0.1** is being built.
+<p align="center"><img src="assets/demo.gif" width="100%" alt="toldya reading Claude Code history, listing the corrections said most often, then adding three of them to CLAUDE.md"></p>
 
-## Planned for v0.1
+```bash
+npx toldya --all
+```
 
-- **Solo mode:** `npx toldya` reads your local Claude Code and Codex history, finds the corrections
-  you repeat, and offers lines for `CLAUDE.md`. You approve each one. Nothing leaves your machine.
-- **Team mode:** `npx toldya owner/repo` reads a repo's pull-request review comments (from people
-  or any review bot), finds the repeats, and opens one PR adding them to `AGENTS.md`.
-- **Count:** next run shows how often each repeat came back after the rule was added.
+You keep telling your coding agent the same things. "Keep it simple." "Don't assume."
+"Don't complicate it." toldya reads what you typed to Claude Code, finds what you keep
+repeating, and writes it into the rule file your agent reads, with your yes. Next time,
+it counts whether you still had to say it.
 
-No account. No telemetry.
+## What it found on the author's own history
+
+A real run. Not a mock-up.
+
+<p align="center"><img src="assets/report.png" width="100%" alt="toldya report: keep it simple 40 times in 36 sessions, dont complex this 29 times, dont assume 15 times, and 71 times it was told to try or check again"></p>
+
+142 sessions. "Keep it simple" 40 times. Rewordings and typos count as one habit: "Don't
+complicate it" and "dont complex this" are the same thing said twice.
+
+## Use it
+
+```bash
+npx toldya                  # this project: offers rules for ./CLAUDE.md
+npx toldya --all            # every project: offers rules for ~/.claude/CLAUDE.md
+npx toldya --dry            # report only, change nothing
+npx toldya --to AGENTS.md   # write rules somewhere else
+npx toldya --add 1,3        # take repeats 1 and 3 without the prompts
+npx toldya --min 5          # only things you said 5+ times
+npx toldya --json           # machine-readable report
+```
+
+Without `--dry` or `--add`, it asks about each repeat: **y** adds it, **n** skips it,
+**e** lets you reword it first. Rules go under a `## Things I kept repeating` heading.
+Nothing is written without a yes.
+
+Run it again a week later and every rule it added shows how often you said it before,
+and how often since.
+
+## What it reads, and what it doesn't
+
+- Only **your own messages** in Claude Code's history on this machine (`~/.claude/projects`).
+  Not the AI's replies, not tool output, not your files.
+- Long messages are treated as pastes (briefs, logs) and skipped. Questions and "I don't
+  understand" are not corrections, so they're skipped too.
+- A repeat counts only if it shows up in **at least two sessions**.
+- Short "try again" / "check again" messages are counted separately. They mean the first
+  attempt missed, but they aren't rules you can write down.
+- **Sends nothing anywhere.** No account, no telemetry, no network calls.
+
+Claude Code keeps about 30 days of history by default, so on a default install toldya sees
+roughly a month.
+
+## Coming next
+
+- **Team mode:** `npx toldya owner/repo` reads a repo's pull-request review comments (from
+  people or any review bot), finds what reviewers keep writing, and opens one PR into `AGENTS.md`.
+- **A share card:** one image of your top repeats, for when you want to show someone.
+- Codex history (not tested on real files yet, so not claimed).
+
+## Requirements
+
+Node 18+. No dependencies.
 
 ## License
 
-MIT © Sevenopt Solutions Private Limited (Singh Labs)
+MIT © Sevenopt Solutions Private Limited · made by [Singh Labs](https://singhlabs.dev)

package/bin/toldya.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// toldya — stop repeating yourself to your AI.
+//
+// Reads what you typed to Claude Code (from its own history on this machine),
+// finds the corrections you keep repeating, offers each one as a line for the
+// rule file your agent reads, and next time counts whether you still say it.
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import {
+  CLAUDE_ROOT, claudeProjects, projectFor, readClaudeSession,
+  corrections, group, repeats, toRule, alreadyWritten, beforeAfter, isRetry,
+} from '../lib/core.mjs';
+
+const VERSION = '0.1.0';
+const argv = process.argv.slice(2);
+const has = (f) => argv.includes(f);
+const opt = (f, d) => { const i = argv.indexOf(f); return i >= 0 && argv[i + 1] ? argv[i + 1] : d; };
+
+if (has('--help') || has('-h')) {
+  console.log(`toldya ${VERSION} — stop repeating yourself to your AI
+
+  toldya            this project: what you keep telling Claude Code here
+  toldya --all      every project; rules go to your global ~/.claude/CLAUDE.md
+  --min N           only repeats said at least N times (default 3)
+  --to FILE         write rules to FILE instead (e.g. AGENTS.md)
+  --add 1,3         add repeats by their number, without asking
+  --dry             show the report, change nothing
+  --json            machine-readable report, change nothing
+
+Reads Claude Code's own history on this machine. Sends nothing anywhere.`);
+  process.exit(0);
+}
+if (has('--version') || has('-v')) { console.log(VERSION); process.exit(0); }
+if (argv.some((a) => /^[\w.-]+\/[\w.-]+$/.test(a))) {
+  console.log('Team mode (owner/repo) is coming next. For now: run `npx toldya` in your project.');
+  process.exit(0);
+}
+
+const all = has('--all');
+const min = Math.max(2, parseInt(opt('--min', '3'), 10) || 3);
+const cwd = process.cwd();
+const projects = claudeProjects();
+const chosen = all ? projects : [projectFor(cwd, projects)].filter(Boolean);
+
+if (!chosen.length) {
+  console.log(projects.length
+    ? `No Claude Code history for this folder (${cwd}).\nRun it inside a project you've used Claude Code in, or try: npx toldya --all`
+    : `No Claude Code history found at ${CLAUDE_ROOT}.`);
+  process.exit(0);
+}
+
+// Everything you typed, stamped with the session it came from.
+const messages = [];
+let sessions = 0;
+for (const p of chosen) {
+  const dir = join(CLAUDE_ROOT, p);
+  for (const f of readdirSync(dir).filter((x) => x.endsWith('.jsonl'))) {
+    const ms = readClaudeSession(join(dir, f));
+    if (ms.length) sessions++;
+    for (const m of ms) messages.push({ ...m, session: `${p}/${f}` });
+  }
+}
+const said = corrections(messages);
+const retries = said.filter((i) => isRetry(i.s)).length;
+const items = said.filter((i) => !isRetry(i.s));
+const found = repeats(group(items), min);
+
+// Where rules go, and what's already written there.
+const target = resolve(opt('--to', all ? join(homedir(), '.claude', 'CLAUDE.md') : join(cwd, 'CLAUDE.md')));
+const ruleFiles = [...new Set(all ? [target] : [target, join(cwd, 'CLAUDE.md'), join(cwd, 'AGENTS.md')])];
+const written = ruleFiles.filter(existsSync).map((f) => readFileSync(f, 'utf8')).join('\n');
+
+// Rules toldya added before, so we can count whether they worked.
+const stateDir = join(homedir(), '.toldya');
+const stateFile = join(stateDir, 'state.json');
+// Rules are remembered per rule file: that's where they live.
+const key = target;
+let state = {};
+try { state = JSON.parse(readFileSync(stateFile, 'utf8')); } catch {}
+const ours = state[key]?.rules || [];
+
+const dates = messages.map((m) => m.ts).filter(Boolean).sort();
+const day = (t) => (t ? new Date(t).toLocaleDateString('en-GB', { day: 'numeric', month: 'short' }) : '?');
+
+if (has('--json')) {
+  console.log(JSON.stringify({
+    sessions, messages: messages.length, corrections: items.length, retries,
+    from: dates[0] || null, to: dates.at(-1) || null,
+    repeats: found.map((r) => ({ phrase: r.phrase, count: r.count, sessions: r.sessions,
+      alreadyWritten: alreadyWritten(r.phrase, written) })),
+    rules: ours.map((r) => ({ ...r, ...beforeAfter(r, items) })),
+  }, null, 2));
+  process.exit(0);
+}
+
+console.log(`\ntoldya · ${sessions} sessions (${day(dates[0])} – ${day(dates.at(-1))}) · ${messages.length} of your messages · ${items.length} corrections\n`);
+
+if (ours.length) {
+  console.log('Rules toldya added earlier:');
+  for (const r of ours) {
+    const { before, after } = beforeAfter(r, items);
+    console.log(`  "${r.text}"  said ${before}× before · ${after}× since (added ${day(r.addedAt)})`);
+  }
+  console.log('');
+}
+
+const fresh = found.filter((r) => !ours.some((o) => o.text === toRule(r.phrase)));
+if (!fresh.length) {
+  console.log(found.length ? 'Nothing new you keep repeating. Nice.' : `No correction said ${min}+ times across sessions yet.`);
+  process.exit(0);
+}
+
+console.log('You keep telling your AI:');
+const shown = fresh.slice(0, 10);
+shown.forEach((r, n) => {
+  const note = alreadyWritten(r.phrase, written) ? '   ← already in your rules, still repeated' : '';
+  console.log(`  ${String(n + 1).padStart(2)}. ${String(r.count).padStart(3)}×  ${r.phrase}   (${r.sessions} sessions)${note}`);
+});
+if (retries >= min) console.log(`\nAnd ${retries} times you told it to try or check again: its first go missed.`);
+const spanDays = dates.length ? (new Date(dates.at(-1)) - new Date(dates[0])) / 864e5 : 0;
+if (spanDays < 35) console.log('\nClaude Code keeps about 30 days of history by default, so older repeats are not counted.');
+
+const picks = opt('--add', null);
+if (has('--dry') || (!picks && !process.stdin.isTTY)) {
+  if (!has('--dry')) console.log('\nRun in a terminal to add these as rules, or pick them with --add 1,3.');
+  process.exit(0);
+}
+
+// Ask before touching any file (or take the numbers given). Each rule is your own words.
+const add = [];
+if (picks) {
+  for (const n of String(picks).split(',').map((x) => parseInt(x, 10))) {
+    const r = shown[n - 1];
+    if (r && !alreadyWritten(r.phrase, written)) add.push(toRule(r.phrase));
+  }
+} else {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  console.log(`\nAdd them to ${target}? For each: y = add, n = skip, e = edit the wording.\n`);
+  for (const r of shown) {
+    if (alreadyWritten(r.phrase, written)) continue;
+    let text = toRule(r.phrase);
+    const a = (await rl.question(`  ${text}  [y/n/e] `)).trim().toLowerCase();
+    if (a === 'e') text = toRule((await rl.question('    new wording: ')).trim() || r.phrase);
+    if (a === 'y' || a === 'e') add.push(text);
+  }
+  rl.close();
+}
+
+if (!add.length) { console.log('\nNothing added.'); process.exit(0); }
+
+const heading = '## Things I kept repeating';
+let doc = existsSync(target) ? readFileSync(target, 'utf8') : '';
+const block = add.map((t) => `- ${t}`).join('\n');
+if (doc.includes(heading)) doc = doc.replace(heading, `${heading}\n${block}`);
+else doc = `${doc.replace(/\s*$/, '')}${doc ? '\n\n' : ''}${heading}\n${block}\n`;
+mkdirSync(join(target, '..'), { recursive: true });
+writeFileSync(target, doc);
+
+const now = new Date().toISOString();
+state[key] = { rules: [...ours, ...add.map((text) => ({ text, addedAt: now }))] };
+mkdirSync(stateDir, { recursive: true });
+writeFileSync(stateFile, JSON.stringify(state, null, 2));
+const shortTarget = target.startsWith(cwd) ? target.slice(cwd.length + 1) : target.replace(homedir(), '~');
+console.log(`\nAdded ${add.length} rule${add.length > 1 ? 's' : ''} to ${shortTarget}. Run toldya again in a week to see if they stuck.`);

package/lib/core.mjs

@@ -0,0 +1,171 @@
+// toldya core: read what you told your AI, find what you keep repeating.
+// No dependencies, no network. Everything here runs on your machine.
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export const CLAUDE_ROOT = join(homedir(), '.claude', 'projects');
+
+// Claude Code stores D:\My work\app as D--My-work-app: every non-alphanumeric
+// character becomes one dash, never collapsed.
+export const encodeProject = (dir) => dir.replace(/[^A-Za-z0-9]/g, '-');
+
+export function claudeProjects(root = CLAUDE_ROOT) {
+  if (!existsSync(root)) return [];
+  return readdirSync(root).filter((d) => {
+    try { return statSync(join(root, d)).isDirectory(); } catch { return false; }
+  });
+}
+
+// The project folder for this directory: longest matching prefix, so running
+// from a subfolder still finds the project it belongs to.
+export function projectFor(cwd, all) {
+  const want = encodeProject(cwd).toLowerCase();
+  return all.filter((d) => want.startsWith(d.toLowerCase()))
+    .sort((a, b) => b.length - a.length)[0] || null;
+}
+
+// Messages you typed, from one transcript. Skips tool results, system notes,
+// compaction summaries and slash-command output: only your own words count.
+export function readClaudeSession(file) {
+  let lines;
+  try { lines = readFileSync(file, 'utf8').split('\n'); } catch { return []; }
+  const out = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    if (e.type !== 'user' || e.isMeta || e.isCompactSummary || e.toolUseResult) continue;
+    let c = e.message?.content;
+    if (Array.isArray(c)) c = c.filter((b) => b.type === 'text').map((b) => b.text).join('\n');
+    if (typeof c !== 'string' || !c.trim()) continue;
+    if (/^\s*</.test(c) || /\[Request interrupted/.test(c)) continue;
+    out.push({ text: c, ts: e.timestamp || '' });
+  }
+  return out;
+}
+
+// A correction is a short instruction aimed at the agent's behaviour.
+const CUE = /\b(don'?t|dont|do not|never|stop|always|avoid|instead|i told you|i said|again|not like that|why did you|make sure|keep it|no need|must)\b/i;
+// Not corrections: you being lost, or asking something.
+const NOT = /\bunde\w*t[ae]?n|\bunders\w*|\b(don'?t know|dont know|no idea|what is|where is|how do|how to|where to)\b|\?\s*$/i;
+// Long messages are pastes (specs, logs, briefs), not things you said.
+const PASTE = 600;
+
+// "Try again", "check again", "so try again": short sentences built on "again"
+// are retries, not rules. They mean the first attempt missed. Counted
+// separately, never offered as a rule.
+export const isRetry = (s) => s.split(' ').length <= 5 && /\bagain\b/i.test(s);
+
+export function corrections(messages) {
+  const out = [];
+  for (const m of messages) {
+    if (m.text.length > PASTE) continue;
+    for (let s of m.text.split(/(?<=[.!?])\s+|\n+|\.{2,}|,{2,}/)) {
+      s = s.trim().replace(/\s+/g, ' ');
+      const words = s.split(' ').length;
+      if (words < 2 || words > 16) continue;
+      if (/https?:|\]\(|`/.test(s)) continue;
+      if (!CUE.test(s) || NOT.test(s)) continue;
+      out.push({ ...m, s });
+    }
+  }
+  return out;
+}
+
+const STOP = new Set("the a an to of and or is it i you me my we our this that for in on with be its it's please just so also now ok okay".split(' '));
+// Words cut to their first five letters, so "complex" and "complicate",
+// "simple" and "simpler", count as the same word.
+const tokens = (s) => new Set((s.toLowerCase().match(/[a-z0-9']+/g) || [])
+  .map((w) => w.replace(/'/g, '')).filter((w) => w.length > 1 && !STOP.has(w))
+  .map((w) => w.slice(0, 5)));
+const grams = (s) => {
+  const t = s.toLowerCase().replace(/[^a-z0-9 ]/g, '');
+  const g = new Set();
+  for (let i = 0; i + 3 <= t.length; i++) g.add(t.slice(i, i + 3));
+  return g;
+};
+const inter = (a, b) => { let n = 0; for (const x of a) if (b.has(x)) n++; return n; };
+
+// Same thing said twice? Word overlap catches rewordings, letter trigrams catch
+// typos ("dont comlicate that" vs "don't complicate it").
+export function similar(a, b) {
+  const ta = a.t || tokens(a.s || a), tb = b.t || tokens(b.s || b);
+  const ga = a.g || grams(a.s || a), gb = b.g || grams(b.s || b);
+  const j = inter(ta, tb) / Math.max(1, new Set([...ta, ...tb]).size);
+  const d = (2 * inter(ga, gb)) / Math.max(1, ga.size + gb.size);
+  return Math.max(j, d);
+}
+export const SAME = 0.5;
+
+// Greedy grouping against each group's first sentence. ponytail: O(n·groups);
+// fine for a few thousand corrections, swap for an index if histories get huge.
+export function group(items) {
+  const groups = [];
+  for (const it of items) {
+    const x = { ...it, t: tokens(it.s), g: grams(it.s) };
+    let best = null, score = 0;
+    for (const grp of groups) {
+      const sc = similar(grp.rep, x);
+      if (sc > score) { score = sc; best = grp; }
+    }
+    if (best && score >= SAME) best.items.push(x);
+    else groups.push({ rep: x, items: [x] });
+  }
+  return groups;
+}
+
+// The wording made of the words you used most across a group, so a one-off
+// typo ("pleae keep it simle") loses to the version you usually type.
+function typical(items) {
+  const freq = new Map();
+  for (const i of items) for (const w of i.t) freq.set(w, (freq.get(w) || 0) + 1);
+  const score = (i) => [...i.t].reduce((n, w) => n + freq.get(w), 0) / Math.max(1, i.t.size);
+  return [...items].sort((a, b) => score(b) - score(a) || a.s.length - b.s.length)[0];
+}
+
+// Repeats worth a rule: said at least `min` times, in at least two sessions.
+export function repeats(groups, min = 3) {
+  // Greedy grouping can split one habit in two ("Don't complicate it" formed
+  // before "dont complex this" arrived). Merge groups whose best wordings match.
+  const merged = [];
+  for (const g of [...groups].sort((a, b) => b.items.length - a.items.length)) {
+    const home = merged.find((m) => similar(typical(m.items), typical(g.items)) >= SAME);
+    if (home) home.items.push(...g.items); else merged.push({ items: [...g.items] });
+  }
+  return merged
+    .filter((g) => g.items.length >= min && new Set(g.items.map((i) => i.session)).size >= 2)
+    .map((g) => {
+      const phrase = typical(g.items).s.replace(/[.!]+$/, '');
+      return {
+        phrase,
+        count: g.items.length,
+        sessions: new Set(g.items.map((i) => i.session)).size,
+        first: g.items.map((i) => i.ts).filter(Boolean).sort()[0] || '',
+        last: g.items.map((i) => i.ts).filter(Boolean).sort().at(-1) || '',
+        items: g.items,
+      };
+    })
+    .sort((a, b) => b.count - a.count);
+}
+
+export const toRule = (phrase) => {
+  const p = phrase.trim().replace(/\s+/g, ' ');
+  return p.charAt(0).toUpperCase() + p.slice(1) + (/[.!]$/.test(p) ? '' : '.');
+};
+
+// Is this already a line in the rule file? Then the wording isn't landing.
+export function alreadyWritten(phrase, ruleText) {
+  return ruleText.split('\n').map((l) => l.replace(/^[\s>*\-#\d.]+/, '').trim())
+    .filter((l) => l.length > 3).some((l) => similar(phrase, l) >= SAME);
+}
+
+// How often a rule's phrase came back before and after it was added.
+export function beforeAfter(rule, items) {
+  let before = 0, after = 0;
+  for (const i of items) {
+    if (similar(rule.text, i.s) < SAME) continue;
+    if (i.ts && i.ts >= rule.addedAt) after++; else before++;
+  }
+  return { before, after };
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "toldya",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Stop repeating yourself to your AI. Finds what you keep telling your coding agent, writes it into CLAUDE.md / AGENTS.md, and counts whether it stopped.",
   "bin": {
-    "toldya": "bin/toldya.js"
+    "toldya": "bin/toldya.mjs"
   },
   "files": [
     "bin",
+    "lib",
     "README.md",
     "LICENSE"
   ],
@@ -29,5 +30,8 @@
     "url": "git+https://github.com/singhlabsdev/toldya.git"
   },
   "author": "Singh Labs (Sevenopt Solutions Private Limited) <info@singhlabs.dev>",
-  "license": "MIT"
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test"
+  }
 }

package/bin/toldya.js

@@ -1,19 +0,0 @@
-#!/usr/bin/env node
-// toldya 0.0.1 — the name is reserved while v0.1 is built. This version only
-// says what's coming, so nobody installs it expecting it to change a file.
-
-const lines = [
-  '',
-  '  toldya — stop repeating yourself to your AI.',
-  '',
-  '  Coming in v0.1:',
-  '    npx toldya              read your Claude Code / Codex history, find what you',
-  '                            keep telling the AI, offer lines for CLAUDE.md',
-  '    npx toldya owner/repo   read a repo\'s PR review comments, find the repeats,',
-  '                            open one PR into AGENTS.md',
-  '',
-  '  This version does nothing else. It reads nothing and writes nothing.',
-  '  Follow along: https://github.com/singhlabsdev/toldya',
-  '',
-];
-process.stdout.write(lines.join('\n') + '\n');