claude-org 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.3.0 — 2026-10-10
+
+- `proxy`: each log line now names the model (`via <org> model=<model> -> <status>`), and the org and model of the last request are written to a JSON state file whose path is passed to `claude` as `CLAUDE_ORG_STATE_FILE`, for statusline and hooks (#12)
+- `probe` / `status`: `--model <id>` (or `CLAUDE_ORG_PROBE_MODEL`) checks that model instead of Haiku and appends `model_status=available|unavailable|unknown` (and `model_error=` when refused), so "5h allowed but this model is refused" is told apart. `auto` falls back to the default org when the preferred org refuses the model (#9)
+- `proxy`: `CLAUDE_ORG_STRATEGY=least-utilized` sends each request to the usable org with the lowest 5h utilization it has reported (orgs not yet measured are tried first). Unset keeps the priority order; the launch line and the log now show the strategy (#7)
+- Docs: proxy mode now explains that Agent-tool subagents go through the same proxy and what that implies (#16)
+
 ## 0.2.2 — 2026-10-10
 
 - Development: `npm run release -- <patch|minor|major|X.Y.Z>` runs the whole release (checks, tests, CHANGELOG, version, commit, tag, push, npm publish, registry check)

package/LICENSE

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

@@ -57,13 +57,22 @@ Repeat steps 1–2 **once per org**:
 | `claude-org proxy [claude args...]` | Launch via a local proxy: a **running** session fails over to another org the moment the 5h limit hits. Needs 2+ org tokens (incl. one for the default side). |
 | `claude-org auto [claude args...]` | Launch on the preferred org if usable, else on the default org. Decided once at launch. |
 | `claude-org <name> [claude args...]` | Launch with that org's token, e.g. `claude-org work --resume`. |
-| `claude-org probe [<name>]` | Print the org's 5h window state on one line (`status= 5h_util= 5h_reset= 5h_reset_local=`). Exit 0 when `allowed`. |
+| `claude-org probe [<name>] [--model <id>]` | Print the org's 5h window state on one line (`status= 5h_util= 5h_reset= 5h_reset_local=`). Exit 0 when `allowed`. With `--model`, probe with that model and append `model= model_status=` (see below). |
 | `claude-org watch` | Poll the preferred org until its window recovers, then notify (terminal + optional `CLAUDE_ORG_NOTIFY_CMD`). |
-| `claude-org status` | `claude auth status` for every saved token + the default login. |
+| `claude-org status [--model <id>]` | `claude auth status` and `probe` for every saved token + the default login. |
 | `claude-org list` | List saved org names. |
 
 `auto` and `<name>` only read env at launch — they cannot switch a running session. Settings, plugins, and session history live under `~/.claude/` and are shared across orgs, so `claude-org auto --resume` continues a session started under the other org.
 
+**Checking a model, not just the window**: `probe` and `status` use Haiku by default, but an org can show `status=allowed` and still refuse another model (for example one that needs usage credits). Pass the model your session uses:
+
+```sh
+claude-org probe work --model claude-fable-5-1
+# status=allowed 5h_util=0.34 ... model=claude-fable-5-1 model_status=unavailable model_error=rate_limit_error
+```
+
+`model_status` is `available` (2xx), `unavailable` (refused while the 5h/7d windows are not rejected; exit 1) or `unknown` (no response, bad token or permission, timeout, server error, or a rejected window; the exit code then follows `status` alone). Setting `CLAUDE_ORG_PROBE_MODEL` applies the same check to `probe`, `status` and `auto`; `auto` then launches on the default org when the preferred org refuses that model.
+
 The **preferred org** (used by `auto`, `watch`, and as `proxy`'s first candidate) resolves in this order: `CLAUDE_ORG_PREFER` -> first entry of `CLAUDE_ORG_ORDER` -> first `.token` file alphabetically.
 
 ## proxy mode
@@ -77,13 +86,29 @@ claude-org proxy --resume
 3. The proxy replaces the `Authorization` header with a real org token and forwards to `api.anthropic.com`. On a 429 or `anthropic-ratelimit-unified-5h-status: rejected` it marks that org limited until `5h-reset` and **resends the same request** with the next org's token.
 4. Claude Code only ever sees the successful response — the org switched mid-session. SSE streaming is piped through untouched.
 
-One log line per request (`via <org> -> <status>`) goes to a temp file printed at launch (`-> proxy 127.0.0.1:<port> (order: ..., log: ...)`).
+One log line per request (`via <org> model=<model> -> <status>`) goes to a temp file printed at launch (`-> proxy 127.0.0.1:<port> (order: ..., strategy: ..., log: ...)`). The prompt and the tokens are never logged.
+
+**Spreading load by utilization**: with `CLAUDE_ORG_STRATEGY=least-utilized`, the proxy remembers the `5h-utilization` each org last reported and sends each request to the usable org with the lowest value. An org that has not reported yet is tried first (in priority order) so it gets measured once; one that answers without a utilization goes after the measured ones. A value is forgotten when that org's 5h window resets. Rate-limited orgs are still skipped. Utilization is a share of each org's own plan, not an absolute amount, so a larger plan is picked more often; if you want one org's allowance used up first (e.g. your company's), keep the default and set `CLAUDE_ORG_ORDER` instead.
+
+**Which org is in use right now**: after each model request the proxy writes `{"org", "model", "status", "at"}` as JSON (`org` is `null` with `status` 503 when no org could serve) to `state.json` in the same temp directory as the log. Its path is exported to the `claude` process as `CLAUDE_ORG_STATE_FILE`, so a statusline command or hook can show it, e.g.:
+
+```sh
+[ -n "$CLAUDE_ORG_STATE_FILE" ] && [ -f "$CLAUDE_ORG_STATE_FILE" ] && node -p "require(process.env.CLAUDE_ORG_STATE_FILE).org"
+```
 
 **Limitations of proxy mode**
 
 - claude.ai connector MCPs (Gmail / Drive / Calendar / Notion / Slack …) and Remote Control are **unavailable**: `ANTHROPIC_AUTH_TOKEN` makes Claude Code treat the session as external-token auth, so `mcp__claude_ai_*` tools do not appear. Local/plugin MCPs work. Open connectors in a plain `claude --resume` session — history is shared.
 - Each proxy serves one session and dies when `claude` exits.
 
+**Subagents**
+
+- Subagents started with Claude Code's Agent tool run in the same process as the parent session and share its `ANTHROPIC_BASE_URL`, so they go through the same proxy with no setup and use the same orgs' limits. Their requests appear in the proxy log with their own `model=` (e.g. a Haiku subagent).
+- Not covered: a `claude` started as a separate process (it needs its own `claude-org proxy`), and agents that run in the cloud (e.g. `isolation: remote`).
+- The connector MCP limitation above applies to subagents too.
+- When an org's 5h or 7d window is rejected, the org is taken out for every model, so subagents also move to the next org until the window resets. A 429 for one model only (#8) moves that model only; other models, including those of subagents, stay on the org.
+- Work routed to a Team / Enterprise org (e.g. your company's) counts toward that org's usage, which its admins can see.
+
 ### Prompt cache & tool search
 
 A custom `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` makes Claude Code treat the session as API-key auth, which changes two defaults:
@@ -105,11 +130,14 @@ A custom `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` makes Claude Code treat t
 |---|---|---|
 | `CLAUDE_ORG_PREFER` | (unset) | Preferred org for `auto` / `watch` / `proxy` |
 | `CLAUDE_ORG_ORDER` | (unset) | Comma-separated org priority for `proxy`; unlisted orgs follow alphabetically |
+| `CLAUDE_ORG_STRATEGY` | (unset: priority order) | `least-utilized`: `proxy` sends each request to the usable org with the lowest 5h utilization (see proxy mode) |
+| `CLAUDE_ORG_PROBE_MODEL` | (unset: Haiku) | Model used by `probe` / `status` / `auto` to check the org; adds `model_status=` to the probe line |
 | `CLAUDE_ORG_TOKEN_DIR` | `~/.claude/org-tokens` | Where `<name>.token` files live |
 | `CLAUDE_ORG_NOTIFY_CMD` | (unset) | `watch` notification command, run as `<cmd> "<title>" "<message>"` via the OS shell |
 | `CLAUDE_ORG_WATCH_MAX_SLEEP` | `18000` | Max seconds between `watch` re-checks (values < 60 also lower the 60s minimum — for tests) |
 | `CLAUDE_ORG_UPSTREAM` | `https://api.anthropic.com` | API base URL for `probe` and `proxy` (stub upstream in tests) |
 | `CLAUDE_ORG_PROXY` | `1` when launched via `proxy` | Marker env passed to the claude process so user hooks can detect connector-less sessions |
+| `CLAUDE_ORG_STATE_FILE` | set when launched via `proxy` | Path of the JSON file holding the org and model of the last request (read it from a statusline or hook) |
 | `CLAUDE_ORG_FORCE_PROBE` | (unset) | Test seam: `allowed` / `rejected[:<epoch>]` / `rejected_until:<epoch>` fakes `probe` results without API calls |
 | `CLAUDE_ORG_REJECT_FILE` | (unset) | Test seam: orgs listed comma-separated in this file are treated as rate-limited by `proxy` |
 

package/bin/claude-org.js

@@ -10,6 +10,23 @@ const { statusAll } = require('../lib/status');
 const { watch } = require('../lib/watch');
 const { proxyLaunch } = require('../lib/proxy');
 
+// `--model <id>` / `--model=<id>` for probe and status. Returns the model
+// ('' when absent) and the remaining args. A missing value is an error rather
+// than a silent fall back to the default model.
+function takeModel(args) {
+  const rest = [];
+  let model = '';
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--model' || args[i].startsWith('--model=')) {
+      model = args[i] === '--model' ? args[++i] : args[i].slice(8);
+      if (!model || model.startsWith('-')) throw new Error('--model needs a model id, e.g. --model claude-fable-5-1');
+    } else {
+      rest.push(args[i]);
+    }
+  }
+  return { model, rest };
+}
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   switch (cmd) {
@@ -23,11 +40,12 @@ async function main() {
       for (const o of listOrgs()) console.log(o);
       return 0;
     case 'status':
-      return statusAll();
+      return statusAll(takeModel(rest).model || undefined);
     case 'probe': {
-      const r = await probe(rest[0] || resolvePrefer());
+      const { model, rest: names } = takeModel(rest);
+      const r = await probe(names[0] || resolvePrefer(), model || undefined);
       if (r.line) console.log(r.line);
-      return r.allowed ? 0 : 1;
+      return r.usable ? 0 : 1;
     }
     case 'pick':
       console.log(await pick());

package/lib/pick.js

@@ -3,18 +3,23 @@ const { resolvePrefer } = require('./config');
 const { probe } = require('./probe');
 
 // pick(): which org `auto` should launch on. Returns 'default' when the
-// preferred org is over its 5h limit (or its token is missing). The decision
-// reason goes to stderr as a single `-> ...` line.
+// preferred org is over its 5h limit (or its token is missing), or refused the
+// model set in CLAUDE_ORG_PROBE_MODEL. The decision reason goes to stderr as a
+// single `-> ...` line.
 async function pick() {
   const prefer = resolvePrefer();
   const r = await probe(prefer);
-  if (r.allowed) {
+  if (r.usable) {
     let util = r.util;
     if (util !== '?') util = `${Math.trunc(Number(util) * 100)}%`;
     console.error(`-> ${prefer} (5h ${util} used)`);
     return prefer;
   }
-  console.error(`-> default (${prefer} is ${r.status}, resets ${r.resetLocal})`);
+  if (r.allowed) {
+    console.error(`-> default (${prefer} refused model ${r.model})`);
+  } else {
+    console.error(`-> default (${prefer} is ${r.status}, resets ${r.resetLocal})`);
+  }
   return 'default';
 }
 

package/lib/probe.js

@@ -2,18 +2,78 @@
 const { readToken } = require('./config');
 const { epochToHHMM } = require('./time');
 
-// probe(name): send a 1-token inference request and read the unified 5h
-// rate-limit headers. Returns { line, status, util, reset, resetLocal, allowed }.
-// `line` is the canonical one-line output:
+const DEFAULT_MODEL = 'claude-haiku-4-5-20251001';
+
+// Whether the org served the probed model. The 5h window is shared by every
+// model, but a model can still be refused while it reads "allowed" (it needs
+// usage credits, or its own weekly allowance is used up), so this is judged
+// from the HTTP status, not from the window headers.
+//   available    2xx
+//   unavailable  any other 4xx, while neither the 5h nor the 7d window is
+//                rejected
+//   unknown      no response, 401/403 (token or org permission), 408, 5xx, or
+//                a rejected window (which hides whether the model itself
+//                would be served)
+function judgeModel(res) {
+  if (!res) return 'unknown';
+  if (res.ok) return 'available';
+  const h = name => res.headers.get(`anthropic-ratelimit-unified-${name}`);
+  if (h('5h-status') === 'rejected' || h('7d-status') === 'rejected') return 'unknown';
+  if ([401, 403, 408].includes(res.status) || res.status >= 500 || res.status < 400) return 'unknown';
+  return 'unavailable';
+}
+
+// One 1-token request. Returns { res, errorType }: res is null when no response
+// came; errorType is error.type of a non-2xx JSON body ('' otherwise).
+async function send(tok, model) {
+  const base = (process.env.CLAUDE_ORG_UPSTREAM || 'https://api.anthropic.com').replace(/\/+$/, '');
+  try {
+    const res = await fetch(`${base}/v1/messages`, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${tok}`,
+        'anthropic-beta': 'oauth-2025-04-20',
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ model, max_tokens: 1, messages: [{ role: 'user', content: 'hi' }] }),
+      signal: AbortSignal.timeout(20000),
+    });
+    let errorType = '';
+    if (res.ok) {
+      res.body && res.body.cancel().catch(() => {});
+    } else {
+      try {
+        errorType = String(JSON.parse(await res.text()).error.type || '').replace(/[^\w.-]/g, '_').slice(0, 60);
+      } catch {
+        errorType = ''; // not a JSON error body: the HTTP status still decides model_status
+      }
+    }
+    return { res, errorType };
+  } catch {
+    return { res: null, errorType: '' };
+  }
+}
+
+// probe(name, model): send a 1-token inference request and read the unified
+// 5h rate-limit headers. Returns { line, status, util, reset, resetLocal,
+// allowed, model, modelStatus, usable }. `line` is the canonical one-line output:
 //   status=<allowed|rejected|unknown> 5h_util=<0.xx|?> 5h_reset=<epoch|?> 5h_reset_local=<HH:MM|?>
+// When a model is given (argument, else CLAUDE_ORG_PROBE_MODEL), the request
+// uses it and the line ends with ` model=<id> model_status=<see judgeModel>`,
+// plus ` model_error=<error.type>` when the model was refused.
+// Without one the request uses Haiku and the line is unchanged. `usable` is
+// "allowed and the model was not refused".
 //
 // Test seam: CLAUDE_ORG_FORCE_PROBE = allowed | rejected[:<epoch>] |
 // rejected_until:<epoch> (rejected_until flips to allowed once <epoch> passes).
 // When forced, the token file is not required and no request is sent.
 // CLAUDE_ORG_UPSTREAM overrides the API base URL (stub upstream in tests).
-async function probe(name) {
+async function probe(name, model = process.env.CLAUDE_ORG_PROBE_MODEL || '') {
   const forced = process.env.CLAUDE_ORG_FORCE_PROBE;
   let status, util, reset;
+  let modelStatus = 'unknown';
+  let modelError = '';
   if (forced) {
     const idx = forced.indexOf(':');
     status = idx === -1 ? forced : forced.slice(0, idx);
@@ -24,29 +84,26 @@ async function probe(name) {
     util = '?';
   } else {
     const tok = readToken(name);
-    if (tok === null) return { line: null, status: 'unknown', util: '?', reset: '?', resetLocal: '?', allowed: false };
-    const base = (process.env.CLAUDE_ORG_UPSTREAM || 'https://api.anthropic.com').replace(/\/+$/, '');
-    let headers = null;
-    try {
-      const res = await fetch(`${base}/v1/messages`, {
-        method: 'POST',
-        headers: {
-          authorization: `Bearer ${tok}`,
-          'anthropic-beta': 'oauth-2025-04-20',
-          'anthropic-version': '2023-06-01',
-          'content-type': 'application/json',
-        },
-        body: JSON.stringify({
-          model: 'claude-haiku-4-5-20251001',
-          max_tokens: 1,
-          messages: [{ role: 'user', content: 'hi' }],
-        }),
-        signal: AbortSignal.timeout(20000),
-      });
-      headers = res.headers;
-      res.body && res.body.cancel().catch(() => {});
-    } catch {
-      headers = null;
+    if (tok === null) {
+      return { line: null, status: 'unknown', util: '?', reset: '?', resetLocal: '?', allowed: false, model, modelStatus, usable: false };
+    }
+    const first = await send(tok, model || DEFAULT_MODEL);
+    let headers = first.res && first.res.headers;
+    modelStatus = judgeModel(first.res);
+    if (modelStatus === 'unavailable') modelError = first.errorType;
+    // A refusal for the model itself carried no window headers on 2026-10-10
+    // (Fable 5.1 on an org without usage credits), so the 5h state is read
+    // from a second request with the default model.
+    if (model && modelStatus === 'unavailable' && !headers.get('anthropic-ratelimit-unified-5h-status')) {
+      const second = await send(tok, DEFAULT_MODEL);
+      headers = second.res && second.res.headers;
+      // A rejected window there means the first 429 may have been the window,
+      // not the model, so the model cannot be judged.
+      const w = name => headers && headers.get(`anthropic-ratelimit-unified-${name}`);
+      if (w('5h-status') === 'rejected' || w('7d-status') === 'rejected') {
+        modelStatus = 'unknown';
+        modelError = '';
+      }
     }
     status = (headers && (headers.get('anthropic-ratelimit-unified-5h-status')
       || headers.get('anthropic-ratelimit-unified-status'))) || 'unknown';
@@ -54,8 +111,12 @@ async function probe(name) {
     reset = (headers && headers.get('anthropic-ratelimit-unified-5h-reset')) || '?';
   }
   const resetLocal = reset !== '?' ? epochToHHMM(reset) : '?';
-  const line = `status=${status} 5h_util=${util} 5h_reset=${reset} 5h_reset_local=${resetLocal}`;
-  return { line, status, util, reset, resetLocal, allowed: status === 'allowed' };
+  let line = `status=${status} 5h_util=${util} 5h_reset=${reset} 5h_reset_local=${resetLocal}`;
+  // The model is user input; keep the key=value line parseable.
+  if (model) line += ` model=${model.replace(/[^\w.:@/-]/g, '_')} model_status=${modelStatus}${modelError ? ` model_error=${modelError}` : ''}`;
+  const allowed = status === 'allowed';
+  const usable = allowed && !(model && modelStatus === 'unavailable');
+  return { line, status, util, reset, resetLocal, allowed, model, modelStatus, usable };
 }
 
 module.exports = { probe };

package/lib/proxy.js

@@ -21,9 +21,13 @@
 //                          "listening on" stderr line)
 //   CLAUDE_ORG_TOKEN_DIR   where <name>.token files live (~/.claude/org-tokens)
 //   CLAUDE_ORG_ORDER       org priority, comma-separated (default: alphabetical)
+//   CLAUDE_ORG_STRATEGY    "least-utilized": prefer the usable org with the
+//                          lowest 5h utilization seen so far (default: ORDER)
 //   CLAUDE_ORG_UPSTREAM    forward target (default https://api.anthropic.com)
 //   CLAUDE_ORG_REJECT_FILE test seam: orgs listed comma-separated in this file
 //                          are treated as rate-limited
+//   CLAUDE_ORG_STATE_FILE  where the org and model of the last /v1/messages
+//                          response are written as JSON (unset: not written)
 const http = require('http');
 const https = require('https');
 const fs = require('fs');
@@ -119,12 +123,16 @@ function createProxy(opts = {}) {
     || (process.env.CLAUDE_ORG_ORDER || '').split(',').map(s => s.trim()).filter(Boolean);
   const UPSTREAM = new URL(opts.upstream || process.env.CLAUDE_ORG_UPSTREAM || 'https://api.anthropic.com');
   const REJECT_FILE = 'rejectFile' in opts ? opts.rejectFile : (process.env.CLAUDE_ORG_REJECT_FILE || '');
+  const STATE_FILE = 'stateFile' in opts ? opts.stateFile : (process.env.CLAUDE_ORG_STATE_FILE || '');
+  const STRATEGY = 'strategy' in opts ? opts.strategy : (process.env.CLAUDE_ORG_STRATEGY || '');
   const out = opts.log || process.stderr;
   const transport = UPSTREAM.protocol === 'http:' ? http : https;
 
   function log(...a) {
     out.write(`[claude-org-proxy ${new Date().toISOString().slice(11, 19)}] ${a.join(' ')}\n`);
   }
+  const leastUtilized = STRATEGY === 'least-utilized';
+  if (STRATEGY && !leastUtilized) log(`unknown CLAUDE_ORG_STRATEGY "${STRATEGY}" -> using the static order`);
 
   function listOrgs() {
     const files = fs.readdirSync(TOKEN_DIR).filter(f => f.endsWith('.token')).map(f => f.slice(0, -6)).sort();
@@ -163,12 +171,63 @@ function createProxy(opts = {}) {
     if (Date.now() >= until) { rejectedUntil.delete(name); return false; }
     return true;
   }
+  // Latest 5h utilization (0..1) each org reported, valid until that window's
+  // reset: name -> { util, until (epoch ms) }. An org that is not picked would
+  // otherwise keep its old high value after its window resets.
+  const utilization = new Map();
+  // Orgs that answered without a utilization header, so they are not put first
+  // again and again as "not measured yet".
+  const answeredUnmeasured = new Set();
+  function utilOf(name) {
+    const e = utilization.get(name);
+    if (e === undefined) return undefined;
+    if (Date.now() >= e.until) { utilization.delete(name); return undefined; }
+    return e.util;
+  }
+  function recordUtil(name, util, reset) {
+    const until = Number.isFinite(reset) ? reset * 1000 : Infinity;
+    utilization.set(name, { util, until });
+    answeredUnmeasured.delete(name);
+  }
   // Usable orgs first, in priority order; rate-limited orgs are moved to the
   // tail (kept as a last resort when everything is limited).
+  // least-utilized: among the usable orgs, those that have not been measured
+  // come first (in priority order) so that each is measured once, then the
+  // rest by utilization, lowest first, then those that answered without a
+  // utilization. Utilization is a share of each org's own plan, not an
+  // absolute amount, so a larger plan is picked more often.
   function pickOrder(model) {
     const orgs = listOrgs();
     const blocked = o => isRejected(o) || isModelRejected(o, model);
-    return orgs.filter(o => !blocked(o)).concat(orgs.filter(blocked));
+    let usable = orgs.filter(o => !blocked(o));
+    if (leastUtilized) {
+      const known = usable.filter(o => utilOf(o) !== undefined).sort((a, b) => utilOf(a) - utilOf(b));
+      const unknown = usable.filter(o => utilOf(o) === undefined);
+      usable = unknown.filter(o => !answeredUnmeasured.has(o))
+        .concat(known, unknown.filter(o => answeredUnmeasured.has(o)));
+    }
+    return usable.concat(orgs.filter(blocked));
+  }
+
+  // Claude Code does not show the x-claude-org response header, so the org in
+  // use is written to a file that a statusline or hook can read. Written via a
+  // rename so a reader never sees a half-written file. No prompt or token goes in.
+  // The model is stored in full (JSON escapes it), unlike the cut log copy, so
+  // two long model names stay distinguishable.
+  // On Windows the rename fails while a reader holds the file open; that write
+  // is skipped and only the first failure is logged, to keep the log readable.
+  let stateWriteFailed = false;
+  function writeState(org, model, status) {
+    if (!STATE_FILE) return;
+    const tmp = `${STATE_FILE}.${process.pid}.tmp`;
+    try {
+      fs.writeFileSync(tmp, JSON.stringify({ org, model, status, at: new Date().toISOString() }) + '\n');
+      fs.renameSync(tmp, STATE_FILE);
+    } catch (e) {
+      try { fs.unlinkSync(tmp); } catch { /* the tmp file was never created */ }
+      if (!stateWriteFailed) log(`cannot write state file ${STATE_FILE}: ${e.message} (further failures are not logged)`);
+      stateWriteFailed = true;
+    }
   }
 
   function forward(org, method, urlPath, headers, body) {
@@ -214,6 +273,12 @@ function createProxy(opts = {}) {
         const status5h = hdr('5h-status');
         const status7d = hdr('7d-status');
         const claim = hdr('representative-claim');
+        const util5h = Number(hdr('5h-utilization'));
+        if (isModelReq && hdr('5h-utilization') !== undefined && Number.isFinite(util5h)) {
+          recordUtil(org, util5h, Number(hdr('5h-reset')));
+        } else if (isModelReq) {
+          answeredUnmeasured.add(org);
+        }
         // The 5h and 7d windows cover every model of the org, so only those make
         // the org as a whole unusable. Other refusals are per model: a used-up
         // per-model weekly allowance (claim=seven_day_overage_included) or a model
@@ -263,7 +328,8 @@ function createProxy(opts = {}) {
         }
         if (isModelReq) {
           const util = hdr('5h-utilization');
-          log(`${clientReq.method} ${clientReq.url} via ${org} -> ${up.statusCode} (5h ${status5h ?? '?'} ${util ?? '?'})${reason ? ` ${reason}` : ''}`);
+          log(`${clientReq.method} ${clientReq.url} via ${org} model=${logModel(model)} -> ${up.statusCode} (5h ${status5h ?? '?'} ${util ?? '?'})${reason ? ` ${reason}` : ''}`);
+          writeState(org, model, up.statusCode);
           if (modelRefused && modelRefusals === attempt - 1) {
             log(`all orgs rejected model ${logModel(model)} -> switch the model (e.g. /model) or wait for that model's limit to reset; the org tokens are not the cause`);
           }
@@ -276,12 +342,13 @@ function createProxy(opts = {}) {
         }
         return;
       }
+      if (isModelReq) writeState(null, model, 503); // no org served it
       clientRes.writeHead(503, { 'content-type': 'application/json' });
       clientRes.end(JSON.stringify({ type: 'error', error: { type: 'claude_org_proxy', message: 'all orgs rate-limited or unreachable' } }));
     });
   });
 
-  return { server, listOrgs, log, upstream: UPSTREAM };
+  return { server, listOrgs, log, upstream: UPSTREAM, strategy: leastUtilized ? 'least-utilized' : 'order' };
 }
 
 // `claude-org proxy [claude args...]`: start an in-process proxy on a random
@@ -299,15 +366,17 @@ async function proxyLaunch(args) {
   }
 
   const order = process.env.CLAUDE_ORG_ORDER || resolvePrefer();
-  const logf = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'claude-org-proxy-')), 'proxy.log');
+  const runDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-org-proxy-'));
+  const logf = path.join(runDir, 'proxy.log');
+  const stateFile = path.join(runDir, 'state.json');
   const logStream = fs.createWriteStream(logf);
