pennyrouter 0.3.18 → 0.3.20

package/README.md

@@ -18,6 +18,7 @@ npx pennyrouter disable
 npx pennyrouter enable
 npx pennyrouter uninstall
 npx pennyrouter status
+npx pennyrouter compare
 ```
 
 Installation opens a browser and requires login to the PennyRouter account that should own
@@ -29,7 +30,7 @@ Installing against a self-hosted gateway is its own flow, with no browser login:
 keeps its own accounts, so the key is minted there.
 
 ```bash
-npx pennyrouter install --private-gateway https://gateway.example.internal
+npx pennyrouter install --private-gateway https://penny-router.apps-dev.gtri.org
 ```
 
 It asks for the gateway URL (unless given) and your email, and mints a key against that
@@ -44,11 +45,11 @@ ones:
 ```json
 {
   "harnesses": ["claude-code", "codex"],
-  "gatewayBaseUrl": "https://gateway.example.internal",
+  "gatewayBaseUrl": "https://penny-router.apps-dev.gtri.org",
   "claudeFunding": ["anthropic-proxy"],
-  "proxyBaseUrl": "https://litellm.example.internal",
+  "anthropicProxyBaseUrl": "https://litellm.core.gtri.org",
   "codexFunding": ["openai-proxy"],
-  "openaiProxyBaseUrl": "https://litellm.example.internal"
+  "openaiProxyBaseUrl": "https://litellm.core.gtri.org"
 }
 ```
 
@@ -57,6 +58,13 @@ npx pennyrouter install --config team-install.json
 ```
 
 Each person is prompted for their email and their proxy key; everything else is prefilled.
+
+For clarity, `proxyBaseUrl`/`proxyApiKey` are the legacy names for the Claude/Anthropic
+wire lane. New files should use `anthropicProxyBaseUrl`/`anthropicProxyApiKey`; Codex uses
+`openaiProxyBaseUrl`/`openaiProxyApiKey`. The `--private-server` spelling is a compatibility
+alias for `--private-gateway`.
+
+
 Any field left out of the file is prompted for, and an unattended run that cannot prompt
 refuses by name rather than installing a half-configured harness. Add `email`, `proxyApiKey`
 and `openaiProxyApiKey` to the file to skip the prompts entirely.
@@ -72,6 +80,16 @@ OpenRouter key. PennyRouter-funded provider keys are never an installed-harness
 
 ## Explicit Penny Commands
 
