### Local Development Install of Better Plugins

Source: https://github.com/johnlindquist/better-plugins/blob/main/README.md

Clone the repository, navigate to the directory, add the local path as a plugin marketplace, and then install the Toolsmith plugin.

```bash
git clone https://github.com/johnlindquist/better-plugins.git
cd better-plugins
codex plugin marketplace add "$PWD"
codex plugin add toolsmith@better-plugins

```

--------------------------------

### Install Toolsmith Plugin via Marketplace

Source: https://github.com/johnlindquist/better-plugins/blob/main/README.md

Add the Better Plugins marketplace and then install the Toolsmith plugin. Restart Codex after installation.

```bash
codex plugin marketplace add johnlindquist/better-plugins
codex plugin add toolsmith@better-plugins

```

--------------------------------

### Gemini Video Hook Activation Example

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/gemini-video/README.md

Example of how to activate the Gemini Video plugin by including the '#gemini-video' token in a prompt, followed by a command and a video path.

```text
#gemini-video summarize ~/Downloads/demo.mp4
```

--------------------------------

### Verify Human View Plugin Functionality

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/human-view/README.md

Simulates user prompts to test the Human View plugin's behavior, including opening panes, starting daemons, and updating content without reloads. This is used to verify the automated tests.

```bash
export HUMAN_VIEW_DATA=/tmp/human-view-test
SID=demo
DIR="$HUMAN_VIEW_DATA/sessions/$SID"

# 1) simulate a prompt WITH the trigger -> opens the pane + starts the daemon
echo '{"hook_event_name":"UserPromptSubmit","session_id":"'$SID'","prompt":"#human Add a CLI flag parser and tests"}' \
  | python3 hooks/human_view_hook.py

SURFACE=$(python3 -c 'import json;print(json.load(open("'"$DIR"'/meta.json"))["surface_ref"])')
cmux browser "$SURFACE" wait --load-state complete --timeout-ms 15000
cmux browser "$SURFACE" get text body          # shows the task title + "Working"

# 2) simulate a second prompt -> body changes WITHOUT any reload
echo '{"hook_event_name":"UserPromptSubmit","session_id":"'$SID'","prompt":"Now add an error-path test"}' \
  | python3 hooks/human_view_hook.py
sleep 2
cmux browser "$SURFACE" get text body          # changed content, no reload called
```

--------------------------------

### User-Level Hook Configuration

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/human-view/README.md

Configuration for wiring the human-view hook to Codex events in `~/.codex/config.toml`. This setup ensures the hook runs for prompt submissions, tool uses, and stop events.

```toml
[hooks]
UserPromptSubmit = [
  { hooks = [ { type = "command", command = "python3 \"/Users/johnlindquist/codex-workshop/sdk-investigation/human-view/hooks/human_view_hook.py\"", timeout = 8, statusMessage = "Updating human view" } ] }
]
PostToolUse = [
  { matcher = "*", hooks = [ { type = "command", command = "python3 \"/Users/johnlindquist/codex-workshop/sdk-investigation/human-view/hooks/human_view_hook.py\"", timeout = 5 } ] }
]
Stop = [
  { hooks = [ { type = "command", command = "python3 \"/Users/johnlindquist/codex-workshop/sdk-investigation/human-view/hooks/human_view_hook.py\"", timeout = 5 } ] }
]
```

--------------------------------

### Enable Plugin Hooks in Codex Configuration

Source: https://github.com/johnlindquist/better-plugins/blob/main/README.md

Ensure that plugin hooks are enabled in your Codex configuration file. This is a prerequisite for installing and using Better Plugins.

```toml
[features]
hooks = true
plugins = true
plugin_hooks = true

```

--------------------------------

### Run Toolsmith Doctor and Summary Checks

Source: https://github.com/johnlindquist/better-plugins/blob/main/README.md

Execute the 'doctor' command for health checks and the 'summary' command to get a report over a specified number of days.

```bash
python3 scripts/better_tools.py doctor
python3 scripts/better_tools.py summary --days 30

```

