opencode-skill-audit 0.1.2 → 0.2.0-dev.pr3.36976113543

package/README.md

@@ -12,8 +12,8 @@ Deterministic audit trail for [Claude Code](https://code.claude.com),
 observable **skills** were invoked, when, and which **files** were changed afterwards. It gives you
 a quick skill-compliance signal before you read the code.
 
-On opencode it also renders live in the TUI sidebar, so the audit sits next to the conversation
-with no command to run.
+On opencode it also renders live in the TUI sidebar, and on Claude Code in a live pane, so the audit
+sits next to the conversation with no command to run.
 
 ```text
 ● Skill audit — f3a91c2e · ~/Dev/Web · 14:02→16:40
@@ -90,7 +90,8 @@ Claude Code / Codex ──hooks───▶ logger.sh ──┐
                                             ├─▶ ~/.claude/skill-audit/<sid>.ndjson
 opencode ──tool.execute.after──▶ plugin ────┘             │
                                                           ├─▶ skill-audit status/report/watch/list
-                                                          └─▶ opencode sidebar (live)
+                                                          ├─▶ opencode sidebar (live)
+                                                          └─▶ Claude Code pane (live)
 ```
 
 The log is the only contract between the writers and the viewers, so the CLI reads opencode
@@ -109,6 +110,22 @@ Subagent hook calls use the parent session ID, so delegated edits appear in the
 
 Restart Claude Code so the hooks load.
 
+#### Live pane
+
+The plugin also opens a **Skill audit** pane showing the current session's timeline. It refreshes
+after every skill and file-edit tool call, and polls the log every two seconds.
+
+- **Opening:** it opens by itself at session start once the terminal is 144 columns or wider.
+  Narrower terminals hold it back until you run `/skill-audit-pane`, which opens it at any width.
+- **Placement:** in fullscreen from 110 columns it docks beside the transcript and shows the full
+  timeline. Press a `▼`/`▶` marker to collapse or expand a run or an hour. Elsewhere it sits above
+  the prompt in a compact form: the header and the latest run.
+- **Other panes:** panes from other plugins become tabs beside it (click a tab, or ctrl+x tab).
+  Only one is shown at a time. Esc or the close mark closes it.
+
+The pane is display only. The shell hooks keep writing the log through `logger.sh`, so recording
+works the same on Claude Code builds without plugin function hooks.
+
 > **Migrating from a manual setup?** Remove any `logger.sh` entries from the `hooks` block of
 > `~/.claude/settings.json` first, or every event is logged twice.
 
@@ -234,6 +251,7 @@ If `list` prints `no session logs in ...`, nothing was written. Go to
 | `skill-audit --help`       | Usage summary                                                    |          0 |
 | `! skill-audit status`     | Run inside a Claude Code session. Queues while the model is busy |          0 |
 | opencode sidebar           | Live timeline beside the conversation. No command to run         |          0 |
+| Claude Code pane           | Live timeline in a pane. `/skill-audit-pane` opens it            |          0 |
 | `/skill-audit`             | Show the report inside Claude Code                               | Model turn |
 | `$skill-audit`             | Show the report inside Codex                                     | Model turn |
 
@@ -361,6 +379,8 @@ and sidebar are TypeScript (`src/`) built with [Bun](https://bun.sh).
 |-------------------|----------------------------------------------------------------------------|
 | `scripts/`        | `logger.sh` hook target, the `skill-audit` CLI, `sync-versions.mjs`        |
 | `src/`            | opencode plugin (`index.ts`), sidebar (`tui.ts`), shared log and view code |
+| `hooks/`          | Claude Code shell hooks (`hooks.json`) and the live pane (`claude.tsx`)    |
+| `types/`          | `$.state` contract for the Claude Code pane                                |
 | `test/`           | Bun tests, fixtures, and `test/format-contract.sh`                         |
 | `.claude-plugin/` | Claude Code plugin manifest and marketplace entry                          |
 | `.codex-plugin/`  | Codex plugin manifest                                                      |
@@ -375,17 +395,28 @@ bun run check     # format:check + lint + typecheck (src and test) + tests
 bun run build     # dist/index.js (plugin) and dist/tui.js (sidebar)
 ```
 
-| Script                   | What                                                     |
-|--------------------------|----------------------------------------------------------|
-| `bun run format`         | Prettier, write mode                                     |
-| `bun run lint`           | ESLint over `src` and `test`                             |
-| `bun run typecheck`      | `tsc --noEmit` for `src`                                 |
-| `bun test`               | Bun test suite in `test/`                                |
-| `bun run check`          | Everything CI runs                                       |
-| `bun run check:versions` | Assert `package.json` and both `plugin.json` files agree |
-| `bun run sync:versions`  | Rewrite the plugin manifests from `package.json`         |
-
-Tests live in `test/`. `test/format-contract.sh` pins the rendered CLI output against fixtures, so
+| Script                     | What                                                     |
+|----------------------------|----------------------------------------------------------|
+| `bun run format`           | Prettier, write mode                                     |
+| `bun run lint`             | ESLint over `src` and `test`                             |
+| `bun run typecheck`        | `tsc --noEmit` for `src`                                 |
+| `bun test`                 | Bun test suite in `test/`                                |
+| `bun run check`            | Everything CI runs                                       |
+| `bun run test:claude`      | Validate and test the Claude Code pane (needs `claude`)  |
+| `bun run typecheck:claude` | Type-check the pane (needs `.claude-plugin/types/`)      |
+| `bun run check:versions`   | Assert `package.json` and both `plugin.json` files agree |
+| `bun run sync:versions`    | Rewrite the plugin manifests from `package.json`         |
+
+Tests live in `test/`. The Claude Code pane is the exception: its tests (`hooks/*.test.tsx`) run
+in Claude Code's mod sandbox, which has no Node or Bun, so `bun test` is rooted at `test/`
+(`bunfig.toml`). `test:claude` copies the pane's files into a scratch folder and runs
+`claude plugin validate` and `claude plugin test` there. `src/core.ts` and `src/view.ts` must stay
+free of `node:*` imports and `process` because the pane imports them; `test/core.test.ts` checks
+this. `typecheck:claude` reads the API types the engine writes to `.claude-plugin/types/` once it
+has loaded the plugin from a local folder. That folder is gitignored and not available in CI, so
+neither pane check runs in CI.
+
+`test/format-contract.sh` pins the rendered CLI output against fixtures, so
 a change to the timeline format has to be updated there deliberately. That output is the contract
 the sidebar and any third-party viewer rely on.
 

package/dist/core.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The log model with no Node dependency. The Claude Code pane runs in a
+ * sandbox without `node:*` modules or `process`, so everything it shares with
+ * the CLI and the opencode sidebar lives here; `log.ts` adds the file I/O.
+ */
+export type SkillEvent = {
+    ts: string;
+    kind: "skill";
+    name: string;
+    args?: string;
+    cwd?: string;
+    source?: string;
+};
+export type FileEvent = {
+    ts: string;
+    kind: "file";
+    tool: string;
+    path: string;
+    cwd?: string;
+};
+export type AuditEvent = SkillEvent | FileEvent;
+/**
+ * An environment variable where the host has one, `undefined` where it does
+ * not. Read through `globalThis` because a bare `process` throws in the Claude
+ * Code sandbox.
+ */
+export declare function env(name: string): string | undefined;
+/**
+ * Parse NDJSON log text. Malformed lines are dropped rather than thrown on: the
+ * sidebar reads the log while the logger is appending to it, so a truncated
+ * trailing line is expected, not exceptional.
+ */
+export declare function parse(text: string): AuditEvent[];
+export declare const NO_SKILL = "(no skill active)";
+export type TimelineFile = {
+    ts: string;
+    tool: string;
+    path: string;
+};
+export type SkillRun = {
+    skill: string;
+    ts: string;
+    files: TimelineFile[];
+};
+/** How long a skill run may sit idle before it stops claiming later edits. */
+export declare const DEFAULT_IDLE_GAP_MS: number;
+/** `SKILL_AUDIT_IDLE_MINUTES` as milliseconds, or the default when unusable. */
+export declare function idleGapFrom(minutes: string | undefined): number;
+/**
+ * The idle gap, in milliseconds. Without one a single skill invoked in the
+ * morning claims every edit made for the rest of the day.
+ */
+export declare function idleGapMs(): number;
+/**
+ * Group a flat event list into skill runs, each carrying the files edited after
+ * it. Port of the jq reduce in scripts/skill-audit; the two must agree.
+ *
+ * A run only claims edits that keep arriving: once `gapMs` passes with no
+ * activity, later files fall into a synthetic run instead. An unparseable
+ * timestamp compares as NaN, which never exceeds the gap, so logs written
+ * before this rule existed group exactly as they did before.
+ */
+export declare function group(events: AuditEvent[], gapMs?: number): SkillRun[];
+export type Summary = {
+    runs: number;
+    distinct: number;
+    files: number;
+    orphan: number;
+};
+export declare function summarize(events: AuditEvent[], gapMs?: number): Summary;
+export type SessionView = {
+    runs: SkillRun[];
+    summary: Summary;
+    cwd: string;
+};
+/** A session's view from its raw log text; empty text is an empty session. */
+export declare function toView(text: string, gapMs?: number): SessionView;
+/** `node:path` basename for POSIX paths: the last segment, trailing slashes ignored. */
+export declare function baseName(path: string): string;
+/**
+ * `path` relative to `cwd` when it sits under it, else `path` as given. The
+ * sidebar only ever shortens paths inside the session directory.
+ */
+export declare function relativeTo(path: string, cwd: string): string;

package/dist/index.js

@@ -3,13 +3,17 @@
 import { appendFileSync, mkdirSync, readFileSync } from "fs";
 import { homedir } from "os";
 import { isAbsolute, join } from "path";
+
+// src/core.ts
+var DEFAULT_IDLE_GAP_MS = 30 * 60000;
+
+// src/log.ts
 function logDir() {
   return process.env.SKILL_AUDIT_DIR || join(homedir(), ".claude", "skill-audit");
 }
 function logPath(sessionID) {
   return join(logDir(), `${sessionID}.ndjson`);
 }
-var DEFAULT_IDLE_GAP_MS = 30 * 60000;
 function append(sessionID, event) {
   try {
     mkdirSync(logDir(), { recursive: true });

package/dist/log.d.ts

@@ -1,63 +1,8 @@
+import { type SessionView } from "./core";
+export * from "./core";
 /** Directory holding the per-session NDJSON logs, shared with the bash logger. */
 export declare function logDir(): string;
 export declare function logPath(sessionID: string): string;
-export type SkillEvent = {
-    ts: string;
-    kind: "skill";
-    name: string;
-    args?: string;
-    cwd?: string;
-    source?: string;
-};
-export type FileEvent = {
-    ts: string;
-    kind: "file";
-    tool: string;
-    path: string;
-    cwd?: string;
-};
-export type AuditEvent = SkillEvent | FileEvent;
-/**
- * Parse NDJSON log text. Malformed lines are dropped rather than thrown on: the
- * sidebar reads the log while the logger is appending to it, so a truncated
- * trailing line is expected, not exceptional.
- */
-export declare function parse(text: string): AuditEvent[];
-export declare const NO_SKILL = "(no skill active)";
-export type TimelineFile = {
-    ts: string;
-    tool: string;
-    path: string;
-};
-export type SkillRun = {
-    skill: string;
-    ts: string;
-    files: TimelineFile[];
-};
-/** How long a skill run may sit idle before it stops claiming later edits. */
-export declare const DEFAULT_IDLE_GAP_MS: number;
-/**
- * The idle gap, in milliseconds. Without one a single skill invoked in the
- * morning claims every edit made for the rest of the day.
- */
-export declare function idleGapMs(): number;
-/**
- * Group a flat event list into skill runs, each carrying the files edited after
- * it. Port of the jq reduce in scripts/skill-audit; the two must agree.
- *
- * A run only claims edits that keep arriving: once `gapMs` passes with no
- * activity, later files fall into a synthetic run instead. An unparseable
- * timestamp compares as NaN, which never exceeds the gap, so logs written
- * before this rule existed group exactly as they did before.
- */
-export declare function group(events: AuditEvent[], gapMs?: number): SkillRun[];
-export type Summary = {
-    runs: number;
-    distinct: number;
-    files: number;
-    orphan: number;
-};
-export declare function summarize(events: AuditEvent[]): Summary;
 export declare function appendSkill(sessionID: string, input: {
     ts: string;
     name: string;
@@ -77,11 +22,6 @@ export declare function appendFile(sessionID: string, input: {
 export declare function parsePatch(args: unknown): string[];
 /** Second-precision UTC timestamp, matching `date -u +%FT%TZ` in logger.sh. */
 export declare function nowTs(date?: Date): string;
-export type SessionView = {
-    runs: SkillRun[];
-    summary: Summary;
-    cwd: string;
-};
 /**
  * Read one session's log. A missing or unreadable file is an empty session, not
  * an error: the sidebar renders before the first event is ever written.

package/dist/tui.js

@@ -7,11 +7,11 @@ import { createSignal, onCleanup } from "solid-js";
 import { appendFileSync, mkdirSync, readFileSync } from "fs";
 import { homedir } from "os";
 import { isAbsolute, join } from "path";
-function logDir() {
-  return process.env.SKILL_AUDIT_DIR || join(homedir(), ".claude", "skill-audit");
-}
-function logPath(sessionID) {
-  return join(logDir(), `${sessionID}.ndjson`);
+
+// src/core.ts
+function env(name) {
+  const host = globalThis;
+  return host.process?.env?.[name];
 }
 function parse(text) {
   const events = [];
@@ -31,9 +31,12 @@ function parse(text) {
 }
 var NO_SKILL = "(no skill active)";
 var DEFAULT_IDLE_GAP_MS = 30 * 60000;
+function idleGapFrom(minutes) {
+  const value = Number(minutes);
+  return Number.isFinite(value) && value > 0 ? value * 60000 : DEFAULT_IDLE_GAP_MS;
+}
 function idleGapMs() {
-  const minutes = Number(process.env.SKILL_AUDIT_IDLE_MINUTES);
-  return Number.isFinite(minutes) && minutes > 0 ? minutes * 60000 : DEFAULT_IDLE_GAP_MS;
+  return idleGapFrom(env("SKILL_AUDIT_IDLE_MINUTES"));
 }
 function epoch(ts) {
   return new Date(ts).getTime();
@@ -69,7 +72,7 @@ function group(events, gapMs = idleGapMs()) {
   }
   return runs;
 }
-function summarize(events) {
+function summarize(events, gapMs = idleGapMs()) {
   const names = [];
   const paths = new Set;
   for (const event of events) {
@@ -79,7 +82,7 @@ function summarize(events) {
       paths.add(event.path);
     }
   }
-  const orphan = group(events).filter((run) => run.skill === NO_SKILL).reduce((total, run) => total + run.files.length, 0);
+  const orphan = group(events, gapMs).filter((run) => run.skill === NO_SKILL).reduce((total, run) => total + run.files.length, 0);
   return {
     runs: names.length,
     distinct: new Set(names).size,
@@ -87,34 +90,41 @@ function summarize(events) {
     orphan
   };
 }
-var EMPTY = {
-  runs: [],
-  summary: {
-    runs: 0,
-    distinct: 0,
-    files: 0,
-    orphan: 0
-  },
-  cwd: ""
-};
+function toView(text, gapMs = idleGapMs()) {
+  const events = parse(text);
+  const cwd = events.find((event) => event.cwd)?.cwd ?? "";
+  return {
+    runs: group(events, gapMs),
+    summary: summarize(events, gapMs),
+    cwd
+  };
+}
+function baseName(path) {
+  const trimmed = path.replace(/\/+$/, "");
+  return trimmed.slice(trimmed.lastIndexOf("/") + 1);
+}
+function relativeTo(path, cwd) {
+  return cwd && path.startsWith(`${cwd}/`) ? path.slice(cwd.length + 1) : path;
+}
+
+// src/log.ts
+function logDir() {
+  return process.env.SKILL_AUDIT_DIR || join(homedir(), ".claude", "skill-audit");
+}
+function logPath(sessionID) {
+  return join(logDir(), `${sessionID}.ndjson`);
+}
 function readSession(sessionID) {
   let text;
   try {
     text = readFileSync(logPath(sessionID), "utf8");
   } catch {
-    return EMPTY;
+    text = "";
   }
-  const events = parse(text);
-  const cwd = events.find((event) => event.cwd)?.cwd ?? "";
-  return {
-    runs: group(events),
-    summary: summarize(events),
-    cwd
-  };
+  return toView(text);
 }
 
 // src/view.ts
-import { basename, relative } from "path";
 var TEXT_ICONS = {
   run: "\xB7",
   file: "\u270E",
@@ -129,8 +139,11 @@ var EMOJI_ICONS = {
   open: "\u25BC",
   closed: "\u25B6"
 };
+function iconsFor(style) {
+  return style === "emoji" ? EMOJI_ICONS : TEXT_ICONS;
+}
 function icons() {
-  return process.env.SKILL_AUDIT_ICONS === "emoji" ? EMOJI_ICONS : TEXT_ICONS;
+  return iconsFor(env("SKILL_AUDIT_ICONS"));
 }
 function pad(value) {
   return String(value).padStart(2, "0");
@@ -168,30 +181,27 @@ function bucketByHour(files) {
   }
   return buckets;
 }
-function headerLine(summary) {
-  const icon = icons();
+function headerLine(summary, icon = icons()) {
   const counts = `${icon.run}${summary.runs} ${icon.file}${summary.files}${summary.orphan > 0 ? ` ${icon.warn}${summary.orphan}` : ""}`;
   return `Skill audit  ${counts}`;
 }
-function runTitle(run, collapsed) {
-  const icon = icons();
+function runTitle(run, collapsed, icon = icons()) {
   const name = run.skill === NO_SKILL ? `${icon.warn} no skill` : shortName(run.skill);
   if (run.files.length === 0) {
     return `  ${name}`;
   }
   return collapsed ? `${icon.closed} ${name} (${run.files.length})` : `${icon.open} ${name}`;
 }
-function hourTitle(bucket, collapsed) {
-  const icon = icons();
+function hourTitle(bucket, collapsed, icon = icons()) {
   const marker = collapsed ? icon.closed : icon.open;
   return `${marker} ${bucket.hour} (${bucket.files.length})`;
 }
 function displayPath(path, cwd, width) {
-  const rel = cwd && path.startsWith(`${cwd}/`) ? relative(cwd, path) : path;
+  const rel = relativeTo(path, cwd);
   if (rel.length <= width) {
     return rel;
   }
-  const base = basename(rel);
+  const base = baseName(rel);
   if (base.length <= width) {
     return base;
   }
@@ -206,11 +216,11 @@ function hourKeyOf(index, bucket) {
   return `${runKey(index)}/hour:${bucket.day} ${bucket.hour}`;
 }
 function sidebarLines(view, options) {
-  const icon = icons();
+  const icon = options.icons ?? icons();
   const marker = options.sectionOpen ? icon.open : icon.closed;
   const lines = [
     {
-      text: `${marker} ${headerLine(view.summary)}`,
+      text: `${marker} ${headerLine(view.summary, icon)}`,
       tone: "text"
     }
   ];
@@ -228,7 +238,7 @@ function sidebarLines(view, options) {
     const key = runKey(index);
     const runCollapsed = options.collapsed.has(key);
     lines.push({
-      text: runTitle(run, runCollapsed),
+      text: runTitle(run, runCollapsed, icon),
       tone: run.skill === NO_SKILL ? "warning" : "accent",
       key
     });
@@ -239,7 +249,7 @@ function sidebarLines(view, options) {
       const bucketKey = hourKeyOf(index, bucket);
       const hourCollapsed = options.collapsed.has(bucketKey);
       lines.push({
-        text: `${HOUR_INDENT}${hourTitle(bucket, hourCollapsed)}`,
+        text: `${HOUR_INDENT}${hourTitle(bucket, hourCollapsed, icon)}`,
         tone: "text",
         key: bucketKey
       });

package/dist/view.d.ts

@@ -1,4 +1,4 @@
-import { type SessionView, type SkillRun, type Summary, type TimelineFile } from "./log";
+import { type SessionView, type SkillRun, type Summary, type TimelineFile } from "./core";
 export type IconSet = {
     run: string;
     file: string;
@@ -6,6 +6,8 @@ export type IconSet = {
     open: string;
     closed: string;
 };
+/** The icon set for a `SKILL_AUDIT_ICONS` value; anything but `emoji` is the text set. */
+export declare function iconsFor(style: string | undefined): IconSet;
 export declare function icons(): IconSet;
 export declare function hhmm(ts: string): string;
 /** The local hour a timestamp belongs to, as a bucket label. */
@@ -24,10 +26,10 @@ export type HourBucket = {
  * folding a day's gap into one row.
  */
 export declare function bucketByHour(files: TimelineFile[]): HourBucket[];
-export declare function headerLine(summary: Summary): string;
+export declare function headerLine(summary: Summary, icon?: IconSet): string;
 /** The skill name leads the row; its times live on the hour buckets below it. */
-export declare function runTitle(run: SkillRun, collapsed: boolean): string;
-export declare function hourTitle(bucket: HourBucket, collapsed: boolean): string;
+export declare function runTitle(run: SkillRun, collapsed: boolean, icon?: IconSet): string;
+export declare function hourTitle(bucket: HourBucket, collapsed: boolean, icon?: IconSet): string;
 /**
  * Fit a path into the sidebar: relative to the session directory, then the
  * basename, then a truncated basename.
@@ -47,6 +49,8 @@ export type SidebarOptions = {
     collapsed: Set<string>;
     /** Usable sidebar width, in columns. */
     width: number;
+    /** Icons to draw with; the environment's set when omitted. */
+    icons?: IconSet;
 };
 export declare function runKey(index: number): string;
 export declare function hourKeyOf(index: number, bucket: HourBucket): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skill-audit",
-  "version": "0.1.2",
+  "version": "0.2.0-dev.pr3.36976113543",
   "description": "Audit trail of skill invocations and file changes, with a live timeline in the opencode sidebar",
   "type": "module",
   "license": "MIT",
@@ -40,16 +40,18 @@
   ],
   "scripts": {
     "clean": "rm -rf dist",
-    "format": "prettier --write src test package.json tsconfig.json tsconfig.test.json eslint.config.js .github/workflows/ci.yml",
-    "format:check": "prettier --check src test package.json tsconfig.json tsconfig.test.json eslint.config.js .github/workflows/ci.yml",
+    "format": "prettier --write src test hooks/claude.tsx hooks/claude.test.tsx types package.json tsconfig.json tsconfig.test.json tsconfig.claude.json eslint.config.js .github/workflows/ci.yml",
+    "format:check": "prettier --check src test hooks/claude.tsx hooks/claude.test.tsx types package.json tsconfig.json tsconfig.test.json tsconfig.claude.json eslint.config.js .github/workflows/ci.yml",
     "lint": "eslint src test",
     "build:types": "tsc --emitDeclarationOnly",
     "build:index": "bun build src/index.ts --outfile dist/index.js --target bun --format esm --external @opencode-ai/plugin --external @opencode-ai/sdk",
     "build:tui": "bun build src/tui.ts --outfile dist/tui.js --target bun --format esm --external @opencode-ai/plugin --external @opencode-ai/sdk --external @opentui/core --external @opentui/solid --external solid-js",
     "build": "bun run clean && bun run build:types && bun run build:index && bun run build:tui",
     "test": "TZ=UTC bun test && TZ=UTC ./test/format-contract.sh",
+    "test:claude": "./test/claude-pane.sh",
     "typecheck": "tsc --noEmit",
     "typecheck:test": "tsc -p tsconfig.test.json",
+    "typecheck:claude": "tsc -p tsconfig.claude.json",
     "check": "bun run format:check && bun run lint && bun run typecheck && bun run typecheck:test && TZ=UTC bun test && TZ=UTC ./test/format-contract.sh",
     "check:versions": "node scripts/sync-versions.mjs --check",
     "sync:versions": "node scripts/sync-versions.mjs",