+Penny Compare is bundled with the CLI on macOS and Linux. It is installed automatically as part
+of `npx pennyrouter install`; to install or refresh it separately, run:
+
+```sh
+npx pennyrouter compare
+```
+
+Then use `penny-compare` for a side-by-side run or `penny-session` for one Penny-routed session.
+The bundle requires `tmux`, Python 3.10+, and the harnesses being compared.
+
 On macOS and Linux, a normal install adds a small `penny` launcher under `~/.local/bin`.
 On Windows it installs `penny.cmd` under `%LOCALAPPDATA%\\PennyRouter\\bin` and adds that
 directory to the user PATH:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pennyrouter",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "description": "Install and manage PennyRouter local coding-agent integrations.",
   "homepage": "https://pennyrouter.com",
   "bugs": {
@@ -20,6 +20,7 @@
   "files": [
     "bin",
     "src",
+    "standalone",
     "README.md"
   ],
   "scripts": {

package/src/cli.js

@@ -59,6 +59,7 @@ import {
   configurePennyHarness,
   hasConfiguredPennyHarnesses,
   installPennyRuntime,
+  installPennyCompare,
   loadPennyConfig,
   pennyConfigPath,
   removePennyHarness,
@@ -120,6 +121,17 @@ export async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (command === "compare") {
+    const result = await installPennyCompare();
+    if (!result.installed) {
+      if (result.supported) throw new Error("Penny Compare is not included in this CLI package.");
+      throw new Error("Penny Compare requires macOS or Linux with tmux and Python 3.10+.");
+    }
+    console.log(`Penny Compare installed at ${result.path}`);
+    console.log("Run `penny-compare` or `penny-session` to use it.");
+    return;
+  }
+
   if (command === "update") {
     await update(flags);
     return;
@@ -234,6 +246,10 @@ function parseArgs(argv) {
     else if (arg.startsWith("--openai-proxy-base-url=")) flags.openaiProxyBaseUrl = arg.slice("--openai-proxy-base-url=".length);
     else if (arg === "--openai-proxy-api-key") flags.openaiProxyApiKey = rest[++i] || "";
     else if (arg.startsWith("--openai-proxy-api-key=")) flags.openaiProxyApiKey = arg.slice("--openai-proxy-api-key=".length);
+    else if (arg === "--anthropic-proxy-base-url") flags.proxyBaseUrl = rest[++i] || "";
+    else if (arg.startsWith("--anthropic-proxy-base-url=")) flags.proxyBaseUrl = arg.slice("--anthropic-proxy-base-url=".length);
+    else if (arg === "--anthropic-proxy-api-key") flags.proxyApiKey = rest[++i] || "";
+    else if (arg.startsWith("--anthropic-proxy-api-key=")) flags.proxyApiKey = arg.slice("--anthropic-proxy-api-key=".length);
     else if (arg === "--proxy-base-url") flags.proxyBaseUrl = rest[++i] || "";
     else if (arg.startsWith("--proxy-base-url=")) flags.proxyBaseUrl = arg.slice("--proxy-base-url=".length);
     else if (arg === "--proxy-api-key") flags.proxyApiKey = rest[++i] || "";
@@ -250,17 +266,17 @@ function parseArgs(argv) {
     // --gateway-base-url, which expects the URL and an admin-issued key up front, this asks
     // for what it needs (gateway URL, then email) and mints the key from the gateway itself,
     // so a user on a VPN can install without an administrator handing them a key first.
-    else if (arg === "--private-gateway") {
+    else if (arg === "--private-gateway" || arg === "--private-server") {
       flags.privateGatewayFlow = true;
       flags.privateGateway = true;
       // Optional inline URL: `--private-gateway https://...` rather than a prompt. Only
       // consume the next argument when it is not itself a flag.
       if (rest[i + 1] && !rest[i + 1].startsWith("-")) flags.gatewayBaseUrl = rest[++i];
     }
-    else if (arg.startsWith("--private-gateway=")) {
+    else if (arg.startsWith("--private-gateway=") || arg.startsWith("--private-server=")) {
       flags.privateGatewayFlow = true;
       flags.privateGateway = true;
-      flags.gatewayBaseUrl = arg.slice("--private-gateway=".length);
+      flags.gatewayBaseUrl = arg.slice(arg.indexOf("=") + 1);
     }
     // Email the private gateway mints the key against; prompted for when absent.
     else if (arg === "--email") flags.email = rest[++i] || "";
@@ -328,6 +344,15 @@ export function applyConfigFile(flags) {
   if (config.harnesses && flags.harness === undefined) {
     flags.harness = config.harnesses.join(",");
   }
+  // Migrate the ambiguous Claude proxy keys in-memory. Existing shared install files remain
+  // valid while new files can say explicitly which wire lane they configure.
+  if (config.anthropicProxyBaseUrl === undefined && config.proxyBaseUrl !== undefined) {
+    config.anthropicProxyBaseUrl = config.proxyBaseUrl;
+  }
+  if (config.anthropicProxyApiKey === undefined && config.proxyApiKey !== undefined) {
+    config.anthropicProxyApiKey = config.proxyApiKey;
+  }
+
   const claudeFunding = new Set(config.claudeFunding || []);
   const codexFunding = new Set(config.codexFunding || []);
   if (claudeFunding.has("subscription") && flags.anthropicAuth === undefined) {
@@ -358,6 +383,15 @@ export function applyConfigFile(flags) {
     const value = String(config[field.config_key] || "").trim();
     if (value && flags[field.config_key] === undefined) flags[field.config_key] = value;
   }
+  // ``proxy*`` was the original Claude/Anthropic naming. Keep it as an input alias, but
+  // normalize the explicit JSON names back to the internal flags used by the installer.
+  if (flags.proxyBaseUrl === undefined && flags.anthropicProxyBaseUrl !== undefined) {
+    flags.proxyBaseUrl = flags.anthropicProxyBaseUrl;
+  }
+  if (flags.proxyApiKey === undefined && flags.anthropicProxyApiKey !== undefined) {
+    flags.proxyApiKey = flags.anthropicProxyApiKey;
+  }
+
   if (flags.gatewayBaseUrl) {
     flags.privateGateway = true;
     // Take the self-hosted install path rather than the hosted browser claim, whose key is
@@ -1423,8 +1457,10 @@ async function selectClaudeFundingProviders(flags, selected) {
       || process.env.ANTHROPIC_AUTH_TOKEN)) supplied.add("subscription");
   if (flags.anthropicApiKey || process.env.ANTHROPIC_API_KEY) supplied.add("anthropic-api");
   if (flags.openrouterApiKey || process.env.OPENROUTER_API_KEY) supplied.add("openrouter");
-  if ((flags.proxyBaseUrl || process.env.PENNYROUTER_PROXY_BASE_URL)
-      && (flags.proxyApiKey || process.env.PENNYROUTER_PROXY_API_KEY)) {
+  if ((flags.proxyBaseUrl || process.env.PENNYROUTER_ANTHROPIC_PROXY_BASE_URL
+      || process.env.PENNYROUTER_PROXY_BASE_URL)
+      && (flags.proxyApiKey || process.env.PENNYROUTER_ANTHROPIC_PROXY_API_KEY
+      || process.env.PENNYROUTER_PROXY_API_KEY)) {
     supplied.add("anthropic-proxy");
   }
   // A --config file states its providers outright, and that choice stands whether or not the
@@ -1559,10 +1595,14 @@ async function configureUserFunding(flags, selected, claudeAnthropicAuth,
     flags.openaiProxyApiKey || process.env.PENNYROUTER_OPENAI_PROXY_API_KEY || "",
   ).trim();
   let proxyBaseUrl = String(
-    flags.proxyBaseUrl || process.env.PENNYROUTER_PROXY_BASE_URL || "",
+    flags.proxyBaseUrl || flags.anthropicProxyBaseUrl
+      || process.env.PENNYROUTER_ANTHROPIC_PROXY_BASE_URL
+      || process.env.PENNYROUTER_PROXY_BASE_URL || "",
   ).trim();
   let proxyApiKey = String(
-    flags.proxyApiKey || process.env.PENNYROUTER_PROXY_API_KEY || "",
+    flags.proxyApiKey || flags.anthropicProxyApiKey
+      || process.env.PENNYROUTER_ANTHROPIC_PROXY_API_KEY
+      || process.env.PENNYROUTER_PROXY_API_KEY || "",
   ).trim();
   const codexSubscriptionAuth = wantsCodex && codexProviders.has("subscription")
     ? await detectCodexChatgptAuth()
@@ -2401,13 +2441,14 @@ function printHelp() {
   console.log(`PennyRouter CLI
 
 Usage:
-  pennyrouter install [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes] [--dry-run] [--make-default|--penny-only] [--no-path-update] [--no-mcp] [--anthropic-auth|--no-anthropic-auth] [--anthropic-api-key KEY] [--openai-api-key KEY] [--openai-proxy-base-url URL --openai-proxy-api-key KEY] [--openrouter-api-key KEY] [--proxy-base-url URL --proxy-api-key KEY] [--private-gateway[=URL] [--email you@example.com]] [--gateway-base-url URL] [--private-key pr-...] [--local[=URL]|--prod] [--config PATH]
+  pennyrouter install [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes] [--dry-run] [--make-default|--penny-only] [--no-path-update] [--no-mcp] [--anthropic-auth|--no-anthropic-auth] [--anthropic-api-key KEY] [--openai-api-key KEY] [--openai-proxy-base-url URL --openai-proxy-api-key KEY] [--openrouter-api-key KEY] [--anthropic-proxy-base-url URL --anthropic-proxy-api-key KEY] [--proxy-base-url URL --proxy-api-key KEY] [--private-gateway|--private-server[=URL] [--email you@example.com]] [--gateway-base-url URL] [--private-key pr-...] [--local[=URL]|--prod] [--config PATH]
   pennyrouter update [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--dry-run] [--penny-key pr-...] [--gateway-base-url URL|--local[=URL]|--prod] [--no-mcp]
   pennyrouter auth anthropic [--penny-key pr-...] [--token oauth-token] [--token-command CMD] [--gateway-base-url URL] [--forget]
   pennyrouter disable [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes]
   pennyrouter enable [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes]
   pennyrouter uninstall [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes] [--forget-token]
   pennyrouter status
+  pennyrouter compare              install or refresh Penny Compare
   pennyrouter profiles [name]
   pennyrouter mcp install|uninstall|status [--harness claude-code,codex]
 

package/src/install-manifest.json

@@ -56,12 +56,12 @@
           "name": "Proxy (e.g., Bedrock, Azure, private server)",
           "fields": [
             {
-              "config_key": "proxyBaseUrl",
-              "label": "Proxy base URL",
+              "config_key": "anthropicProxyBaseUrl",
+              "label": "Anthropic proxy base URL",
               "secret": false,
               "placeholder": "https://proxy.example.com"
             },
-            { "config_key": "proxyApiKey", "label": "Proxy API key", "secret": true }
+            { "config_key": "anthropicProxyApiKey", "label": "Anthropic proxy API key", "secret": true }
           ]
         }
       ]

package/src/launch.js

@@ -65,6 +65,10 @@ export function pennyRuntimeDir() {
   return join(pennyDataDir(), "runtime");
 }
 
+export function pennyCompareDir() {
+  return join(pennyDataDir(), "compare");
+}
+
 export function pennyBinDir() {
   if (process.platform === "win32") return join(pennyDataDir(), "bin");
   return join(homeDir(), ".local", "bin");
@@ -257,6 +261,32 @@ async function copyRuntime() {
   await cp(join(source, "package.json"), join(destination, "package.json"), { force: true });
 }
 
+/** Install the bundled, repository-independent Penny Compare tools. */
+export async function installPennyCompare() {
+  if (!(process.platform === "darwin" || process.platform === "linux")) {
+    return { supported: false, installed: false, path: pennyCompareDir() };
+  }
+  const source = join(packageRoot(), "standalone");
+  const destination = pennyCompareDir();
+  try {
+    await stat(source);
+  } catch {
+    return { supported: true, installed: false, path: destination };
+  }
+  await mkdir(destination, { recursive: true, mode: 0o700 });
+  // Preserve user state while replacing the shipped code on every CLI upgrade.
+  for (const entry of await readdir(destination)) {
+    if (entry === ".env" || entry === "reports") continue;
+    await rm(join(destination, entry), { recursive: true, force: true });
+  }
+  for (const entry of await readdir(source)) {
+    if (entry === ".env" || entry === "reports") continue;
+    await cp(join(source, entry), join(destination, entry), { recursive: true, force: true });
+  }
+  await mkdir(join(destination, "reports"), { recursive: true, mode: 0o700 });
+  return { supported: true, installed: true, path: destination };
+}
+
 async function writeShim() {
   await mkdir(pennyBinDir(), { recursive: true, mode: 0o755 });
   const entry = join(pennyRuntimeDir(), "bin", "penny.js");
@@ -386,7 +416,8 @@ export async function installPennyRuntime({ updatePath = true } = {}) {
     config.windows_path_managed = true;
     await savePennyConfig(config);
   }
-  return { supported: true, ...path, shim_path: pennyShimPath() };
+  const compare = await installPennyCompare();
+  return { supported: true, ...path, shim_path: pennyShimPath(), compare };
 }
 
 export function renderCodexLaunchProfile({ gatewayBaseUrl, subscriptionAuth }) {

package/standalone/.env.example

@@ -0,0 +1,8 @@
+# Copy to .env (gitignored) and fill in.
+#
+# Used only by the NATIVE pane, and only when penny-compare is run with --native-proxy
+# or you answer yes to the proxy question in the menu. Without that, the NATIVE pane
+# always talks to Anthropic directly.
+
+PENNY_COMPARE_NATIVE_BASE_URL=
+PENNY_COMPARE_NATIVE_AUTH_TOKEN=

package/standalone/README-original.md

@@ -0,0 +1,79 @@
+Comparison tool
+
+## Single-session HUD
+
+For one normal interactive session with the same live token/cost panel used by the comparison
+tool, run:
+
+    apps/compare/penny-session
+
+It starts a Penny-routed Claude Code session by default. Choose another client explicitly when
+needed:
+
+    apps/compare/penny-session penny-codex
+    apps/compare/penny-session penny-opencode
+    apps/compare/penny-session claude --model sonnet
+
+OpenCode can be compared directly or through PennyRouter:
+
+    penny-compare opencode penny-opencode
+    penny-compare --model pennyrouter/auto opencode penny-opencode
+
+OpenCode usage is read from its local SQLite session store, including cache and output tokens.
+The compare tool separates native and PennyRouter sessions using OpenCode's recorded provider id.
+
+The launcher accepts `--dir PATH`, `--label NAME`, `--model MODEL`, `--pricing-profile PROFILE`,
+and `--native-proxy`. When the client exits, the HUD exits with it; no comparison window or tmux
+session is created.
+
+The live HUD and saved reports use the same model prices on both sides. A direct comparison uses
+standard rates. Selecting `--native-proxy` switches both panes to the GovCloud schedule. Its
+Opus 5 rates are $5.50/M input, $27.50/M output, $0.55/M cache read, $6.875/M 5-minute cache
+write, and $11.00/M 1-hour cache write. The GovCloud profile also carries dedicated rates for
+Opus 4.8, Sonnet 5, Haiku 4.5, and the context-tiered GPT 5.6 Luna, Terra, and Sol models. GPT's
+high rate is selected per call only when that call's input context exceeds 272K.
+
+Ctrl-Shift-X (or Ctrl-B then X) snapshots the interval since launch or the last reset, writes a
+per-call JSON report to `apps/compare/reports`, shows total token and cost savings, and waits for
+Enter before closing the tmux session.
+
+## Report viewer
+
+Start the local web viewer with:
+
+    apps/compare/penny-compare-viewer
+
+Then open http://127.0.0.1:8788. It lists saved comparisons, shows side-by-side token and cost
+metrics, and lets you select any linked transcript message to read its complete output. New
+reports record each pane's stable `session_id` and `transcript_path` so the viewer can resolve the
+original Claude Code or Codex JSONL session. Reports created before this metadata was added are
+still viewable for their summary metrics, but cannot identify a transcript automatically.
+
+To use another port for a one-off run:
+
+    apps/compare/penny-compare-viewer --port 8790
+
+penny-compare \
+--model opus \
+--dir-left /Users/jduke34/Documents/GitHub/test-session/native \
+--dir-right /Users/jduke34/Documents/GitHub/test-session/penny \
+claude penny-claude
+
+#with proxy
+penny-compare \
+--dir-left ~/Documents/GitHub/test-session/native \
+--dir-right ~/Documents/GitHub/test-session/penny \
+--label-left NATIVE \
+--label-right PENNY \
+--model sonnet \
+--native-proxy \
+claude penny-claude
+
+penny-compare \
+--dir-left ~/Documents/GitHub/test-session/native \
+--dir-right ~/Documents/GitHub/test-session/penny \
+--label-left "NATIVE BEDROCK" \
+--label-right "PENNY BEDROCK"  \
+--model opus \
+--native-proxy \
+claude penny-claude

package/standalone/README.md

@@ -0,0 +1,60 @@
+# Penny Compare — portable bundle
+
+Live token/cost HUDs for coding-agent sessions. Run two harnesses side by side
+(`penny-compare`) or one on its own (`penny-session`).
+
+Self-contained: stdlib Python only, no pip, no npm.
+
+## Install
+
+    ./install.sh                # symlinks into ~/.local/bin
+    ./install.sh ~/bin          # or a directory you choose
+
+Keep this folder where it is — the commands are symlinks back to it. Move it and
+re-run `install.sh` to repoint.
+
+### Requirements
+
+- `tmux` and `python3` 3.10+ (`install.sh` checks both and stops if either is missing)
+- Whichever harnesses you're comparing: `claude`, `codex`, `opencode`
+- For the penny-routed panes: `npx pennyrouter install`
+
+## Use
+
+    penny-compare                                  menu
+    penny-compare claude penny-claude              native vs penny, side by side
+    penny-compare --model opus claude penny-claude both panes on one model
+    penny-session                                  one penny-routed Claude session
+    penny-session claude --model sonnet            one native session
+    penny-compare-viewer                           browse saved reports
+
+Keys, in-session: `ctrl-shift-s` sync · `ctrl-shift-r` reset counters ·
+`ctrl-shift-x` write report and quit. Each also has a `ctrl-b` prefix spelling
+for terminals that can't send ctrl-shift (Terminal.app among them).
+
+Reset before the run that counts — a comparison is only fair once both sides
+have a warm cache.
+
+## `.env` (optional)
+
+Only needed for `--native-proxy`, which routes the NATIVE pane through a proxy
+instead of straight to Anthropic. **Not included in this bundle** — it holds auth
+tokens. Copy `.env.example` to `.env` and fill it in, or copy your existing
+`.env` across separately.
+
+Without it, everything else works; the NATIVE pane just talks to Anthropic directly.
+
+## Reports
+
+New runs land in `reports/` beside the bundle. `penny-compare-viewer` serves them at
+http://localhost:8765. A release bundle starts with an empty reports directory; reports are
+local runtime data and are never copied into a release.
+
+## Caveat: pricing goes stale
+
+`pricing.py` hardcodes per-token rates, and the Codex model list in
+`penny-compare` mirrors the gateway's catalog. Neither updates itself away from
+the repo, and a stale table misprices silently. Re-copy those two files when
+rates change.
+
+Original repo docs: `README-original.md`.

package/standalone/claude-proxy.sh

@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+# Point Claude Code (and penny-compare's NATIVE pane) at an OpenAI/Anthropic-compatible
+# proxy, and put it back.
+#
+# This does two things together, since both are needed to fully switch over:
+#
+#  1. Writes ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN into ~/.claude/settings.json's
+#     `env` block, which is what a bare `claude` invocation reads on startup. Every
+#     other setting in that file is preserved -- the edit is a key-level merge, not a
+#     rewrite.
+#  2. Writes PENNY_COMPARE_NATIVE_BASE_URL / PENNY_COMPARE_NATIVE_AUTH_TOKEN into this
+#     repo's .env file. penny-compare's pane.py reads those two vars from its own
+#     process environment when run with --native-proxy, and injects them into the
+#     NATIVE pane's subprocess as ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN. Without
+#     this, --native-proxy has nothing to read and the NATIVE pane falls back to
+#     Anthropic direct even with settings.json pointed at the proxy, because pane.py
+#     strips ambient ANTHROPIC_* vars before optionally reinjecting its own.
+#  3. Sets settings.json's disableClaudeAiConnectors to true while the proxy is on.
+#     Once ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN override auth, Claude Code is no
+#     longer authenticated against claude.ai, so claude.ai-hosted MCP connectors
+#     (Gmail, Calendar, Drive, etc.) are unreachable regardless -- this just says so
+#     up front instead of showing the "disabled because an auth source is set"
+#     warning on every startup. Cleared on `off`.
+#
+#   claude-proxy.sh on [url]   point Claude Code (and --native-proxy) at the proxy
+#   claude-proxy.sh off        remove it, back to Anthropic direct everywhere
+#   claude-proxy.sh status     show what is set right now, for both
+#
+# The token is read from CLAUDE_PROXY_TOKEN, or prompted for without echo.
+# It is never passed on the command line, where it would land in shell history.
+#
+# export CLAUDE_PROXY_URL=https://litellm.core.gtri.org
+# export CLAUDE_PROXY_TOKEN=sk-example
+# ./claude-proxy.sh on
+#
+# The first `on` backs up settings.json and .env once per invocation (whichever
+# already exist), before any write. Recoverable from settings.json.bak.<timestamp>
+# and .env.bak.<timestamp> in ~/.claude and this repo respectively.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+ENV_FILE="${PROXY_ENV_FILE:-$SCRIPT_DIR/.env}"
+if [ -f "$ENV_FILE" ]; then
+  set -a
+  . "$ENV_FILE"
+  set +a
+fi
+
+SETTINGS="${CLAUDE_SETTINGS:-$HOME/.claude/settings.json}"
+# Falls back to whatever URL is already saved in .env from the last `on` run,
+# so a bare `./claude-proxy.sh on` reuses it without retyping.
+DEFAULT_URL="${CLAUDE_PROXY_URL:-${PENNY_COMPARE_NATIVE_BASE_URL:-}}"
+
+NATIVE_URL_VAR="PENNY_COMPARE_NATIVE_BASE_URL"
+NATIVE_TOKEN_VAR="PENNY_COMPARE_NATIVE_AUTH_TOKEN"
+
+die() { echo "error: $*" >&2; exit 1; }
+
+command -v python3 >/dev/null || die "python3 is required"
+
+# Claude Code creates this on first run; an install that has never been launched
+# has no file, and writing one here would guess at the rest of its contents.
+[ -f "$SETTINGS" ] || die "no settings file at $SETTINGS (run claude once first)"
+
+# One backup per run, before any write.
+backup() {
+  local dest="$SETTINGS.bak.$(date +%Y%m%dT%H%M%SZ)"
+  cp "$SETTINGS" "$dest"
+  echo "backed up settings to $dest"
+
+  if [ -f "$ENV_FILE" ]; then
+    local env_dest="$ENV_FILE.bak.$(date +%Y%m%dT%H%M%SZ)"
+    cp "$ENV_FILE" "$env_dest"
+    echo "backed up .env to $env_dest"
+  fi
+}
+
+# Merge or delete the two env keys in settings.json. Reads the file, edits the
+# parsed object, and writes to a temp file in the same directory before renaming
+# over the original, so an interrupted run cannot leave a half-written file behind.
+edit_settings() {
+  ACTION="$1" URL="${2:-}" TOKEN="${3:-}" SETTINGS="$SETTINGS" python3 <<'PY'
+import json, os, tempfile
+
+path = os.environ["SETTINGS"]
+action = os.environ["ACTION"]
+
+with open(path) as fh:
+    settings = json.load(fh)
+
+env = settings.setdefault("env", {})
+if action == "on":
+    env["ANTHROPIC_BASE_URL"] = os.environ["URL"]
+    env["ANTHROPIC_AUTH_TOKEN"] = os.environ["TOKEN"]
+    # claude.ai connectors rely on claude.ai OAuth; a proxy auth source means
+    # Claude Code is no longer authenticated against that account, so the
+    # connectors would be unreachable anyway -- this just says so up front.
+    settings["disableClaudeAiConnectors"] = True
+else:
+    env.pop("ANTHROPIC_BASE_URL", None)
+    env.pop("ANTHROPIC_AUTH_TOKEN", None)
+    # Leave no empty env block behind if this script put everything in it.
+    if not env:
+        settings.pop("env")
+    settings.pop("disableClaudeAiConnectors", None)
+
+directory = os.path.dirname(path) or "."
+with tempfile.NamedTemporaryFile("w", dir=directory, delete=False) as tmp:
+    json.dump(settings, tmp, indent=2)
+    tmp.write("\n")
+    temp_path = tmp.name
+os.chmod(temp_path, 0o600)
+os.replace(temp_path, path)
+PY
+}
+
+# Remove any existing line for the given var name from .env.
+strip_env_var() {
+  local var="$1"
+  [ -f "$ENV_FILE" ] || return 0
+  grep -v -e "^${var}=" "$ENV_FILE" > "$ENV_FILE.tmp" || true
+  mv "$ENV_FILE.tmp" "$ENV_FILE"
+}
+
+# Merge or delete the two penny-compare native-proxy keys in .env, preserving any
+# other lines already in the file.
+edit_native_env() {
+  local action="$1" url="${2:-}" token="${3:-}"
+  touch "$ENV_FILE"
+  strip_env_var "$NATIVE_URL_VAR"
+  strip_env_var "$NATIVE_TOKEN_VAR"
+  if [ "$action" = "on" ]; then
+    printf '%s=%s\n' "$NATIVE_URL_VAR" "$url" >> "$ENV_FILE"
+    printf '%s=%s\n' "$NATIVE_TOKEN_VAR" "$token" >> "$ENV_FILE"
+  fi
+  chmod 600 "$ENV_FILE"
+}
+
+show_status() {
+  SETTINGS="$SETTINGS" python3 <<'PY'
+import json, os
+
+with open(os.environ["SETTINGS"]) as fh:
+    settings = json.load(fh)
+
+env = settings.get("env", {})
+url = env.get("ANTHROPIC_BASE_URL")
+token = env.get("ANTHROPIC_AUTH_TOKEN")
+if url:
+    shown = f"{token[:6]}...{token[-4:]}" if token and len(token) > 12 else ("set" if token else "MISSING")
+    connectors = "disabled" if settings.get("disableClaudeAiConnectors") else "enabled"
+    print(f"claude (settings.json): ON\n  ANTHROPIC_BASE_URL:   {url}\n  ANTHROPIC_AUTH_TOKEN: {shown}\n  claude.ai connectors: {connectors}")
+else:
+    print("claude (settings.json): OFF (Claude Code talks to Anthropic directly)")
+PY
+
+  if [ ! -f "$ENV_FILE" ]; then
+    echo "penny-compare --native-proxy (.env): OFF (no .env file)"
+    return
+  fi
+
+  local url token
+  url="$(grep -e "^${NATIVE_URL_VAR}=" "$ENV_FILE" | tail -n1 | cut -d= -f2-)"
+  token="$(grep -e "^${NATIVE_TOKEN_VAR}=" "$ENV_FILE" | tail -n1 | cut -d= -f2-)"
+
+  if [ -n "$url" ]; then
+    local shown="MISSING"
+    if [ -n "$token" ]; then
+      if [ "${#token}" -gt 12 ]; then
+        shown="${token:0:6}...${token: -4}"
+      else
+        shown="set"
+      fi
+    fi
+    echo "penny-compare --native-proxy (.env): ON"
+    echo "  $NATIVE_URL_VAR:   $url"
+    echo "  $NATIVE_TOKEN_VAR: $shown"
+  else
+    echo "penny-compare --native-proxy (.env): OFF"
+  fi
+}
+
+case "${1:-status}" in
+  on)
+    url="${2:-$DEFAULT_URL}"
+    [ -n "$url" ] || die "usage: $(basename "$0") on <proxy-url>   (or set CLAUDE_PROXY_URL)"
+
+    # Falls back to whatever token is already saved in .env from the last
+    # `on` run, so a bare `./claude-proxy.sh on` reuses it without retyping.
+    token="${CLAUDE_PROXY_TOKEN:-${PENNY_COMPARE_NATIVE_AUTH_TOKEN:-}}"
+    if [ -z "$token" ]; then
+      # -s so the key does not linger on screen or in scrollback.
+      read -rsp "Proxy API key: " token < /dev/tty
+      echo
+    fi
+    [ -n "$token" ] || die "no token given"
+
+    backup
+    edit_settings on "$url" "$token"
+    edit_native_env on "$url" "$token"
+    echo "Claude Code -> $url"
+    echo "penny-compare --native-proxy -> $url"
+    echo "Restart any running claude/penny-compare session to pick this up."
+    ;;
+  off)
+    backup
+    edit_settings off
+    edit_native_env off
+    echo "Claude Code -> Anthropic direct"
+    echo "penny-compare --native-proxy -> Anthropic direct"
+    echo "Restart any running claude/penny-compare session to pick this up."
+    ;;
+  status)
+    show_status
+    ;;
+  *)
+    die "usage: $(basename "$0") {on [url]|off|status}"
+    ;;
+esac