--------------------------------

### Toolsmith Hook Control Output

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/toolsmith/skills/toolsmith/SKILL.md

Example control-JSON objects emitted by the Toolsmith hook on stdout. These control the hook's behavior and output suppression.

```json
{"continue":true,"suppressOutput":true}
```

```json
{"continue":true}
```

--------------------------------

### Fetch and Process State Data

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/human-view/assets/index.html

Periodically fetches the latest task state from the server using a GET request. It updates the UI if the revision number has changed and displays a 'reconnecting' status if the fetch fails.

```javascript
async function poll() {
  try {
    const r = await fetch(`/state.json?token=${encodeURIComponent(token)}&t=${Date.now()}`, { cache: "no-store" });
    if (!r.ok) throw new Error("HTTP " + r.status);
    const state = await r.json();
    els.conn.classList.remove("bad");
    els.conn.textContent = "live";
    if (state.revision !== seen) {
      seen = state.revision;
      render(state);
    }
  } catch (e) {
    els.conn.classList.add("bad");
    els.conn.textContent = "reconnecting";
  }
}
poll();
setInterval(poll, 800);
})();
```

--------------------------------

### Inspect Project Files

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/toolsmith/skills/toolsmith/SKILL.md

Use standard shell commands to inspect the current project directory and identify relevant configuration or agent files. This helps in understanding the project's structure and dependencies.

```bash
pwd
ls
find .. -maxdepth 2 -name AGENTS.md -o -name package.json -o -name pyproject.toml -o -name Cargo.toml
```

--------------------------------

### Inspect Local CLI Tool Capabilities

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/toolsmith/skills/toolsmith/SKILL.md

For unfamiliar CLI tools, use harmless commands like --help or --version to inspect their capabilities without executing mutating commands. This is part of the research phase before recommending tools.

```bash
<tool> --help
<tool> help
<tool> --version
```

--------------------------------

### Architecture Diagram

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/human-view/README.md

Illustrates the flow of information and process spawning between user prompts, hooks, the daemon, and the browser view.

```text
UserPromptSubmit / PostToolUse / Stop
        │  (stdin JSON: session_id, hook_event_name, prompt, last_assistant_message…)
        ▼
hooks/human_view_hook.py        ← fast: mutate state.json, ensure daemon, print {"continue":true}
        │ spawns (detached, once) ──► daemon/human_view_daemon.py  (127.0.0.1:<ephemeral>)
        │ opens (once) ───────────► cmux new-pane --type browser --url http://127.0.0.1:<port>/?token=…
        ▼
state.json  ◄── served as /state.json ──►  assets/index.html  (polls every 800ms)
```

--------------------------------

### Initialize Elements and Constants

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/human-view/assets/index.html

Sets up DOM element references and defines constants for SVG shapes used in the UI. This code runs immediately when the script is loaded.

```javascript
(() => {
  const token = "__TOKEN__";
  const els = {
    title: document.getElementById("title"),
    phase: document.getElementById("phase"),
    detail: document.getElementById("detail"),
    detailCard: document.getElementById("detailCard"),
    prompt: document.getElementById("prompt"),
    summary: document.getElementById("summary"),
    summaryCard: document.getElementById("summaryCard"),
    timeline: document.getElementById("timeline"),
    rev: document.getElementById("rev"),
    updated: document.getElementById("updated"),
    conn: document.getElementById("conn"),
    glyph: document.getElementById("glyph"),
  };
  let seen = -1;
  const SHAPES = {
    spark: '<path d="M50 6 L58 42 L94 50 L58 58 L50 94 L42 58 L6 50 L42 42 Z" fill="currentColor"/>',
    orbit: '<circle cx="50" cy="50" r="10" fill="currentColor"/><ellipse cx="50" cy="50" rx="42" ry="18" stroke="currentColor" stroke-width="4" fill="none"/><ellipse cx="50" cy="50" rx="18" ry="42" stroke="currentColor" stroke-width="4" fill="none"/>',
    stack: '<rect x="20" y="18" width="60" height="16" rx="5" fill="currentColor"/><rect x="20" y="42" width="60" height="16" rx="5" fill="currentColor" opacity="0.7"/><rect x="20" y="66" width="60" height="16" rx="5" fill="currentColor" opacity="0.45"/>',
    wave: '<path d="M8 60 Q29 30 50 60 T92 60" stroke="currentColor" stroke-width="6" fill="none"/><path d="M8 78 Q29 48 50 78 T92 78" stroke="currentColor" stroke-width="6" fill="none" opacity="0.5"/>',
    hex: '<path d="M50 8 L86 29 L86 71 L50 92 L14 71 L14 29 Z" stroke="currentColor" stroke-width="6" fill="none"/><circle cx="50" cy="50" r="9" fill="currentColor"/>',
    bolt: '<path d="M56 6 L24 56 L46 56 L40 94 L78 40 L54 40 Z" fill="currentColor"/>',
  };

```

