rippletide-package 0.1.0

package/counter/src/counter.js

@@ -0,0 +1,165 @@
+// Codex live-counter launcher.
+//
+// One command: point Codex's `openai_base_url` at the counter proxy, open the floating
+// sticky window, and tally calls / tokens / cost live until you stop. Restores your Codex
+// config on exit. Ported/trimmed from x-ray's launcher (`backend/xray.js`) — Codex only,
+// no OpenTelemetry, no Claude, no risk.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { startCounterProxy } from "./proxy.js";
+
+const home = os.homedir();
+const WINDOW = fileURLToPath(new URL("../frontend/window.jxa", import.meta.url));
+const BEGIN = "# >>> rippletide counter >>>";
+const END = "# <<< rippletide counter <<<";
+const CODEX_BUNDLE = "com.openai.codex";
+
+const TOKEN_FIELDS = ["inputTokens", "outputTokens", "totalTokens", "cachedInputTokens", "cacheCreationInputTokens", "reasoningOutputTokens"];
+const emptyTokens = () => Object.fromEntries(TOKEN_FIELDS.map((f) => [f, 0]));
+const tokenCount = (v) => { const n = Number(v); return Number.isFinite(n) && n > 0 ? Math.round(n) : 0; };
+
+function codexHome() { return process.env.CODEX_HOME || path.join(home, ".codex"); }
+
+// ---- temporary Codex config (openai_base_url -> the proxy) ----
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+function stripManaged(config) {
+  return config.replace(new RegExp(`\\n?${escapeRe(BEGIN)}[\\s\\S]*?${escapeRe(END)}\\n?`, "g"), "\n");
+}
+
+function removeOpenaiBaseUrl(config) {
+  const kept = [];
+  let topLevel = true;
+  for (const line of config.split("\n")) {
+    if (/^\s*\[/.test(line)) topLevel = false;
+    if (topLevel && /^\s*openai_base_url\s*=/.test(line)) continue;
+    kept.push(line);
+  }
+  return kept.join("\n");
+}
+
+function withCounterConfig(config, baseUrl) {
+  const clean = removeOpenaiBaseUrl(stripManaged(config)).trimEnd();
+  return `${BEGIN}\nopenai_base_url = ${JSON.stringify(baseUrl)}\n${END}\n${clean ? `\n${clean}\n` : ""}`;
+}
+
+function atomicWrite(file, content, mode = 0o600) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, content, { mode });
+  fs.renameSync(tmp, file);
+}
+
+function installConfig(baseUrl) {
+  const dir = codexHome();
+  fs.mkdirSync(dir, { recursive: true });
+  const cfg = path.join(dir, "config.toml");
+  const original = fs.existsSync(cfg) ? fs.readFileSync(cfg, "utf8") : "";
+  const mode = (() => { try { return fs.statSync(cfg).mode & 0o777; } catch { return 0o600; } })();
+  atomicWrite(cfg, withCounterConfig(original, baseUrl), mode);
+  return () => atomicWrite(cfg, original, mode);
+}
+
+// ---- relaunch the Codex app so it picks up the base URL (app reads config at startup) ----
+function codexAppRunning() {
+  const r = spawnSync("osascript", ["-e", `application id "${CODEX_BUNDLE}" is running`], { encoding: "utf8" });
+  return r.status === 0 && r.stdout.trim() === "true";
+}
+
+function relaunchCodexApp(log) {
+  if (process.env.RIPPLETIDE_RELAUNCH_CODEX_APP === "0" || process.platform !== "darwin" || !codexAppRunning()) return;
+  log("counter: relaunching the Codex app once so it routes through the counter.");
+  spawnSync("osascript", ["-e", `tell application id "${CODEX_BUNDLE}" to quit`], { encoding: "utf8" });
+  const start = Date.now();
+  while (codexAppRunning() && Date.now() - start < 8000) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+  spawnSync("open", ["-b", CODEX_BUNDLE], { encoding: "utf8" });
+}
+
+// ---- state the window renders ----
+function newState() {
+  return {
+    label: "codex", calls: 0, risky: 0, rerouted: 0,
+    models: {}, providers: {}, riskyModels: {}, riskyActions: {}, servedModels: {}, reroutes: {},
+    tokens: emptyTokens(), costUsd: 0, usageModels: {}, status: "counting", updated: 0,
+  };
+}
+
+function addTokens(target, delta) {
+  for (const f of TOKEN_FIELDS) target[f] = tokenCount(target[f]) + tokenCount(delta[f]);
+}
+
+function writeState(file, state) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ ...state, updated: Date.now() }));
+  fs.renameSync(tmp, file);
+}
+
+function openWindow(statePath) {
+  if (process.platform !== "darwin") return null;
+  return spawn("osascript", ["-l", "JavaScript", WINDOW, statePath], { stdio: "ignore" });
+}
+
+export async function run() {
+  const stateDir = path.join(process.env.XDG_STATE_HOME || path.join(home, ".local", "state"), "rippletide");
+  fs.mkdirSync(stateDir, { recursive: true });
+  const statePath = path.join(stateDir, "counter.json");
+  const state = newState();
+  const persist = (status = "counting") => { state.status = status; writeState(statePath, state); };
+  persist();
+
+  const proxy = startCounterProxy({
+    onCall({ model = "unknown" } = {}) {
+      state.calls += 1;
+      const name = String(model || "unknown").trim() || "unknown";
+      state.models[name] = (state.models[name] || 0) + 1;
+      state.providers[name] = "codex";
+      persist();
+    },
+    onUsage({ model = "unknown", usage = {}, costUsd = 0 } = {}) {
+      const delta = {}; for (const f of TOKEN_FIELDS) delta[f] = tokenCount(usage[f]);
+      if (!TOKEN_FIELDS.some((f) => delta[f] > 0)) return;
+      const name = String(model || "unknown").trim() || "unknown";
+      addTokens(state.tokens, delta);
+      state.costUsd += Number(costUsd) || 0;
+      if (!state.usageModels[name]) state.usageModels[name] = { ...emptyTokens(), costUsd: 0 };
+      addTokens(state.usageModels[name], delta);
+      state.usageModels[name].costUsd += Number(costUsd) || 0;
+      persist();
+    },
+  });
+  await proxy.listen();
+
+  let stopped = false;
+  let restoreConfig = () => {};
+  let window = null;
+  try {
+    restoreConfig = installConfig(proxy.baseUrl());
+    relaunchCodexApp(console.log);
+    window = openWindow(statePath);
+    console.log(`counter: live. Use Codex (app or CLI) — calls, tokens, and cost tally in the floating window.`);
+    console.log(`counter: routing Codex → ${proxy.baseUrl()} (config restored on exit). Ctrl-C to stop.`);
+    if (process.platform !== "darwin") console.log("counter: the sticky window is macOS-only; counting still works.");
+  } catch (e) {
+    try { restoreConfig(); } catch {}
+    proxy.close();
+    console.error(`counter: failed to start: ${e.message}`);
+    return 1;
+  }
+
+  const stop = () => {
+    if (stopped) return; stopped = true;
+    try { restoreConfig(); } catch (e) { console.error(`counter restore warning: ${e.message}`); }
+    try { proxy.close(); } catch {}
+    persist("stopped");
+    try { window?.kill(); } catch {}
+    process.exit(0);
+  };
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(sig, stop);
+  process.on("exit", () => { if (!stopped) { try { restoreConfig(); } catch {} } });
+  window?.on("exit", stop);
+  process.stdin.resume();
+  return new Promise(() => {}); // run until a signal stops us
+}