-  const { server, log, upstream } = createProxy({ order: order.split(','), log: logStream });
+  const { server, log, upstream, strategy } = createProxy({ order: order.split(','), log: logStream, stateFile });
 
   try {
     await new Promise((resolve, reject) => {
       server.once('error', reject);
       server.listen(0, '127.0.0.1', () => {
-        log(`listening on http://127.0.0.1:${server.address().port} orgs=${listOrgs().join(',')} upstream=${upstream.host}`);
+        log(`listening on http://127.0.0.1:${server.address().port} orgs=${listOrgs().join(',')} upstream=${upstream.host} strategy=${strategy}`);
         resolve();
       });
     });
@@ -316,7 +385,7 @@ async function proxyLaunch(args) {
     return 1;
   }
   const port = server.address().port;
-  console.error(`-> proxy 127.0.0.1:${port} (order: ${order}, log: ${logf})`);
+  console.error(`-> proxy 127.0.0.1:${port} (order: ${order}, strategy: ${strategy}, log: ${logf})`);
 
   // A custom ANTHROPIC_BASE_URL + AUTH_TOKEN makes Claude Code treat the session
   // as API-key auth: prompt cache TTL drops to 5min and MCP tool search is
@@ -325,6 +394,7 @@ async function proxyLaunch(args) {
     ANTHROPIC_BASE_URL: `http://127.0.0.1:${port}`,
     ANTHROPIC_AUTH_TOKEN: 'claude-org-proxy', // dummy; the proxy replaces it
     CLAUDE_ORG_PROXY: '1',                    // marker: "connector MCPs unavailable" session
+    CLAUDE_ORG_STATE_FILE: stateFile,         // last org/model, for statusline and hooks
   };
   if (!process.env.CLAUDE_CODE_PROMPT_CACHE_TTL) envExtra.CLAUDE_CODE_PROMPT_CACHE_TTL = '1h';
   if (!process.env.ENABLE_TOOL_SEARCH) envExtra.ENABLE_TOOL_SEARCH = 'true';
@@ -339,9 +409,9 @@ async function proxyLaunch(args) {
 // `node claude-org-proxy.js`).
 if (require.main === module) {
   const PORT = Number(process.env.PORT || 0);
-  const { server, listOrgs, log, upstream } = createProxy();
+  const { server, listOrgs, log, upstream, strategy } = createProxy();
   server.listen(PORT, '127.0.0.1', () => {
-    log(`listening on http://127.0.0.1:${server.address().port} orgs=${listOrgs().join(',')} upstream=${upstream.host}`);
+    log(`listening on http://127.0.0.1:${server.address().port} orgs=${listOrgs().join(',')} upstream=${upstream.host} strategy=${strategy}`);
   });
 }
 

package/lib/status.js

@@ -21,7 +21,8 @@ function authStatus(envExtra = {}) {
   });
 }
 