--------------------------------

### Configure Toolsmith Prompt and Retention Controls

Source: https://github.com/johnlindquist/better-plugins/blob/main/README.md

Set environment variables to control prompt text storage, excerpt length, prompt state cache TTL, and raw event retention policies.

```bash
TOOLSMITH_CAPTURE_PROMPT_TEXT=0          # store prompt hashes only; disables prompt excerpts
TOOLSMITH_MAX_PROMPT_EXCERPT_CHARS=800   # max prompt excerpt stored in prompt events
TOOLSMITH_PROMPT_STATE_TTL_MS=21600000   # prompt-to-tool linkage cache TTL
BETTER_TOOLS_RETENTION_DAYS=90           # raw JSONL retention
BETTER_TOOLS_MAX_BYTES=250000000         # raw event byte cap

```

--------------------------------

### Compile Python Scripts and Run Unit Tests

Source: https://github.com/johnlindquist/better-plugins/blob/main/README.md

Compile all Python files within the scripts and tests directories and then discover and run unit tests.

```bash
python3 -m py_compile scripts/*.py tests/*.py
python3 -m unittest discover -s tests

```

--------------------------------

### Toolsmith Dashboard Configuration

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/toolsmith/skills/toolsmith/SKILL.md

Controls the live dashboard for Toolsmith. Set TOOLSMITH_DASHBOARD=0 to disable it, or TOOLSMITH_DASHBOARD_OPEN_BROWSER=0 to run it headless.

```text
TOOLSMITH_DASHBOARD=0
```

```text
TOOLSMITH_DASHBOARD_OPEN_BROWSER=0
```

--------------------------------

### Run Toolsmith Analyzer

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/toolsmith/skills/toolsmith/SKILL.md

Execute the Toolsmith analyzer scripts for doctor, indexing, and summarization. Ensure the PLUGIN_ROOT environment variable is set or use the full path to the script.

```bash
python3 "$PLUGIN_ROOT/scripts/better_tools.py" doctor
python3 "$PLUGIN_ROOT/scripts/better_tools.py" index --days 30
python3 "$PLUGIN_ROOT/scripts/better_tools.py" summary --days 30
```

```bash
python3 /Users/johnlindquist/dev/better-plugins/plugins/toolsmith/scripts/better_tools.py summary --days 30
```

--------------------------------

### Gemini Video Plugin Workflow Diagram

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/gemini-video/README.md

Diagram illustrating the flow of data and processes within the Gemini Video plugin, from user prompt submission to job status updates.

```text
UserPromptSubmit / PostToolUse / Stop
        │  (stdin JSON: session_id, cwd, hook_event_name, prompt, tool_input…)
        ▼
hooks/gemini_video_hook.py   ← fast: detect .mp4 → atomic claim → spawn detached worker → emit control JSON
        │ spawns (detached, once per video) ──► worker/worker.py
        │                                          └─ runs: bun ~/lessons/scripts/summarize-one.ts <video> <prompt>
        ▼
$PLUGIN_DATA/jobs/<job_key>/{status,summary.md,error.txt,worker.log}
```

--------------------------------