package/counter/src/proxy.js

@@ -0,0 +1,243 @@
+// Codex live-counter proxy.
+//
+// A tiny reverse proxy that sits on Codex's `openai_base_url`: it forwards every model
+// call to api.openai.com untouched, and on the way back it counts the call and reads the
+// response `usage` to tally tokens and estimate cost. Ported from x-ray's proxy
+// (`backend/xray-proxy.js`, codex/add-tokens-and-cost) — the counting + token/cost half
+// only: no risk scanning, no HTTPS MITM, no OpenTelemetry, Codex/OpenAI only.
+
+import http from "node:http";
+import https from "node:https";
+
+const INFERENCE_PATH = /\/(responses|chat\/completions)(\/|$|\?)/;
+const DEBUG = process.env.COUNTER_DEBUG === "1";
+const dbg = (m) => { if (DEBUG) process.stderr.write(`counter-proxy: ${m}\n`); };
+
+const usageTokenFields = [
+  "inputTokens", "outputTokens", "totalTokens",
+  "cachedInputTokens", "cacheCreationInputTokens", "reasoningOutputTokens",
+];
+
+// USD per million tokens. Kept in sync with x-ray's OpenAI price table.
+const openAiPriceTable = [
+  { pattern: /^gpt-5\.5-pro(?:-|$)/, inputUsdPerMt: 30, outputUsdPerMt: 180 },
+  { pattern: /^gpt-5\.5(?:-|$)/, inputUsdPerMt: 5, cachedInputUsdPerMt: 0.5, outputUsdPerMt: 30 },
+  { pattern: /^gpt-5\.4-pro(?:-|$)/, inputUsdPerMt: 30, outputUsdPerMt: 180 },
+  { pattern: /^gpt-5\.4-mini(?:-|$)/, inputUsdPerMt: 0.75, cachedInputUsdPerMt: 0.075, outputUsdPerMt: 4.5 },
+  { pattern: /^gpt-5\.4-nano(?:-|$)/, inputUsdPerMt: 0.2, cachedInputUsdPerMt: 0.02, outputUsdPerMt: 1.25 },
+  { pattern: /^gpt-5\.4(?:-|$)/, inputUsdPerMt: 2.5, cachedInputUsdPerMt: 0.25, outputUsdPerMt: 15 },
+  { pattern: /^gpt-5\.3-codex(?:-|$)/, inputUsdPerMt: 1.75, cachedInputUsdPerMt: 0.175, outputUsdPerMt: 14 },
+  { pattern: /^chat-latest(?:-|$)/, inputUsdPerMt: 5, cachedInputUsdPerMt: 0.5, outputUsdPerMt: 30 },
+];
+
+function tokenNumber(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? Math.round(n) : 0;
+}
+
+function normalizeModelName(model) {
+  return String(model || "").trim().toLowerCase();
+}
+
+function usagePricing(model) {
+  const normalized = normalizeModelName(model);
+  return openAiPriceTable.find((entry) => entry.pattern.test(normalized)) || null;
+}
+
+export function estimateUsageCostUsd(model, usage) {
+  const pricing = usagePricing(model);
+  if (!pricing || !usage) return 0;
+  const inputTokens = tokenNumber(usage.inputTokens);
+  const cachedInputTokens = Math.min(inputTokens, tokenNumber(usage.cachedInputTokens));
+  const cacheCreationInputTokens = Math.min(
+    Math.max(0, inputTokens - cachedInputTokens),
+    tokenNumber(usage.cacheCreationInputTokens),
+  );
+  const uncachedInputTokens = Math.max(0, inputTokens - cachedInputTokens - cacheCreationInputTokens);
+  const inputCost = uncachedInputTokens * pricing.inputUsdPerMt;
+  const cachedCost = cachedInputTokens * (pricing.cachedInputUsdPerMt ?? pricing.inputUsdPerMt);
+  const cacheWriteCost = cacheCreationInputTokens * (pricing.cacheWriteInputUsdPerMt ?? pricing.inputUsdPerMt);
+  const outputCost = tokenNumber(usage.outputTokens) * pricing.outputUsdPerMt;
+  return (inputCost + cachedCost + cacheWriteCost + outputCost) / 1_000_000;
+}
+
+function normalizeUsage(usage) {
+  const normalized = {};
+  for (const field of usageTokenFields) normalized[field] = tokenNumber(usage?.[field]);
+  if (!normalized.totalTokens) normalized.totalTokens = normalized.inputTokens + normalized.outputTokens;
+  return usageHasTokens(normalized) ? normalized : null;
+}
+
+function usageHasTokens(usage) {
+  return usageTokenFields.some((field) => tokenNumber(usage?.[field]) > 0);
+}
+
+function normalizeOpenAIUsage(usage) {
+  if (!usage || typeof usage !== "object") return null;
+  const inputTokens = tokenNumber(usage.input_tokens ?? usage.prompt_tokens);
+  const outputTokens = tokenNumber(usage.output_tokens ?? usage.completion_tokens);
+  return normalizeUsage({
+    inputTokens,
+    outputTokens,
+    totalTokens: tokenNumber(usage.total_tokens) || inputTokens + outputTokens,
+    cachedInputTokens: tokenNumber(
+      usage.input_tokens_details?.cached_tokens ?? usage.prompt_tokens_details?.cached_tokens ?? usage.cached_tokens,
+    ),
+    reasoningOutputTokens: tokenNumber(
+      usage.output_tokens_details?.reasoning_tokens ?? usage.completion_tokens_details?.reasoning_tokens ?? usage.reasoning_tokens,
+    ),
+  });
+}
+
+// Take only the increase since the last usage seen on a streamed response (Codex sends
+// cumulative usage across SSE events), so we never double-count within one call.
+function usageDelta(previous, current) {
+  const merged = {};
+  const delta = {};
+  for (const field of usageTokenFields) {
+    if (field === "totalTokens") continue;
+    const prev = tokenNumber(previous?.[field]);
+    const next = Math.max(prev, tokenNumber(current?.[field]));
+    merged[field] = next;
+    delta[field] = Math.max(0, next - prev);
+  }
+  merged.totalTokens = Math.max(tokenNumber(previous?.totalTokens), tokenNumber(current?.totalTokens), merged.inputTokens + merged.outputTokens);
+  delta.totalTokens = Math.max(0, merged.totalTokens - tokenNumber(previous?.totalTokens));
+  return { merged, delta: usageHasTokens(delta) ? delta : null };
+}
+
+function requestModel(requestBody) {
+  try {
+    const parsed = JSON.parse(Buffer.isBuffer(requestBody) ? requestBody.toString("utf8") : String(requestBody || ""));
+    return String(parsed.model || "unknown").trim() || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function sseEvents(text) {
+  return String(text || "").split(/\r?\n\r?\n/).filter(Boolean);
+}
+
+function eventData(event) {
+  return String(event || "").split(/\r?\n/).filter((l) => l.startsWith("data:")).map((l) => l.slice(5).trimStart()).join("\n");
+}
+
+function responseUsage(chunk) {
+  const text = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk || "");
+  let found = null;
+  for (const event of sseEvents(text)) {
+    const data = eventData(event);
+    if (!data || data === "[DONE]") continue;
+    try {
+      const parsed = JSON.parse(data);
+      found = normalizeOpenAIUsage(parsed.response?.usage || parsed.usage) || found;
+    } catch {}
+  }
+  try {
+    const parsed = JSON.parse(text);
+    found = normalizeOpenAIUsage(parsed.response?.usage || parsed.usage) || found;
+  } catch {}
+  return found;
+}
+
+function responseModel(chunk) {
+  const text = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk || "");
+  for (const event of sseEvents(text)) {
+    const data = eventData(event);
+    if (!data || data === "[DONE]") continue;
+    try {
+      const parsed = JSON.parse(data);
+      const m = (parsed.response?.model || parsed.model || "").trim?.() || String(parsed.response?.model || parsed.model || "").trim();
+      if (m) return m;
+    } catch {}
+  }
+  return null;
+}
+
+// Start the reverse proxy. `onCall({model})` fires once per inference request;
+// `onUsage({model, usage, costUsd})` fires as token usage arrives.
+export function startCounterProxy({ onCall, onUsage } = {}) {
+  const server = http.createServer((req, res) => forward(req, res, { onCall, onUsage }));
+  server.on("error", () => {});
+  // Codex opens a WebSocket to /v1/responses when the provider supports it. This HTTP proxy
+  // can't carry that upgrade, so refuse it immediately — Codex then falls straight back to
+  // its HTTPS transport (which we do forward) instead of retrying the handshake until timeout.
+  server.on("upgrade", (req, socket) => {
+    dbg(`ws upgrade ${req.method} ${req.url} -> refused`);
+    try { socket.write("HTTP/1.1 426 Upgrade Required\r\nConnection: close\r\n\r\n"); } catch {}
+    try { socket.destroy(); } catch {}
+  });
+  return {
+    server,
+    listen(port = 0, host = "127.0.0.1") {
+      return new Promise((resolve, reject) => {
+        server.listen(port, host, resolve);
+        server.once("error", reject);
+      });
+    },
+    address() { return server.address(); },
+    baseUrl() { return `http://127.0.0.1:${server.address().port}/v1`; },
+    close() { try { server.close(); } catch {} },
+  };
+}
+
+function forward(req, res, { onCall, onUsage }) {
+  const chunks = [];
+  req.on("data", (c) => chunks.push(c));
+  req.on("end", () => {
+    const requestBody = Buffer.concat(chunks);
+    const model = requestModel(requestBody);
+    // Count only real inference POSTs — not the GET /v1/responses connectivity probes.
+    const isInference = req.method === "POST" && INFERENCE_PATH.test(req.url || "");
+    const upgrade = req.headers.upgrade || (req.headers["sec-websocket-key"] ? "websocket?" : "");
+    dbg(`${req.method} ${req.url} model=${model} inference=${isInference} bodyLen=${requestBody.length}${upgrade ? ` upgrade=${upgrade}` : ""}`);
+    if (isInference) onCall?.({ model });
+
+    const headers = { ...req.headers, host: "api.openai.com" };
+    delete headers["proxy-connection"];
+    headers["accept-encoding"] = "identity";
+
+    const upstream = https.request(
+      { hostname: "api.openai.com", port: 443, method: req.method, path: req.url, headers, ALPNProtocols: ["http/1.1"] },
+      (upRes) => {
+        res.writeHead(upRes.statusCode || 502, upRes.headers);
+        dbg(`resp ${upRes.statusCode} ct=${upRes.headers["content-type"]} ce=${upRes.headers["content-encoding"] || "none"}`);
+        let servedModel = null;
+        let lastUsage = null;
+        let buffer = "";
+        let sawUsage = false;
+        const noteUsage = (found) => {
+          if (!found) return;
+          const next = usageDelta(lastUsage, found);
+          lastUsage = next.merged;
+          if (!next.delta) return;
+          sawUsage = true;
+          const usageModel = servedModel || model;
+          onUsage?.({ model: usageModel, usage: next.delta, costUsd: estimateUsageCostUsd(usageModel, next.delta) });
+        };
+        upRes.on("data", (chunk) => {
+          buffer += chunk.toString("utf8");
+          const parts = buffer.split(/\r?\n\r?\n/);
+          buffer = parts.pop() || "";
+          for (const part of parts) {
+            if (!servedModel) servedModel = responseModel(part) || servedModel;
+            noteUsage(responseUsage(part));
+          }
+          res.write(chunk);
+        });
+        upRes.on("end", () => {
+          // non-streaming JSON: the whole body is still in the buffer here
+          servedModel = servedModel || responseModel(buffer);
+          noteUsage(responseUsage(buffer));
+          if (DEBUG && isInference) dbg(`usage extracted=${sawUsage} for ${servedModel || model}`);
+          res.end();
+        });
+      },
+    );
+    upstream.on("error", (e) => {
+      try { res.writeHead(502, { "content-type": "text/plain" }); res.end(String(e.message || e)); } catch {}
+    });
+    upstream.end(requestBody);
+  });
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "rippletide-package",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Rippletide's CLI for AI coding agents — one command, each feature a subcommand.",
+  "keywords": [
+    "agents",
+    "ai-agents",
+    "cli",
+    "rippletide"
+  ],
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rippletideco/rippletide-package.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "rippletide": "bin/rippletide.js"
+  },
+  "files": [
+    "bin/",
+    "reviewer/bin/",
+    "reviewer/src/",
+    "reviewer/codex/rippletide-reviewer/scripts/",
+    "reviewer/README.md",
+    "reviewer/.env.example",
+    "tide/bin/",
+    "tide/src/",
+    "tide/examples/",
+    "tide/README.md",
+    "counter/src/",
+    "counter/frontend/",
+    "counter/README.md",
+    "README.md",
+    "PUBLISHING.md"
+  ],
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "scripts": {
+    "help": "node ./bin/rippletide.js --help",
+    "start": "node ./bin/rippletide.js review",
+    "review": "node ./bin/rippletide.js review",
+    "tide": "node ./bin/rippletide.js tide",
+    "counter": "node ./bin/rippletide.js counter",
+    "codex:prepare": "npm --prefix reviewer run codex:prepare",
+    "pack:dry": "npm pack --dry-run",
+    "release:check": "npm run check && node ./bin/rippletide.js --help",
+    "release:dry": "npm publish --dry-run",
+    "release:publish": "npm publish",
+    "prepublishOnly": "npm run release:check",
+    "check": "node --check bin/rippletide.js && npm --prefix reviewer run check && npm --prefix tide run check && node --check counter/src/cli.js && node --check counter/src/counter.js && node --check counter/src/proxy.js && npm run pack:dry",
+    "lint": "npm run check",
+    "test": "npm run check"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "UNLICENSED"
+}

