@intentic/claude-plugin 1.322.0 → 1.324.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
     "name": "intentic",
     "displayName": "Intentic",
-    "version": "1.322.0",
+    "version": "1.324.0",
     "description": "Cheaper, sharper Claude Code sessions: Bash output trimmed before Claude reads it, a project map and this project's field notes at session start, iq code search and fileq document reading taught, and /intentic:stats to show what each one saved. Every mechanism is a switch in /config.",
     "author": {
         "name": "intentic"

package/README.md

@@ -21,6 +21,8 @@ The hooks and the bundled commands run on Node.js 20.11 or later, which has to b
 | Claude reads a document | `fileq` turns docx, pdf, xlsx, pptx, epub, ipynb, images, audio and archives into markdown. | `fileq` |
 | Claude makes a document | `fileq check` lists what is wrong with a docx, pptx, xlsx or pdf by slide, page or cell, and `fileq render` draws its pages as PNGs for Claude to look at (with LibreOffice and poppler installed). The fileq skill says to run both before handing the file over. | `fileq` |
 
+| A Bash command succeeds, in Claude Code 2.1.287 or later | A line under the prompt says what the cleaners saved so far this session, and `/intentic-pane` shows the full report in a pane. See [In the interface](#in-the-interface). | `output_cleaners` |
+
 A failed command reaches Claude unchanged. Outside an Intentic sandbox there is no secret store to mask values from, so the cleaners mask only text that looks like a credential: an assignment to a name like `API_KEY` or `TOKEN` whose value looks generated, bearer tokens, AWS access keys, and passwords in URLs.
 
 The `intentic:Intentic` output style adds three working habits to Claude Code's own instructions: batch independent lookups, reuse what is already in context, and run long commands in the background instead of sleeping. Pick it in `/output-style`. It is off until you do.
@@ -31,7 +33,7 @@ Open `/config` and find the rows under intentic. The switches read at session st
 
 | Key | Default | Effect |
 | --- | --- | --- |
-| `output_cleaners` | on | Clean successful Bash output and ledger what each cleaner saved |
+| `output_cleaners` | on | Clean successful Bash output, ledger what each cleaner saved, and show the saving under the prompt. Off, none of the three happens |
 | `cleaners` | empty (all) | Which cleaners run: `-cap,-wide` switches some off, `git,pnpm` allows only those |
 | `output_holdout` | 0 | Share of commands left uncleaned, to measure the saving against real output |
 | `project_map` | on | Send the project map at session start |
@@ -62,6 +64,21 @@ The numbers above are an illustration of the format. The report reads two things
 
 The arithmetic is the one behind the savings page of an Intentic sandbox, from the same packages, so a number here means what it means there.
 
+## In the interface
+
+Claude Code 2.1.287 and later can load a small mod from a plugin, code that runs inside Claude Code and draws in its interface. The plugin's mod (`hooks/register.ts`) makes the cleaners' work visible, and does nothing else: it changes no output and sends nothing.
+
+| What | Where it shows | Needs |
+| --- | --- | --- |
+| A status line under the prompt, such as `intentic: Bash output trimmed 84% · 1.6M tokens saved over 12 commands`. It updates after each Bash command and stays empty until a command has been shortened. | The terminal and the Desktop app | `output_cleaners` on |
+| `/intentic-pane`, the `/intentic:stats` report in a pane with a Refresh button. `/intentic-pane all` reports every project. | The terminal and the Desktop app | `node` on `PATH`, as for the rest of the plugin |
+
+Where Claude Code draws nothing, the mod still runs and the status line has no place to go. `/intentic-pane` then answers with the report as text, as it also does in the VS Code extension and in `claude -p`. `/intentic:stats` works the same everywhere, whatever the version, and is the command to use in a script.
+
+The status line counts from the ledger rows the session has already written (when it resumes) and adds each Bash command as it finishes. It is the same ledger `/intentic:stats` reads, so the two agree, except that a command left untrimmed on purpose by `output_holdout` counts as saving nothing in the status line. The mod does a few additions and one status update per Bash command and reads the ledger once, when the session starts. Claude Code gives a mod hook 10 seconds, and 50 ms for the hook on prompt edits, which the mod does not use.
+
+Older Claude Code versions are not harmed by the mod. `modules` in `hooks/hooks.json` is a key those versions either do not know, in which case they read the file as before (checked on 2.1.200), or know and keep it switched off until a rollout reaches the account (seen on 2.1.283), in which case the Bash and session hooks still run and Claude Code may print one line at start saying that a hooks module was not loaded. From 2.1.287 on the module loads by default.
+
 ## Field notes
 
 Run `/intentic:field-notes` every few weeks. It counts this project's sessions (failures by how many sessions hit them, the commands that ran and how often they failed, the files edited most) and asks Claude to rewrite `.claude/intentic/field-notes.toon` from that evidence, checking each fact against the project before writing it. Commit the file to share it with a team, or ignore it to keep it yours.
@@ -89,6 +106,8 @@ The plugin is built from the packages that own each mechanism, so the sandbox an
 - [@intentic/fileq](../fileq): the CLI, bundled as `dist/fileq.mjs`, the text of its skill, and its NOTICE (rules adapted from SurfSense under Apache-2.0), copied to `generated/fileq-NOTICE`.
 - [@intentic/iq](../../_search/iq): the iq skill and the hint a session opens with. The build rewords the hint's two sandbox phrases for a plain install and fails if they change upstream.
 
+The mod is one source file, [hooks/register.ts](hooks/register.ts), shipped as it is: Claude Code loads TypeScript hooks modules itself, in an environment with no Node and no imports beyond the plugin's own files, so there is nothing to bundle. Its helpers are exported and tested with bun (`src/mod.test.ts`); the hooks as Claude Code wires them are tested with its own test runner (`tests/mod.test.ts`).
+
 The build writes `dist/` (one esbuild bundle per hook and command, so an install needs no `node_modules`) and `generated/` (the skills and the output style, from the texts those packages own). Both are ignored by git.
 
 ### Key files
@@ -106,7 +125,8 @@ The build writes `dist/` (one esbuild bundle per hook and command, so an install
 ```sh
 pnpm --filter @intentic/claude-plugin build      # dist/, generated/, and the version in plugin.json
 pnpm --filter @intentic/claude-plugin test
-pnpm --filter @intentic/claude-plugin validate   # build, then `claude plugin validate`
+pnpm --filter @intentic/claude-plugin test:mod   # the mod's tests, through `claude plugin test` (needs `claude` 2.1.287 or later on PATH)
+pnpm --filter @intentic/claude-plugin validate   # build, then `claude plugin validate --strict`
 claude --plugin-dir _sandbox/claude-plugin       # a session with the checkout loaded, after a build
 ```
 

package/dist/fileq.mjs

@@ -87118,8 +87118,8 @@ var require_body_reader = __commonJS({
         if (checkboxResult) {
           var checkboxElement = fldChar.firstOrEmpty("w:ffData").firstOrEmpty("w:checkBox");
           var checkedElement = checkboxElement.first("w:checked");
-          var checked = checkedElement == null ? readBooleanElement(checkboxElement.first("w:default")) : readBooleanElement(checkedElement);
-          return { type: "checkbox", checked };
+          var checked2 = checkedElement == null ? readBooleanElement(checkboxElement.first("w:default")) : readBooleanElement(checkedElement);
+          return { type: "checkbox", checked: checked2 };
         }
         return { type: "unknown" };
       }
@@ -105433,12 +105433,12 @@ var init_pdf_furniture = __esm({
 });
 
 // ../fileq/src/lib/derivers/pdf.ts
-import { execFile as execFile2 } from "node:child_process";
+import { execFile as execFile2, spawnSync } from "node:child_process";
 import { mkdtemp, readdir, readFile as readFile10, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join as join3 } from "node:path";
 import { promisify as promisify2 } from "node:util";
-var SCAN_THRESHOLD_CHARS_PER_PAGE, MAX_OCR_PAGES, OCR_DPI, run3, ocrAvailable, recognisePages, pagesToMarkdown, furnitureNotes, withoutFurniture, pdfDeriver;
+var SCAN_THRESHOLD_CHARS_PER_PAGE, MAX_OCR_PAGES, OCR_DPI, OCR_TIMEOUT_MS, run3, checked, ocrAvailable, readPages, recognisePages, pagesToMarkdown, furnitureNotes, withoutFurniture, pdfDeriver;
 var init_pdf = __esm({
   "../fileq/src/lib/derivers/pdf.ts"() {
     "use strict";
@@ -105448,8 +105448,27 @@ var init_pdf = __esm({
     SCAN_THRESHOLD_CHARS_PER_PAGE = 24;
     MAX_OCR_PAGES = 20;
     OCR_DPI = "200";
+    OCR_TIMEOUT_MS = 6e4 + MAX_OCR_PAGES * 15e3;
     run3 = promisify2(execFile2);
-    ocrAvailable = () => onPath("tesseract") && onPath("pdftoppm");
+    checked = /* @__PURE__ */ new Map();
+    ocrAvailable = () => {
+      const path = process.env["PATH"] ?? "";
+      let available = checked.get(path);
+      if (available === void 0) {
+        available = onPath("pdftoppm") && onPath("ocr") && spawnSync("ocr", ["--check"], { stdio: "ignore", timeout: 1e4 }).status === 0;
+        checked.set(path, available);
+      }
+      return available;
+    };
+    readPages = (images) => new Promise((resolve6, reject) => {
+      execFile2("ocr", [...images], { timeout: OCR_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }, (error2, stdout) => {
+        if (error2 === null || error2.code === 1) {
+          resolve6(stdout);
+        } else {
+          reject(error2);
+        }
+      });
+    });
     recognisePages = async (absPath, totalPages) => {
       const dir = await mkdtemp(join3(tmpdir(), "fileq-ocr-"));
       try {
@@ -105457,12 +105476,11 @@ var init_pdf = __esm({
           timeout: 12e4
         });
         const images = (await readdir(dir)).filter((name) => name.endsWith(".png")).toSorted();
-        const pages = [];
-        for (const image of images) {
-          const { stdout } = await run3("tesseract", [join3(dir, image), "stdout", "-l", "eng"], { timeout: 12e4, maxBuffer: 16 * 1024 * 1024 });
-          pages.push(stdout.replaceAll(/[ \t]+/g, " ").trim());
+        if (images.length === 0) {
+          return [];
         }
-        return pages;
+        const pages = (await readPages(images.map((image) => join3(dir, image)))).split("\f");
+        return images.map((_3, index) => (pages[index] ?? "").replaceAll(/[ \t]+/g, " ").trim());
       } finally {
         await rm(dir, { recursive: true, force: true });
       }
@@ -105478,11 +105496,11 @@ ${page === "" ? "(no text on this page)" : page}`).join("\n\n");
       return { markdown: pagesToMarkdown(kept), notes: furnitureNotes(removed, example) };
     };
     pdfDeriver = {
-      // The stamp names OCR capability, since a sidecar written before tesseract was available must read as stale now
-      // that it's here.
-      // A static name would leave a pre-OCR sidecar looking current forever.
+      // The stamp names OCR capability, since a sidecar written before the reader was available must read as stale now
+      // that it's here. A static name would leave a pre-OCR sidecar looking current forever. It names the reader too:
+      // `pdf+ocr` was tesseract's, whose pages PaddleOCR reads again.
       get name() {
-        return ocrAvailable() ? "pdf+ocr" : "pdf";
+        return ocrAvailable() ? "pdf+ppocr" : "pdf";
       },
       version: 2,
       derive: async (absPath) => {
@@ -105504,10 +105522,10 @@ ${page === "" ? "(no text on this page)" : page}`).join("\n\n");
           }
           const recognised = await recognisePages(absPath, totalPages);
           const notes = [
-            `scanned: text recognised by OCR (tesseract) on ${recognised.length} of ${totalPages} page${plural3} \u2014 recognised, not exact; check figures against the page image`
+            `scanned: text recognised by OCR (PaddleOCR) on ${recognised.length} of ${totalPages} page${plural3} \u2014 recognised, not exact; check figures against the page image`
           ];
           if (totalPages > MAX_OCR_PAGES) {
-            notes.push(`OCR stops at ${MAX_OCR_PAGES} pages: run tesseract over the rest yourself if they matter`);
+            notes.push(`OCR stops at ${MAX_OCR_PAGES} pages: draw the rest with pdftoppm and read them with \`ocr <page.png>...\` if they matter`);
           }
           const { markdown, notes: stripped } = withoutFurniture(recognised);
           return { markdown, title, notes: [...notes, ...stripped] };

package/dist/stats.mjs

@@ -13,6 +13,8 @@ var OPENING_SEARCHES = { name: "openingSearches", of: (turn) => turn.openingSear
 var ROOT_LISTINGS = { name: "openingListings", of: (turn) => turn.openingListings, round: round1 };
 var CALLS_BEFORE_TARGET = { name: "callsBeforeTarget", of: (turn) => turn.callsBeforeTarget, round: round1 };
 var FAILED_CALLS = { name: "failedCalls", of: (turn) => turn.failedCalls, round: round1 };
+var ROUND_TRIPS = { name: "roundTrips", of: (turn) => turn.roundTrips, round: round1 };
+var CONTEXT_PER_CALL = { name: "contextPerCall", of: (turn) => turn.contextPerCall, round: Math.round };
 var armOfValues = (values) => {
   if (values.length === 0) {
     return { turns: 0, mean: 0, variance: 0 };
@@ -73,8 +75,12 @@ var MECHANISMS = {
   map: { metrics: [ROOT_LISTINGS, CALLS_BEFORE_TARGET], sampleUnit: "opening turns", sample: openingTurn },
   // The brief rides the whole session, so turn 40 is as much evidence as turn 1.
   notes: { metrics: [FAILED_CALLS, CALLS_BEFORE_TARGET], sampleUnit: "conversations", sample: meanOfTurns },
-  // Judged on what the long form was written to prevent: calls that fail, and calls spent before reaching the work.
-  guidance: { metrics: [FAILED_CALLS, CALLS_BEFORE_TARGET], sampleUnit: "conversations", sample: meanOfTurns }
+  // Judged on what the long form was written to prevent: calls that fail, calls spent before reaching the work, and
+  // the round trips its batching and context-reuse paragraphs ask the agent not to spend.
+  guidance: { metrics: [FAILED_CALLS, CALLS_BEFORE_TARGET, ROUND_TRIPS], sampleUnit: "conversations", sample: meanOfTurns },
+  // Judged on what it is for, the prompt each call carries, and on what it could cost: a model that has lost a result
+  // it needed runs the tool again (more round trips) or guesses (more calls that fail).
+  clearing: { metrics: [CONTEXT_PER_CALL, ROUND_TRIPS, FAILED_CALLS], sampleUnit: "conversations", sample: meanOfTurns }
 };
 var measureExperiment = (turns, design) => {
   const latest = turns.filter((turn) => design.arm(turn) !== void 0 && design.cohort(turn) !== void 0).toSorted((left, right) => right.at - left.at)[0];

package/generated/skills/fileq/SKILL.md

@@ -13,7 +13,7 @@ cached by content, so a repeat read of unchanged content is instant.
 - Prints a capsule (format, token cost), the content up to the budget, and `saved:` — the markdown file
   carrying the whole thing. Over budget, the cut is announced with that exact path to Read.
 - Formats: docx and odt (headings, lists, tables), xlsx (capped tables), pptx (slides + speaker notes),
-  pdf (text layer; a scan is OCR'd when `tesseract` is on PATH, and the note says the words are
+  pdf (text layer; a scan is OCR'd when an `ocr` command is on PATH, and the note says the words are
   recognised, not exact), epub (chapters in reading order), ipynb (cells, fenced code, capped outputs),
   png/jpg/gif/webp (dimensions + EXIF), mp3/wav/flac/mp4/… (duration + tags), html, and V8 profiles
   (`.cpuprofile` from `node --cpu-prof`, `.heapprofile` from `--heap-prof`) as functions ranked by self and total cost.
@@ -29,9 +29,10 @@ without parsing it again. Run it again rather than opening a sidecar under `.int
 checks the hash for you.
 
 ## What it refuses, and why
-- A scanned PDF with no `tesseract` on PATH answers "no usable text layer … OCR is not part of this tier"
+- A scanned PDF with no `ocr` on PATH answers "no usable text layer … OCR is not part of this tier"
   rather than an empty page; images say "no visual description". Treat those notes as "not generated",
-  never as "nothing there". Installing tesseract turns the first into OCR.
+  never as "nothing there". An `ocr` command that prints each image's text, a form feed between images (the
+  Intentic sandbox's PaddleOCR reader), turns the first into OCR.
 - Plain text (md, csv, txt, code) is not fileq's business: Read it directly — but see below for the big ones.
 - Web pages belong to `webq`; images for a vision model belong to the Read tool, which shows the pixels.
 

package/hooks/hooks.json

@@ -1,5 +1,8 @@
 {
     "description": "intentic: session context (map, field notes, iq teaching), Bash output cleaning. Each script reads its own /config switch and answers nothing when it is off. Without node on PATH the tool hooks stand down silently and each session opens with one line saying why nothing ran.",
+    "modules": [
+        "./register.ts"
+    ],
     "hooks": {
         "SessionStart": [
             {

package/hooks/register.ts

@@ -0,0 +1,311 @@
+// The plugin's mod: what the Bash output cleaners saved, drawn in Claude Code (2.1.287 or later). Claude Code loads this
+// file in-process, from `modules` in hooks.json, next to the shell hooks that do the cleaning; it only shows their work.
+//   - a status entry under the prompt, updated after each Bash call: "Bash trimmed 84% · 1.6M tokens saved · 12 commands";
+//   - `/intentic-pane`, the /intentic:stats report in a pane, or as text where nothing draws.
+// A mod runs in an environment with no Node, so files and processes go through `$`, and this one file imports nothing:
+// the engine's own types (`import type … from 'claude-code'`) are only written once a mod has loaded, so the few members
+// used here are declared below instead, which keeps the package's typecheck working on a fresh checkout.
+// Limits (code.claude.com/docs/en/plugins/mods/reference): a hook gets 10 s, a prompt.edit hook 50 ms; nothing here hooks
+// prompt.edit, and the per-call hook does a string-length sum and one `$.ui.status` call.
+
+// ---- the slice of the mods API this file uses ----------------------------------------------------------------------
+
+interface Element {
+    readonly type: string;
+}
+
+type Component<P> = (props: P) => Element;
+
+interface Api {
+    readonly plugin: { readonly name: string; readonly root: string };
+    readonly env: { get(name: string): Promise<string | undefined> };
+    readonly fs: {
+        read(path: string): Promise<string>;
+        exists(path: string): Promise<boolean>;
+        list(path: string): Promise<readonly { readonly name: string; readonly kind: string }[]>;
+        stat(path: string): Promise<{ readonly mtimeMs: number }>;
+    };
+    readonly process: { run(argv: readonly string[], init?: { cwd?: string; timeoutMs?: number }): Promise<{ exitCode: number; stdout: string; stderr: string }> };
+    readonly session: { id(): Promise<string>; cwd(): Promise<string>; surfaces(): Promise<readonly string[]> };
+    readonly command: { register(spec: { name: string; description: string; argumentHint?: string }): Promise<object> };
+    readonly ui: {
+        status(text: string | undefined): void;
+        open(pane: { id: string; title?: string }): Promise<{ isPlaced: boolean }>;
+        close(pane: { id: string }): Promise<void>;
+        invalidate(event: "ui.render"): void;
+        resolve(e: RenderEvent): {
+            Box: Component<{ flexDirection?: "column" | "row"; gap?: number; children?: readonly Element[] }>;
+            Text: Component<{ dimColor?: boolean; children?: string }>;
+            Markdown: Component<{ text: string }>;
+            Button: Component<{ key: string; label: string; hotkey?: string; onPress: () => Promise<void> }>;
+        };
+    };
+}
+
+type Next<E, R> = (e: E) => Promise<R>;
+type Hook<E, R> = ($: Api, e: E, next: Next<E, R>) => Promise<R> | R;
+
+interface PostToolUse {
+    readonly session_id?: string;
+    readonly tool_name?: string;
+    readonly tool_response?: BashResponse | string | null;
+}
+interface PostToolUseResult {
+    readonly updatedToolOutput?: BashResponse | string | null;
+}
+interface CommandRun {
+    readonly args: string;
+}
+interface SessionStart {
+    readonly cwd?: string;
+}
+// A tool's result as Claude Code hands it over; Bash's carries these, and whatever else it carries is left alone.
+interface BashResponse {
+    readonly stdout?: string | number | boolean | object | null;
+    readonly stderr?: string | number | boolean | object | null;
+    readonly interrupted?: boolean;
+    readonly isImage?: boolean;
+    readonly backgroundTaskId?: string | number | null;
+}
+interface LedgerRow {
+    readonly session?: string | number | null;
+    readonly rawBytes?: string | number | null;
+    readonly emittedBytes?: string | number | null;
+}
+interface Options {
+    readonly output_cleaners?: boolean | string | number | readonly string[];
+}
+
+interface RenderEvent {
+    readonly surface?: string;
+}
+
+interface On {
+    (event: "session.start", hook: Hook<SessionStart, SessionStart>): void;
+    (event: "classic.PostToolUse", hook: Hook<PostToolUse, PostToolUseResult | undefined>): void;
+    (event: "command.run", matcher: { command: string }, hook: Hook<CommandRun, { text?: string }>): void;
+    (event: "ui.render", matcher: { component: "Pane"; requestId: string }, hook: Hook<RenderEvent, Element>): void;
+}
+
+export type Register = (on: On, options: Options) => void;
+
+// ---- what the cleaners saved: pure helpers, tested without an engine ---------------------------------------------------
+
+export interface Tally {
+    readonly commands: number;
+    readonly raw: number;
+    readonly emitted: number;
+}
+
+export const EMPTY: Tally = { commands: 0, raw: 0, emitted: 0 };
+
+export const add = (tally: Tally, raw: number, emitted: number): Tally => ({ commands: tally.commands + 1, raw: tally.raw + raw, emitted: tally.emitted + emitted });
+
+// A ledger row, as @intentic/output-cleaners writes it into filter-stats.jsonl: lengths of the text before and after the
+// cleaners, tagged by the plugin's post-bash hook with the project and the session.
+export const seedFromLedger = (text: string, session: string): Tally => {
+    let tally = EMPTY;
+    for (const line of text.split("\n")) {
+        // The session id is a substring of its own rows, so most lines are skipped before they are parsed.
+        if (!line.includes(session)) {
+            continue;
+        }
+        try {
+            // SAFETY: a ledger line is whatever a past hook wrote; each field is checked by type before it is used.
+            const row = JSON.parse(line) as LedgerRow;
+            if (row.session === session && typeof row.rawBytes === "number" && typeof row.emittedBytes === "number") {
+                tally = add(tally, row.rawBytes, row.emittedBytes);
+            }
+        } catch {
+            // allow(silent-catch): a torn or foreign line is not a row; the ledger's own reader skips these the same way.
+        }
+    }
+    return tally;
+};
+
+// What the model would have read of a Bash result, which is what post-bash.ts counts as the raw text: stdout, then stderr.
+export const textLength = (response: BashResponse | string | null | undefined): number | undefined => {
+    if (typeof response !== "object" || response === null) {
+        return undefined;
+    }
+    const { stdout, stderr, interrupted, isImage, backgroundTaskId } = response;
+    if (typeof stdout !== "string" || interrupted === true || isImage === true || backgroundTaskId !== undefined) {
+        return undefined;
+    }
+    const err = typeof stderr === "string" ? stderr : "";
+    return err === "" ? stdout.length : stdout.length + (stdout === "" || stdout.endsWith("\n") ? 0 : 1) + err.length;
+};
+
+export const emittedLength = (result: PostToolUseResult | undefined): number | undefined => {
+    return textLength(result?.updatedToolOutput);
+};
+
+// Four characters to a token, as the ledger's own summary counts.
+const tokens = (length: number): string => {
+    const count = Math.round(length / 4);
+    if (count >= 1_000_000) {
+        return `${(count / 1_000_000).toFixed(1)}M`;
+    }
+    if (count >= 10_000) {
+        return `${Math.round(count / 1000)}k`;
+    }
+    return count >= 1000 ? `${(count / 1000).toFixed(1)}k` : String(count);
+};
+
+// Nothing until a command has actually been shortened: "0% saved" under every prompt is noise.
+export const statusText = (tally: Tally): string | undefined => {
+    const saved = tally.raw - tally.emitted;
+    if (saved <= 0 || tally.raw === 0) {
+        return undefined;
+    }
+    return `intentic: Bash output trimmed ${Math.round((saved / tally.raw) * 100)}% · ${tokens(saved)} tokens saved over ${tally.commands} ${tally.commands === 1 ? "command" : "commands"}`;
+};
+
+// The plugin's data directory, where post-bash.ts keeps the ledger and session-start.ts the switches. A hook gets it as
+// CLAUDE_PLUGIN_DATA; a mod is not given it, so it is worked out the way Claude Code does: `plugins/data/<name>-<marketplace>`
+// under the config directory, the marketplace read off the plugin's own install path (`plugins/cache/<marketplace>/<name>/<version>`),
+// and `<name>-inline` for a plugin loaded from a folder.
+export const dataDirOf = (name: string, root: string, env: { data?: string | undefined; config?: string | undefined; home?: string | undefined }): string | undefined => {
+    if (env.data !== undefined && env.data !== "") {
+        return env.data;
+    }
+    const config = env.config !== undefined && env.config !== "" ? env.config : env.home !== undefined && env.home !== "" ? `${env.home}/.claude` : undefined;
+    if (config === undefined) {
+        return undefined;
+    }
+    const cached = /[\\/]plugins[\\/]cache[\\/]([^\\/]+)[\\/]([^\\/]+)[\\/][^\\/]+[\\/]?$/.exec(root);
+    const id = `${name}-${cached?.[1] ?? "inline"}`.replace(/[^a-zA-Z0-9_-]/g, "-");
+    return `${config.replace(/[\\/]+$/, "")}/plugins/data/${id}`;
+};
+
+// ---- the mod ---------------------------------------------------------------------------------------------------------
+
+const PANE = "intentic-savings";
+const COMMAND = "intentic-pane";
+// A pane's Markdown holds 10,000 characters; the report is a fraction of that, but a project list could grow.
+const REPORT_LIMIT = 9000;
+
+// Where this plugin keeps its ledger: the directory Claude Code names for its hooks (see dataDirOf). A plugin read from a
+// folder (a marketplace that is a directory) has an install path that says nothing about its marketplace, so when the
+// derived directory holds nothing the session-start hook wrote (`options.json`, written every session), the plugin's own
+// newest sibling under plugins/data is taken instead.
+const dataDir = async ($: Api): Promise<string | undefined> => {
+    const derived = dataDirOf($.plugin.name, $.plugin.root, {
+        data: await $.env.get("CLAUDE_PLUGIN_DATA"),
+        config: await $.env.get("CLAUDE_CONFIG_DIR"),
+        home: (await $.env.get("HOME")) ?? (await $.env.get("USERPROFILE")),
+    });
+    if (derived === undefined || (await $.fs.exists(`${derived}/options.json`))) {
+        return derived;
+    }
+    const parent = derived.slice(0, derived.lastIndexOf("/"));
+    let best = derived;
+    let newest = -1;
+    try {
+        for (const entry of await $.fs.list(parent)) {
+            if (entry.kind !== "dir" || !entry.name.startsWith(`${$.plugin.name}-`)) {
+                continue;
+            }
+            const written = await $.fs.stat(`${parent}/${entry.name}/options.json`).then(
+                (stat) => stat.mtimeMs,
+                () => -1,
+            );
+            if (written > newest) {
+                newest = written;
+                best = `${parent}/${entry.name}`;
+            }
+        }
+    } catch {
+        // allow(silent-catch): no plugins/data yet means nothing has run, and the derived directory is as good as any.
+    }
+    return best;
+};
+
+// The /intentic:stats report, from the bundle the plugin ships; the same code the skill runs, so the pane and the command
+// say the same thing.
+const buildReport = async ($: Api, args: string): Promise<string> => {
+    const data = await dataDir($);
+    if (data === undefined) {
+        return "intentic: the plugin's data directory could not be found, so there is no report to show.";
+    }
+    const argv = ["node", `${$.plugin.root}/dist/stats.mjs`, "--data", data, "--project", await $.session.cwd(), ...(args.trim() === "all" ? ["all"] : [])];
+    try {
+        const ran = await $.process.run(argv, { timeoutMs: 20_000 });
+        return ran.exitCode === 0 ? ran.stdout.slice(0, REPORT_LIMIT) : `intentic: the report failed (exit ${ran.exitCode}): ${ran.stderr.trim().slice(0, 300)}`;
+    } catch (error) {
+        return `intentic: the report needs Node.js 20.11 or later on PATH (${error instanceof Error ? error.message : String(error)}).`;
+    }
+};
+
+export const register: Register = (on, options) => {
+    // The same switch the shell hooks read: off, nothing is cleaned, nothing is ledgered, and there is nothing to show.
+    const cleaning = options["output_cleaners"] !== false;
+    let tally: Tally = EMPTY;
+    let report = "";
+
+    on("session.start", async ($, e, next) => {
+        await $.command.register({ name: COMMAND, description: "Show what the intentic plugin saved, in a pane", argumentHint: "[all]" });
+        if (cleaning) {
+            try {
+                const data = await dataDir($);
+                const session = await $.session.id();
+                // Resumed or reloaded: what this session already saved is in the ledger. A ledger over the 4 MiB a mod may
+                // read at once is not an error; the count starts from this point.
+                tally = data === undefined ? EMPTY : seedFromLedger(await $.fs.read(`${data}/output/filter-stats.jsonl`), session);
+            } catch {
+                tally = EMPTY;
+            }
+            $.ui.status(statusText(tally));
+        }
+        return next(e);
+    });
+
+    if (cleaning) {
+        on("classic.PostToolUse", async ($, e, next) => {
+            const raw = e.tool_name === "Bash" ? textLength(e.tool_response) : undefined;
+            const result = await next(e);
+            if (raw !== undefined) {
+                // The shell hook answers with the trimmed result, or with nothing when it left the output as it was.
+                tally = add(tally, raw, emittedLength(result) ?? raw);
+                $.ui.status(statusText(tally));
+            }
+            return result;
+        });
+    }
+
+    on("command.run", { command: COMMAND }, async ($, e) => {
+        report = await buildReport($, e.args);
+        // A plain `-p` run has no surface at all, and `ui.open` would answer "placed" into nothing; a surface that places no
+        // panes answers "not placed". Either way the report goes out as the command's own text, which every Claude Code shows.
+        const draws = (await $.session.surfaces()).length > 0;
+        const opened = draws ? await $.ui.open({ id: PANE, title: "intentic savings" }) : undefined;
+        if (opened?.isPlaced === true) {
+            $.ui.invalidate("ui.render");
+            return {};
+        }
+        if (opened !== undefined) {
+            await $.ui.close({ id: PANE });
+        }
+        return { text: report };
+    });
+
+    on("ui.render", { component: "Pane", requestId: PANE }, ($, e) => {
+        const { Box, Text, Markdown, Button } = $.ui.resolve(e);
+        return Box({
+            flexDirection: "column",
+            gap: 1,
+            children: [
+                report === "" ? Text({ dimColor: true, children: "Run /intentic-pane to fill this." }) : Markdown({ text: report }),
+                Button({
+                    key: "refresh",
+                    label: "Refresh",
+                    hotkey: "r",
+                    onPress: async () => {
+                        report = await buildReport($, "");
+                        $.ui.invalidate("ui.render");
+                    },
+                }),
+            ],
+        });
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/claude-plugin",
-  "version": "1.322.0",
+  "version": "1.324.0",
   "description": "The intentic Claude Code plugin: trimmed Bash output, a project map and field notes at session start, iq search and fileq teaching, and a /intentic:stats report of what each saved",
   "license": "MIT",
   "type": "module",
@@ -40,8 +40,8 @@
   },
   "devDependencies": {
     "@intentic/agent-context": "0.0.0",
-    "@intentic/fileq": "1.322.0",
-    "@intentic/iq": "1.322.0",
+    "@intentic/fileq": "1.324.0",
+    "@intentic/iq": "1.324.0",
     "@intentic/output-cleaners": "0.0.0",
     "@intentic/testing": "0.0.0",
     "@intentic/tsconfig": "0.0.0",
@@ -55,6 +55,7 @@
     "typecheck": "tsgo --noEmit -p tsconfig.test.json",
     "test": "suites",
     "test:watch": "suites --watch",
+    "test:mod": "node test-mod.mjs",
     "validate": "node build.mjs --validate"
   }
 }