### Generate Tool Index with Toolsmith

Source: https://github.com/johnlindquist/better-plugins/blob/main/README.md

Use the Toolsmith Python script to generate a compact, deduped index of tools. This command specifies the number of days for data inclusion.

```bash
python3 scripts/better_tools.py index --days 30

```

--------------------------------

### Toolsmith Capture Mode Configuration

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/toolsmith/skills/toolsmith/SKILL.md

Configures how Toolsmith captures data. Options include 'opt-in' (default, triggered by #toolsmith), 'always' (legacy ambient capture), and 'off'.

```text
TOOLSMITH_CAPTURE_MODE=opt-in
```

--------------------------------

### Real Smoke Test Execution

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/gemini-video/README.md

Command to perform a real smoke test of the Gemini Video plugin. This requires setting the GEMINI_API_KEY and involves an actual Gemini API call.

```bash
export GEMINI_API_KEY=...      # do not echo
SID=smoke
echo '{"hook_event_name":"UserPromptSubmit","session_id":"'"$SID"'","prompt":"#gemini-video summarize /abs/path/real.mp4","cwd":"'"$HOME"'"}' \
  | GEMINI_VIDEO_DATA=/tmp/gv python3 hooks/gemini_video_hook.py
sleep 5; cat /tmp/gv/jobs/*/status; head /tmp/gv/jobs/*/summary.md 2>/dev/null
```

--------------------------------

### Render Event Timeline

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/human-view/assets/index.html

Renders the activity timeline by mapping event data to list items. It displays the last 8 events in reverse chronological order. If no events exist, it shows a 'No activity yet' message.

```javascript
function renderTimeline(events) {
  if (!events || !events.length) {
    els.timeline.innerHTML = '<li class="empty">No activity yet</li>';
    return;
  }
  els.timeline.innerHTML = events.slice(-8).reverse().map(e => `<li><span class="kind">${escape(e.kind || "·")}</span><span class="what">${escape(e.what || "")}</span></li>`).join("");
}
```

--------------------------------

### Hermetic Test Execution

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/gemini-video/README.md

Command to run the hermetic tests for the Gemini Video plugin. This test verifies the plugin's functionality without making actual network calls to Gemini.

```bash
cd plugins/gemini-video
python3 tests/test_gemini_video.py     # expect: OK: 0 failure(s)
```

--------------------------------

### Render List of Items

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/toolsmith/assets/dashboard.html

Renders a list of items into an HTML element by its ID. Each item is displayed as 'name: count'. If no items are provided, it displays 'No data yet'.

```javascript
function renderList(id, items) {
  const node = document.getElementById(id);
  node.replaceChildren();
  for (const item of items || []) {
    const li = document.createElement("li");
    li.textContent = `${item.name}: ${item.count}`;
    node.appendChild(li);
  }
  if (!items || items.length === 0) {
    const li = document.createElement("li");
    li.textContent = "No data yet";
    node.appendChild(li);
  }
}
```

--------------------------------

### Render Task State

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/human-view/assets/index.html

Updates the UI based on the provided state object. This includes setting text content, applying styles (like `--hue`), rendering SVG shapes, and managing the visibility of the summary card. It also triggers a 'flash' animation on the detail card.

```javascript
function render(state) {
  const design = state.design || {};
  if (typeof design.hue === "number") document.documentElement.style.setProperty("--hue", design.hue);
  els.glyph.innerHTML = SHAPES[design.shape] || SHAPES.spark;
  text(els.title, state.title || "Codex task");
  text(els.phase, state.phase || "Working");
  text(els.detail, state.status_detail || "Working…");
  text(els.prompt, state.prompt || "—");
  text(els.rev, state.revision ?? 0);
  text(els.updated, state.updated_at || "—");
  renderTimeline(state.events);
  if (state.summary) {
    els.summaryCard.style.display = "";
    text(els.summary, state.summary);
  } else {
    els.summaryCard.style.display = "none";
  }
  els.detailCard.classList.remove("flash");
  void els.detailCard.offsetWidth; // reflow to restart animation
  els.detailCard.classList.add("flash");
  document.title = `${state.phase || "Codex"} · ${state.title || "Human View"}`;
}
```

--------------------------------

### Default Gemini Video Runner Command

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/gemini-video/README.md

The default shell command executed by the worker to process a video using Gemini. This command can be overridden via the GEMINI_VIDEO_RUNNER environment variable.

```shell
bun ~/lessons/scripts/summarize-one.ts <video> <prompt-file>
```

--------------------------------

### Toolsmith Data Source Fallback Path

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/toolsmith/skills/toolsmith/SKILL.md

Specifies the fallback directory for the Toolsmith corpus if the environment variable is not set. This path is used to store raw event data.

```text
~/.codex/plugin-data/toolsmith/
```

--------------------------------

### Check Toolsmith JavaScript Hook

Source: https://github.com/johnlindquist/better-plugins/blob/main/README.md

Verify the integrity of the `capture_pre_tool_use.js` hook using Node.js's check functionality.

```bash
cd plugins/toolsmith
node --check hooks/capture_pre_tool_use.js

```

--------------------------------

### Reinstall Toolsmith After Local Edits

Source: https://github.com/johnlindquist/better-plugins/blob/main/README.md

After making local modifications to the Toolsmith plugin, remove and then re-add it to ensure Codex refreshes its cached copy.

```bash
codex plugin remove toolsmith@better-plugins
codex plugin add toolsmith@better-plugins

```

--------------------------------

### Fetch and Render Dashboard State

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/toolsmith/assets/dashboard.html

Fetches dashboard state data from a server endpoint and updates various UI elements. It also sets up an interval to refresh the data every second.

```javascript
const TOKEN = "__TOKEN__";
function setText(id, value) {
  document.getElementById(id).textContent = String(value ?? "");
}
function renderList(id, items) {
  const node = document.getElementById(id);
  node.replaceChildren();
  for (const item of items || []) {
    const li = document.createElement("li");
    li.textContent = `${item.name}: ${item.count}`;
    node.appendChild(li);
  }
  if (!items || items.length === 0) {
    const li = document.createElement("li");
    li.textContent = "No data yet";
    node.appendChild(li);
  }
}
async function tick() {
  try {
    const res = await fetch(`/state.json?token=${encodeURIComponent(TOKEN)}`, {
      cache: "no-store"
    });
    const data = await res.json();
    setText("status", `Updated ${data.generated_at}`);
    setText("warning", data.warning || "");
    setText("records", data.totals.records);
    setText("tool_records", data.totals.tool_records);
    setText("duplicates", data.totals.duplicate_tool_input_calls);
    setText("redactions", data.redaction.redacted_count);
    renderList("top_tools", data.top_tools);
    renderList("top_projects", data.top_projects);
  } catch (error) {
    setText("status", `Disconnected: ${error}`);
  }
}
tick();
setInterval(tick, 1000);
```

--------------------------------

### Update Text Content of an Element

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/human-view/assets/index.html

A utility function to update an element's text content only if the new value differs from the current one. This prevents unnecessary DOM updates.

```javascript
function text(el, v) {
  if (el.textContent !== v) el.textContent = v;
}
```

--------------------------------

### HTML Entity Escaping

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/human-view/assets/index.html

Escapes special HTML characters to prevent XSS vulnerabilities and ensure correct rendering of text content. Handles common entities like &, <, >, and ".

```javascript
function escape(s) {
  return String(s).replace(/[[&<>"]]/g, c => ({
    "&": "&amp;",
    "<": "&lt;",
    ">": "&gt;",
    "\"": "&quot;"
  }[c]));
}
```

--------------------------------

### Update Text Content

Source: https://github.com/johnlindquist/better-plugins/blob/main/plugins/toolsmith/assets/dashboard.html

Updates the text content of an HTML element by its ID. Handles null or undefined values by converting them to strings.

```javascript
function setText(id, value) {
  document.getElementById(id).textContent = String(value ?? "");
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.