package/reviewer/.env.example

@@ -0,0 +1,5 @@
+# Required only for CLI mode.
+OPENAI_API_KEY=
+
+# Optional CLI model override.
+RIPPLETIDE_MODEL=gpt-5.5

package/reviewer/README.md

@@ -0,0 +1,137 @@
+# Rippletide Reviewer
+
+Rippletide Reviewer reviews local AI agents before ship. It reads an agent repo, builds an evidence pack from local code/config/docs, produces short impact-driven findings, and can propose focused edits for findings the builder chooses.
+
+The MVP has two local modes:
+
+- **CLI mode**: Rippletide calls the configured model directly, can run an interactive fix loop, and attempts a local proof after accepted edits.
+- **Codex-native mode**: Rippletide prepares local evidence for Codex, then Codex does the review and proposes edits in the user's existing Codex session.
+
+## Quick Start
+
+```bash
+npm install
+cp .env.example .env
+```
+
+Add your model API key to `.env` for CLI mode:
+
+```bash
+OPENAI_API_KEY=...
+RIPPLETIDE_MODEL=gpt-5.5
+```
+
+Run a review with npx:
+
+```bash
+npx rippletide review
+```
+
+The command reviews the current directory by default.
+
+Explicit path:
+
+```bash
+npx rippletide review /path/to/agent
+```
+
+Current local reviewer mode requires `OPENAI_API_KEY`. The product direction is hosted-first, so the final `npx rippletide review` flow will use the Rippletide hosted reviewer instead of asking users to configure model keys.
+
+Run a review from a local checkout:
+
+```bash
+node bin/rippletide.js review /path/to/agent
+```
+
+Run a review and choose fixes interactively:
+
+```bash
+node bin/rippletide.js review /path/to/agent --fix
+```
+
+Inspect only, without user-facing findings:
+
+```bash
+node bin/rippletide.js inspect /path/to/agent
+```
+
+## Try A Local Agent
+
+The repo includes local agents for teammate testing:
+
+```text
+agents/
+```
+
+Example:
+
+```bash
+node bin/rippletide.js review agents/browser-use-apply-to-job
+```
+
+Codex-native evidence preparation:
+
+```bash
+codex/rippletide-reviewer/scripts/rippletide-codex prepare agents/langgraph-react-agent
+```
+
+## Product Flow
+
+1. Collect local agent evidence.
+2. Build an evidence pack with source excerpts and file citations.
+3. Ask the LLM inspector to create an internal neutral dossier.
+4. Ask the LLM reviewer to reread the dossier and evidence.
+5. Show the user short findings only.
+6. For a selected finding, ask the LLM action planner for a small patch or `NO_PATCH`.
+7. Let the user apply, refuse, comment, skip, or quit.
+8. After an accepted patch, run a safe local proof command when possible and save `proof.md`.
+9. Save artifacts under the target agent repo.
+
+Artifacts are written to:
+
+```text
+<agent>/.rippletide/actions/<run-id>/
+<agent>/.rippletide/codex/<run-id>/
+```
+
+These folders are intentionally ignored by Git.
+
+## Repo Layout
+
+```text
+agents/                         Local agents for teammate testing
+bin/rippletide.js               CLI executable shim
+src/connect/                    Shared local evidence/context foundation
+src/integrations/               CLI, Codex, MCP, and future assistant wrappers
+codex/rippletide-reviewer/      Codex plugin packaging and skill wrapper
+docs/                           Architecture and development notes
+```
+
+The Codex plugin has its own short guide at [codex/rippletide-reviewer/README.md](codex/rippletide-reviewer/README.md).
+
+The intended architecture is one shared foundation with thin wrappers for CLI, MCP, Codex, Claude Code, Cursor, Gemini, OpenCode, and packaging surfaces. New reusable behavior should land under `src/connect/` or `src/features/`; wrappers should only translate host-specific setup and calls.
+
+## Commands
+
+```bash
+npm run check       # syntax-check the CLI/Codex scripts and run tests
+npm run help        # show CLI usage
+npm run inspect -- /path/to/agent
+npm run review -- /path/to/agent
+```
+
+## Safety Model
+
+- Rippletide reads local source/config/doc files and redacts obvious secrets before sending evidence to the configured model in CLI mode.
+- Codex-native mode does not call Rippletide APIs or external model APIs by itself. It only writes local evidence and instructions for Codex.
+- Proposed edits are not applied until the user chooses apply.
+- CLI fix mode only runs allowlisted local proof commands without a shell: `npm test`, `bun test`, `python3 -m pytest`, `python3 -m unittest discover`, `node --test`, `npm run check`, `node --check`, or `python3 -m py_compile`.
+- Behavior tests/evals are proof. Syntax/compile checks are reported as code checks, not behavior proof.
+- If behavior proof fails or no safe proof exists, Rippletide reports that plainly instead of claiming the finding is fixed.
+- Generated `.rippletide/` artifacts, `.env`, and agent results must not be committed.
+
+## Development
+
+Read [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the current system shape and [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for local development rules.
+
+The npm package and publishing flow are owned by the repo root. See [../docs/PUBLISHING.md](../docs/PUBLISHING.md).

package/reviewer/bin/rippletide-review.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+if (process.argv.length <= 2) {
+  process.argv.push("review");
+  process.argv.push(".");
+} else {
+  const firstArg = process.argv[2];
+  const helpRequested = firstArg === "--help" || firstArg === "-h";
+  const commandProvided = firstArg === "review" || firstArg === "inspect";
+
+  if (!helpRequested && !commandProvided) {
+    process.argv.splice(2, 0, "review");
+  }
+}
+
+await import("../src/integrations/cli/rippletide.js");

package/reviewer/bin/rippletide.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from "../src/integrations/cli/rippletide.js";
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/reviewer/codex/rippletide-reviewer/README.md

@@ -0,0 +1,28 @@
+# Rippletide Reviewer Codex Plugin
+
+This plugin lets Codex run Rippletide in Codex-native mode.
+
+Codex-native mode does not call Rippletide APIs or external model APIs by itself. It prepares local evidence under the target agent repo and gives Codex instructions for the review/action flow.
+
+## Smoke Test
+
+From the repository root:
+
+```bash
+codex/rippletide-reviewer/scripts/rippletide-codex prepare agents/langgraph-react-agent
+```
+
+Generated artifacts are written to:
+
+```text
+<agent>/.rippletide/codex/<run-id>/
+```
+
+## Files
+
+```text
+.codex-plugin/plugin.json            Plugin manifest
+skills/rippletide-reviewer/SKILL.md  Codex-facing workflow
+scripts/rippletide-codex             Evidence preparation wrapper
+scripts/rippletide-reviewer          Standalone CLI wrapper
+```