opencode-skill-audit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sven Depickere
+
+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

@@ -0,0 +1,367 @@
+# skill-audit
+
+[![CI](https://github.com/DepickereSven/skill-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/DepickereSven/skill-audit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Deterministic audit trail for [Claude Code](https://code.claude.com),
+[Codex](https://developers.openai.com/codex/) and [opencode](https://opencode.ai) sessions: which
+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.
+
+```text
+● Skill audit — f3a91c2e · ~/Dev/Web · 14:02→14:20 UTC
+
+  14:02 ⚡ superpowers:brainstorming
+  14:05 ⚡ superpowers:test-driven-development
+  14:06 │  ✎ src/auth/token.ts  Edit
+  14:09 │  ✎ src/auth/token.test.ts  Write
+  14:20 ⚠ (no skill active)
+  14:20 │  ✎ src/index.ts  Edit
+
+● 2 skill runs (2 distinct) · 3 files touched · ⚠ 1 edits outside skill context
+```
+
+## Why
+
+You ask an agent to follow a skill. Did it? Reading the transcript to find out is slow, and asking
+another model to judge costs tokens and is itself non-deterministic.
+
+LLMs are not deterministic; hook events are. This plugin logs the facts exposed by each host's
+documented hook API:
+
+- **No LLM judging, no tokens.** Everything except the two in-session slash/skill commands runs
+  entirely outside the model.
+- **No transcript parsing.** Only documented hook payloads, so nothing silently breaks on a
+  transcript format change.
+- **One data model across three hosts.** The NDJSON log is the only contract, so the CLI reads
+  opencode sessions and the opencode sidebar reads Claude Code sessions.
+- **The red flag is a number.** `⚠ edits outside skill context` counts files changed while no
+  observable skill was active.
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Install](#install)
+- [Verify the install](#verify-the-install)
+- [Usage](#usage)
+- [Data format](#data-format)
+- [Troubleshooting](#troubleshooting)
+- [Honest limitations](#honest-limitations)
+- [Uninstall](#uninstall)
+- [Requirements](#requirements)
+- [Development](#development)
+- [License](#license)
+
+## How it works
+
+`PostToolUse` hooks capture skill-tool calls and file edits. On Codex, a `UserPromptSubmit` hook
+also captures explicit `$skill-name` references, and `apply_patch` payloads are expanded into one
+file event per path. On opencode a plugin does the same job through the `tool.execute.after` hook.
+Events are appended as NDJSON to `~/.claude/skill-audit/<session_id>.ndjson`; override the location
+with `SKILL_AUDIT_DIR`.
+
+```text
+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)
+```
+
+The log is the only contract between the writers and the viewers, so the CLI reads opencode
+sessions and the opencode sidebar reads Claude Code sessions.
+
+Subagent hook calls use the parent session ID, so delegated edits appear in the same audit.
+
+## Install
+
+### Claude Code
+
+```text
+/plugin marketplace add DepickereSven/skill-audit
+/plugin install skill-audit@depickeresven-skill-audit
+```
+
+Restart Claude Code so the hooks load.
+
+> **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.
+
+### Codex
+
+```bash
+codex plugin marketplace add DepickereSven/skill-audit
+codex plugin add skill-audit@depickeresven-skill-audit
+```
+
+Start a new Codex session after installation. Codex asks you to review and trust plugin-bundled
+hooks before they run. Plugins are available in Codex CLI and the ChatGPT desktop app's Codex
+surface, but not in the IDE extension. See the official
+[plugin](https://developers.openai.com/codex/plugins/build) and
+[hook](https://developers.openai.com/codex/hooks) documentation.
+
+Invoke the bundled Codex skill with `$skill-audit`.
+
+### opencode
+
+```bash
+opencode plugin opencode-skill-audit --global
+```
+
+Restart opencode so the plugin loads. It registers two things: a server hook that logs
+`skill`, `edit`, `write` and `apply_patch` tool calls, and a sidebar section that renders the
+current session's timeline live.
+
+
+![OpenCode Image](docs/opencode.png)
+
+Click the header to collapse the section, or a skill row to fold its files away.
+
+opencode discovers skills natively, including from `.claude/skills/` and `.agents/skills/`, so
+skills you already use are logged without moving them. To get the in-session report as well, link
+the bundled skill into a directory opencode scans:
+
+```bash
+ln -sf "$PWD/skills/skill-audit" ~/.config/opencode/skills/skill-audit
+```
+
+### CLI on your PATH (recommended)
+
+The viewer works from any terminal. Link the installed script somewhere on your PATH.
+
+Claude Code:
+
+```bash
+ln -sf ~/.claude/plugins/cache/*/skill-audit/*/scripts/skill-audit ~/.local/bin/skill-audit
+```
+
+Codex:
+
+```bash
+ln -sf ~/.codex/plugins/cache/*/skill-audit/*/scripts/skill-audit ~/.local/bin/skill-audit
+```
+
+You can also clone this repository and link `scripts/skill-audit` directly.
+
+`~/.local/bin` is not on every system's `PATH`. Check with `command -v skill-audit`; if it prints
+nothing, add the directory in your shell profile:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### Claude Code statusline segment (optional)
+
+Plugins cannot modify your statusline. Add this to your own statusline script to get a live
+`⚡2 ✎5 tdd` segment:
+
+```sh
+sid=$(echo "$input" | jq -r '.session_id // empty')
+audit_log="$HOME/.claude/skill-audit/$sid.ndjson"
+if [ -n "$sid" ] && [ -s "$audit_log" ]; then
+  audit=$(jq -rs '
+    [ .[] | select(.kind=="skill") ] as $s
+    | ([ .[] | select(.kind=="file") | .path ] | unique | length) as $f
+    | "⚡\($s|length) ✎\($f)"
+      + (if ($s|length) > 0 then " " + ($s[-1].name | split(":") | last) else "" end)
+  ' "$audit_log" 2>/dev/null)
+  [ -n "$audit" ] && parts="$parts | $audit"
+fi
+```
+
+## Verify the install
+
+Hooks that never fire look exactly like a session with no skill usage, so confirm once after
+installing.
+
+1. In a **new** session on the host you installed, invoke any skill and edit one file. Invoking
+   this plugin's own skill is enough:
+   - Claude Code: `/skill-audit`
+   - Codex: `$skill-audit`
+   - opencode: watch the sidebar section appear
+2. Check that a log exists and is growing:
+
+   ```bash
+   ls -la ~/.claude/skill-audit/
+   ```
+
+3. Read it back from any terminal:
+
+   ```bash
+   skill-audit list      # sessions, newest first
+   skill-audit status    # counts + recent timeline for the newest session
+   ```
+
+If `list` prints `no session logs in ...`, nothing was written — go to
+[Troubleshooting](#troubleshooting).
+
+## Usage
+
+| Command                    | What                                                             |     Tokens |
+|----------------------------|------------------------------------------------------------------|-----------:|
+| `skill-audit status [sid]` | Compact counts and recent timeline                               |          0 |
+| `skill-audit report [sid]` | Full timeline                                                    |          0 |
+| `skill-audit watch [sid]`  | Live view, refreshed every two seconds; `q` quits                |          0 |
+| `skill-audit list`         | Recent sessions                                                  |          0 |
+| `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 |
+| `/skill-audit`             | Show the report inside Claude Code                               | Model turn |
+| `$skill-audit`             | Show the report inside Codex                                     | Model turn |
+
+`status`, `report` and `watch` all take an optional session ID. Without one they use the most
+recently modified log, which is the wrong session if you run several at once — get the ID from
+`skill-audit list` and pass it explicitly.
+
+The `⚠ edits outside skill context` counter is the compliance red flag: files changed while no
+observable skill was active.
+
+## Data format
+
+One NDJSON file per session, one event per line, appended in chronological order:
+
+```json
+{"ts":"2026-07-10T14:05:11Z","kind":"skill","name":"superpowers:test-driven-development","args":"","cwd":"/Users/me/proj","source":"tool"}
+{"ts":"2026-07-10T14:06:40Z","kind":"file","tool":"apply_patch","path":"/Users/me/proj/src/auth/token.ts","cwd":"/Users/me/proj"}
+```
+
+| Field     | On      | Meaning                                                                       |
+|-----------|---------|-------------------------------------------------------------------------------|
+| `ts`      | both    | UTC timestamp, `YYYY-MM-DDThh:mm:ssZ`                                         |
+| `kind`    | both    | `skill` or `file` — the only two event kinds                                  |
+| `cwd`     | both    | Session working directory as reported by the host                             |
+| `name`    | `skill` | Skill identifier, e.g. `superpowers:test-driven-development`                  |
+| `args`    | `skill` | Arguments passed to the skill tool; empty string when there were none         |
+| `source`  | `skill` | `tool` for an observed skill tool call, `prompt` for a Codex `$skill-name`    |
+| `turn_id` | `skill` | Codex turn identifier; present only when the host supplies one                |
+| `tool`    | `file`  | Tool that made the edit: `Edit`, `Write`, `NotebookEdit`, `apply_patch`…      |
+| `path`    | `file`  | Absolute path of the changed file (relative paths are resolved against `cwd`) |
+
+Within a Codex turn, a repeated `(turn_id, name)` skill pair is written once, so a skill named
+several times in one prompt does not inflate the counts.
+
+The format is open, so you can build other viewers on top. Prune old logs with:
+
+```bash
+find ~/.claude/skill-audit -name '*.ndjson' -mtime +30 -delete
+```
+
+## Troubleshooting
+
+**Nothing is logged / `no session logs in ...`**
+
+- Did you restart the host after installing? Hooks and plugins load at startup, and an existing
+  session keeps running without them.
+- Confirm the plugin is installed: `claude plugin list`, `codex plugin list`, or check the
+  `plugin` array in `~/.config/opencode/opencode.json`.
+- On Codex, hooks only run after you review and trust them — accept the prompt.
+- Is `jq` installed? `logger.sh` exits silently without it, by design: the hook must never block a
+  session. Check with `command -v jq`.
+
+**Every event appears twice.** A manual `logger.sh` entry is still in the `hooks` block of
+`~/.claude/settings.json` alongside the plugin's. Remove the manual one.
+
+**The CLI shows an empty or unrelated session.** Without an argument the viewer picks the most
+recently modified log, which is the wrong one when sessions run in parallel. Run `skill-audit list`
+and pass the ID: `skill-audit report <sid>`.
+
+**The CLI finds nothing but the logs exist.** Writer and viewer disagree about the directory. If
+you set `SKILL_AUDIT_DIR` for the host, export it for your shell too — otherwise the CLI looks in
+`~/.claude/skill-audit`.
+
+**`skill-audit: command not found`.** The symlink is missing or its directory is not on `PATH`;
+see [CLI on your PATH](#cli-on-your-path-recommended).
+
+**A skill ran but is missing from the timeline.** Expected in some cases — see
+[Honest limitations](#honest-limitations).
+
+## Honest limitations
+
+- **Invocation is not compliance.** The log proves that a skill was explicitly selected or exposed
+  as a tool event, not that the result followed every instruction.
+- **Codex automatic skill loading is not a hook event today.** Explicit `$skill-name` references
+  are captured; skills that Codex chooses automatically are not. No transcript parsing is used to
+  fill that gap.
+- **Prompt-sourced entries are syntax-level evidence.** Codex supplies plain prompt text to the
+  hook, so a lower-case dollar-prefixed token can be logged even if it does not resolve to an
+  installed skill. The NDJSON `source: "prompt"` field distinguishes these entries.
+- **Only observable file tools are captured.** Claude `Edit`/`Write`/`NotebookEdit`, Codex
+  `apply_patch`, and opencode `edit`/`write`/`apply_patch` edits are logged. Files created
+  indirectly by shell commands are not visible as separate file events.
+- **opencode agents and subagents are not logged.** They have no equivalent on the other two
+  hosts, so logging them would add an event kind only one host can emit. The audit keeps one data
+  model across all three.
+- **Session-start injected skills** are context, not skill tool calls, and do not appear.
+- **Concurrent sessions:** the newest-log default can pick the wrong session; pass the session ID
+  explicitly after using `skill-audit list`.
+
+## Uninstall
+
+Claude Code:
+
+```bash
+claude plugin uninstall skill-audit@depickeresven-skill-audit
+```
+
+Codex:
+
+```bash
+codex plugin remove skill-audit@depickeresven-skill-audit
+```
+
+opencode has no removal subcommand — delete the `"opencode-skill-audit"` entry from the `plugin`
+array in `~/.config/opencode/opencode.json` (or the project-local `opencode.json`), and remove the
+skill symlink if you made one:
+
+```bash
+rm -f ~/.config/opencode/skills/skill-audit
+```
+
+Then restart the host. Finally, clean up the CLI symlink and the logs, which no uninstall touches:
+
+```bash
+rm -f ~/.local/bin/skill-audit
+rm -rf ~/.claude/skill-audit
+```
+
+## Requirements
+
+- macOS or Linux
+- `bash` and `jq` for the CLI viewer and the Claude Code / Codex hooks
+- opencode `>= 1.14` for the plugin and its sidebar
+
+## Development
+
+The hooks and the CLI viewer are plain bash (`scripts/`) with no build step. The opencode plugin
+and sidebar are TypeScript (`src/`) built with [Bun](https://bun.sh).
+
+```bash
+bun install
+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
+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.
+
+Version bumps go through `npm version`, which runs `scripts/sync-versions.mjs` and stages
+`.claude-plugin/plugin.json` and `.codex-plugin/plugin.json` alongside it. CI (`.github/workflows/ci.yml`)
+runs `bun run check` plus a manifest-version job on every push and pull request.
+
+## License
+
+[MIT](LICENSE) © Sven Depickere

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from "@opencode-ai/plugin";
+/**
+ * Server plugin: turns completed tool calls into audit events.
+ *
+ * The equivalent of the PostToolUse hooks the plugin registers on Claude Code
+ * and Codex, writing the same NDJSON log those hosts write.
+ */
+export declare const SkillAuditServer: Plugin;
+declare const _default: {
+    id: string;
+    server: Plugin;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,126 @@
+// @bun
+// src/log.ts
+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`);
+}
+function append(sessionID, event) {
+  try {
+    mkdirSync(logDir(), { recursive: true });
+    appendFileSync(logPath(sessionID), `${JSON.stringify(event)}
+`);
+  } catch {
+    return;
+  }
+}
+function appendSkill(sessionID, input) {
+  if (!input.name)
+    return;
+  append(sessionID, {
+    ts: input.ts,
+    kind: "skill",
+    name: input.name,
+    args: "",
+    cwd: input.cwd,
+    source: "tool"
+  });
+}
+function appendFile(sessionID, input) {
+  if (!input.path || input.path === "/dev/null") {
+    return;
+  }
+  const path = isAbsolute(input.path) || !input.cwd ? input.path : join(input.cwd, input.path);
+  append(sessionID, {
+    ts: input.ts,
+    kind: "file",
+    tool: input.tool,
+    path,
+    cwd: input.cwd
+  });
+}
+function parsePatch(args) {
+  const patchText = typeof args === "string" ? args : typeof args?.patchText === "string" ? args.patchText : typeof args?.patch === "string" ? args.patch : "";
+  const paths = [];
+  for (const line of patchText.split(`
+`)) {
+    const match = /^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)$/.exec(line.trim());
+    const path = match?.[1]?.trim();
+    if (path && !paths.includes(path)) {
+      paths.push(path);
+    }
+  }
+  return paths;
+}
+function nowTs(date = new Date) {
+  return `${date.toISOString().slice(0, 19)}Z`;
+}
+
+// src/record.ts
+var FILE_TOOLS = new Set(["edit", "write", "multiedit"]);
+var PATCH_TOOLS = new Set(["apply_patch", "patch"]);
+function stringField(args, key) {
+  const value = args?.[key];
+  return typeof value === "string" ? value : "";
+}
+function record(call, cwd) {
+  try {
+    const { tool, sessionID, args } = call;
+    const ts = nowTs();
+    if (tool === "skill") {
+      appendSkill(sessionID, {
+        ts,
+        name: stringField(args, "name") || stringField(args, "skill"),
+        cwd
+      });
+      return;
+    }
+    if (FILE_TOOLS.has(tool)) {
+      appendFile(sessionID, {
+        ts,
+        tool,
+        path: stringField(args, "filePath"),
+        cwd
+      });
+      return;
+    }
+    if (PATCH_TOOLS.has(tool)) {
+      for (const path of parsePatch(args)) {
+        appendFile(sessionID, {
+          ts,
+          tool,
+          path,
+          cwd
+        });
+      }
+    }
+  } catch {
+    return;
+  }
+}
+
+// src/index.ts
+var SkillAuditServer = async ({ directory, worktree }) => {
+  const cwd = directory || worktree || process.cwd();
+  return {
+    "tool.execute.after": async ({ tool, sessionID, args }) => {
+      record({
+        tool,
+        sessionID,
+        args
+      }, cwd);
+    }
+  };
+};
+var src_default = {
+  id: "skill-audit",
+  server: SkillAuditServer
+};
+export {
+  SkillAuditServer,
+  src_default as default
+};

package/dist/log.d.ts

@@ -0,0 +1,77 @@
+/** 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[];
+};
+/**
+ * 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.
+ */
+export declare function group(events: AuditEvent[]): 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;
+    cwd: string;
+}): void;
+export declare function appendFile(sessionID: string, input: {
+    ts: string;
+    tool: string;
+    path: string;
+    cwd: string;
+}): void;
+/**
+ * Extract touched paths from an apply_patch payload. opencode uses the same
+ * `*** Begin Patch` envelope as Codex, so this mirrors the sed parsing in
+ * logger.sh. Duplicates are collapsed, order of first appearance kept.
+ */
+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.
+ */
+export declare function readSession(sessionID: string): SessionView;

package/dist/record.d.ts

@@ -0,0 +1,10 @@
+export type ToolCall = {
+    tool: string;
+    sessionID: string;
+    args: unknown;
+};
+/**
+ * Map one completed opencode tool call onto audit events. Never throws: a hook
+ * that disturbs the session is worse than a missing log line.
+ */
+export declare function record(call: ToolCall, cwd: string): void;

package/dist/tui.d.ts

@@ -0,0 +1,7 @@
+import type { TuiPlugin } from "@opencode-ai/plugin/tui";
+export declare const tui: TuiPlugin;
+declare const _default: {
+    id: string;
+    tui: TuiPlugin;
+};
+export default _default;

package/dist/tui.js

@@ -0,0 +1,307 @@
+// @bun
+// src/tui.ts
+import { createElement, insert, setProp } from "@opentui/solid";
+import { createSignal, onCleanup } from "solid-js";
+
+// src/log.ts
+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`);
+}
+function parse(text) {
+  const events = [];
+  for (const line of text.split(`
+`)) {
+    if (!line.trim()) {
+      continue;
+    }
+    try {
+      const event = JSON.parse(line);
+      if (event?.kind === "skill" || event?.kind === "file") {
+        events.push(event);
+      }
+    } catch {}
+  }
+  return events;
+}
+var NO_SKILL = "(no skill active)";
+function group(events) {
+  const runs = [];
+  for (const event of events) {
+    if (event.kind === "skill") {
+      runs.push({
+        skill: event.name,
+        ts: event.ts,
+        files: []
+      });
+      continue;
+    }
+    if (runs.length === 0) {
+      runs.push({
+        skill: NO_SKILL,
+        ts: event.ts,
+        files: []
+      });
+    }
+    runs[runs.length - 1].files.push({
+      ts: event.ts,
+      tool: event.tool,
+      path: event.path
+    });
+  }
+  return runs;
+}
+function summarize(events) {
+  const names = [];
+  const paths = new Set;
+  for (const event of events) {
+    if (event.kind === "skill") {
+      names.push(event.name);
+    } else {
+      paths.add(event.path);
+    }
+  }
+  const orphan = group(events).filter((run) => run.skill === NO_SKILL).reduce((total, run) => total + run.files.length, 0);
+  return {
+    runs: names.length,
+    distinct: new Set(names).size,
+    files: paths.size,
+    orphan
+  };
+}
+var EMPTY = {
+  runs: [],
+  summary: {
+    runs: 0,
+    distinct: 0,
+    files: 0,
+    orphan: 0
+  },
+  cwd: ""
+};
+function readSession(sessionID) {
+  let text;
+  try {
+    text = readFileSync(logPath(sessionID), "utf8");
+  } catch {
+    return EMPTY;
+  }
+  const events = parse(text);
+  const cwd = events.find((event) => event.cwd)?.cwd ?? "";
+  return {
+    runs: group(events),
+    summary: summarize(events),
+    cwd
+  };
+}
+
+// src/view.ts
+import { basename, relative } from "path";
+function hhmm(ts) {
+  return ts.slice(11, 16);
+}
+function shortName(name) {
+  const parts = name.split(":");
+  return parts[parts.length - 1] || name;
+}
+function headerLine(summary) {
+  const counts = `\u26A1${summary.runs} \u270E${summary.files}${summary.orphan > 0 ? ` \u26A0${summary.orphan}` : ""}`;
+  return `Skill audit  ${counts}`;
+}
+function runTitle(run, collapsed) {
+  const time = hhmm(run.ts);
+  if (run.skill === NO_SKILL) {
+    return `\u26A0 ${time} no skill`;
+  }
+  const name = shortName(run.skill);
+  if (run.files.length === 0) {
+    return `  ${time} ${name}`;
+  }
+  return collapsed ? `\u25B6 ${time} ${name} (${run.files.length})` : `\u25BC ${time} ${name}`;
+}
+function displayPath(path, cwd, width) {
+  const rel = cwd && path.startsWith(`${cwd}/`) ? relative(cwd, path) : path;
+  if (rel.length <= width) {
+    return rel;
+  }
+  const base = basename(rel);
+  if (base.length <= width) {
+    return base;
+  }
+  return `${base.slice(0, Math.max(0, width - 1))}\u2026`;
+}
+var FILE_INDENT = "     \u270E ";
+function sidebarLines(view, options) {
+  const marker = options.sectionOpen ? "\u25BC" : "\u25B6";
+  const lines = [
+    {
+      text: `${marker} ${headerLine(view.summary)}`,
+      tone: "text"
+    }
+  ];
+  if (!options.sectionOpen) {
+    return lines;
+  }
+  if (view.runs.length === 0) {
+    lines.push({
+      text: "  no events yet",
+      tone: "muted"
+    });
+    return lines;
+  }
+  view.runs.forEach((run, index) => {
+    const collapsed = options.collapsed.has(index);
+    lines.push({
+      text: runTitle(run, collapsed),
+      tone: run.skill === NO_SKILL ? "warning" : "accent",
+      runIndex: index
+    });
+    if (collapsed) {
+      return;
+    }
+    for (const file of run.files) {
+      lines.push({
+        text: `${FILE_INDENT}${displayPath(file.path, view.cwd, options.width - FILE_INDENT.length)}`,
+        tone: "muted"
+      });
+    }
+  });
+  return lines;
+}
+
+// src/watch.ts
+import { statSync, watch } from "fs";
+function mtime(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+function watchSession(sessionID, onChange, options = {}) {
+  const debounceMs = options.debounceMs ?? 100;
+  const pollMs = options.pollMs ?? 2000;
+  const path = logPath(sessionID);
+  let last = mtime(path);
+  let timer;
+  let stopped = false;
+  const fire = () => {
+    if (stopped) {
+      return;
+    }
+    const current = mtime(path);
+    if (current === last) {
+      return;
+    }
+    last = current;
+    onChange();
+  };
+  const schedule = () => {
+    if (stopped) {
+      return;
+    }
+    clearTimeout(timer);
+    timer = setTimeout(fire, debounceMs);
+  };
+  let watcher;
+  try {
+    watcher = watch(logDir(), schedule);
+  } catch {
+    watcher = undefined;
+  }
+  const poll = setInterval(fire, pollMs);
+  return () => {
+    stopped = true;
+    clearTimeout(timer);
+    clearInterval(poll);
+    watcher?.close();
+  };
+}
+
+// src/tui.ts
+var ORDER = 800;
+var DEFAULT_WIDTH = 30;
+function element(tag, props, children = []) {
+  const node = createElement(tag);
+  for (const [key, value] of Object.entries(props)) {
+    if (value !== undefined) {
+      setProp(node, key, value);
+    }
+  }
+  for (const child of children) {
+    if (child !== null && child !== undefined && child !== false) {
+      insert(node, child);
+    }
+  }
+  return node;
+}
+function toneColor(theme, tone) {
+  if (tone === "accent") {
+    return theme.accent;
+  }
+  if (tone === "warning") {
+    return theme.warning;
+  }
+  if (tone === "muted") {
+    return theme.textMuted;
+  }
+  return theme.text;
+}
+function toggle(set, index) {
+  const next = new Set(set);
+  if (!next.delete(index)) {
+    next.add(index);
+  }
+  return next;
+}
+function Section(api, sessionID, width) {
+  const [view, setView] = createSignal(readSession(sessionID));
+  const [sectionOpen, setSectionOpen] = createSignal(true);
+  const [collapsed, setCollapsed] = createSignal(new Set);
+  const redraw = () => api.renderer.requestRender();
+  onCleanup(watchSession(sessionID, () => {
+    setView(readSession(sessionID));
+    redraw();
+  }));
+  const rows = () => sidebarLines(view(), {
+    sectionOpen: sectionOpen(),
+    collapsed: new Set(collapsed()),
+    width
+  }).map((line, index) => {
+    const onMouseDown = index === 0 ? () => {
+      setSectionOpen((open) => !open);
+      redraw();
+    } : line.runIndex !== undefined ? () => {
+      setCollapsed((current) => toggle(current, line.runIndex));
+      redraw();
+    } : undefined;
+    return element("text", {
+      fg: toneColor(api.theme.current, line.tone),
+      onMouseDown
+    }, [line.text]);
+  });
+  return element("box", {
+    width: "100%",
+    flexDirection: "column"
+  }, [rows]);
+}
+var tui = async (api, options) => {
+  const width = typeof options?.["width"] === "number" ? options["width"] : DEFAULT_WIDTH;
+  api.slots.register({
+    order: ORDER,
+    slots: { sidebar_content: (_ctx, props) => Section(api, props.session_id, width) }
+  });
+};
+var tui_default = {
+  id: "skill-audit",
+  tui
+};
+export {
+  tui_default as default,
+  tui
+};

package/dist/view.d.ts

@@ -0,0 +1,30 @@
+import { type SessionView, type SkillRun, type Summary } from "./log";
+export declare function hhmm(ts: string): string;
+/** `superpowers:brainstorming` -> `brainstorming`, the way the statusline snippet does. */
+export declare function shortName(name: string): string;
+export declare function headerLine(summary: Summary): string;
+export declare function runTitle(run: SkillRun, collapsed: boolean): string;
+/**
+ * Fit a path into the sidebar: relative to the session directory, then the
+ * basename, then a truncated basename.
+ */
+export declare function displayPath(path: string, cwd: string, width: number): string;
+export type Tone = "text" | "muted" | "accent" | "warning";
+export type Line = {
+    text: string;
+    tone: Tone;
+    runIndex?: number;
+};
+export type SidebarOptions = {
+    /** Whether the whole section is expanded. */
+    sectionOpen: boolean;
+    /** Indices of runs whose files are hidden. */
+    collapsed: Set<number>;
+    /** Usable sidebar width, in columns. */
+    width: number;
+};
+/**
+ * The entire sidebar section as plain lines. Keeping layout here rather than in
+ * the OpenTUI glue means it can be tested without a terminal.
+ */
+export declare function sidebarLines(view: SessionView, options: SidebarOptions): Line[];

package/dist/watch.d.ts

@@ -0,0 +1,12 @@
+export type WatchOptions = {
+    debounceMs?: number;
+    pollMs?: number;
+};
+/**
+ * Call `onChange` when a session's log changes.
+ *
+ * Watches the log directory rather than the file, because the file does not
+ * exist until the session's first event. The interval is a fallback: fs.watch
+ * misses changes on some network and container filesystems.
+ */
+export declare function watchSession(sessionID: string, onChange: () => void, options?: WatchOptions): () => void;

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "opencode-skill-audit",
+  "version": "0.1.0",
+  "description": "Audit trail of skill invocations and file changes, with a live timeline in the opencode sidebar",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Sven Depickere",
+    "url": "https://github.com/DepickereSven"
+  },
+  "homepage": "https://github.com/DepickereSven/skill-audit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DepickereSven/skill-audit.git"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "audit",
+    "skills",
+    "sidebar",
+    "tui"
+  ],
+  "oc-plugin": [
+    "tui"
+  ],
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./tui": {
+      "import": "./dist/tui.js",
+      "types": "./dist/tui.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "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",
+    "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": "bun test && ./test/format-contract.sh",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json",
+    "check": "bun run format:check && bun run lint && bun run typecheck && bun run typecheck:test && bun test && ./test/format-contract.sh",
+    "check:versions": "node scripts/sync-versions.mjs --check",
+    "sync:versions": "node scripts/sync-versions.mjs",
+    "version": "node scripts/sync-versions.mjs && git add .claude-plugin/plugin.json .codex-plugin/plugin.json",
+    "prepublishOnly": "bun run check:versions && bun run check && bun run build"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.14.0",
+    "@opentui/core": ">=0.4.5",
+    "@opentui/solid": ">=0.4.5",
+    "solid-js": ">=1.9.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@opencode-ai/plugin": "1.18.23",
+    "@opentui/core": "0.4.5",
+    "@opentui/solid": "0.4.5",
+    "@types/bun": "latest",
+    "eslint": "^10.9.1",
+    "eslint-plugin-simple-import-sort": "^14.0.0",
+    "prettier": "^3.9.6",
+    "solid-js": "1.9.9",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.69.0"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  }
+}