-async function statusAll() {
+// model: passed to probe (undefined -> CLAUDE_ORG_PROBE_MODEL or Haiku).
+async function statusAll(model) {
   for (const name of listOrgs()) {
     const tok = readToken(name);
     if (tok === null) continue;
@@ -29,7 +30,7 @@ async function statusAll() {
     const out = await authStatus({ CLAUDE_CODE_OAUTH_TOKEN: tok });
     const lines = out.split('\n').filter(l => KEYS_RE.test(l));
     console.log(lines.length ? lines.join('\n') : '  (auth status failed)');
-    const r = await probe(name);
+    const r = await probe(name, model);
     if (r.line) console.log(`  ${r.line}`);
   }
   console.log('== default (no env) ==');

package/lib/usage.js

@@ -24,11 +24,15 @@ token org alphabetically):
   claude-org auto [claude args...]    launch on <prefer> if usable, else default
                                     (decided once at launch)
   claude-org <name> [claude args...]  e.g. claude-org work --resume
-  claude-org probe [<name>]           print the org's 5h window state on one line
-                                    (exit 0 when allowed)
+  claude-org probe [<name>] [--model <id>]
+                                    print the org's 5h window state on one line
+                                    (exit 0 when allowed); with --model, probe with
+                                    that model and add model_status= (exit 1 when
+                                    the org refused it)
   claude-org watch                    wait until <prefer> recovers, then notify
                                     (terminal + optional CLAUDE_ORG_NOTIFY_CMD)
-  claude-org status                   show \`claude auth status\` for each org token
+  claude-org status [--model <id>]    show \`claude auth status\` and probe for each
+                                    org token
   claude-org list                     list saved org names
 
 auto / <name> only read env at launch, so they cannot switch mid-session. To keep

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-org",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Switch Claude Code between multiple Anthropic organizations, with automatic failover on the 5-hour rate limit",
   "license": "MIT",
   "type": "commonjs",