@rikcodes/teamclaude 1.1.13-rik.4 → 1.1.14-rik.1

package/README.md

@@ -1,6 +1,6 @@
 # TeamClaude
 
-> **Fork notice (rikbrown).** This fork adds four features and two reload fixes on top of
+> **Fork notice (rikbrown).** This fork adds three features on top of
 > [KarpelesLab/teamclaude](https://github.com/KarpelesLab/teamclaude):
 >
 > - **[OpenAI models via a Codex sidecar](docs/openai.md)** (`sidecars` + `customModels`, opt-in):
@@ -11,16 +11,13 @@
 >   equal-priority accounts by the weekly window that governs the requested model, continuously — preempt the
 >   current account when another resets more than `poolHours` sooner, and balance `distributeSessions` within
 >   that pool instead of across all accounts. Spends the quota closest to refreshing first, so a window no
->   longer rolls over with quota unspent.
+>   longer rolls over with quota unspent. Applied live on config reload.
 > - **[Burn-rate projection](docs/quota.md#burn-rate-projection)** (`projection`, on by default): sample each
 >   bucket's consumption over a rolling window and tag every account row with whichever window binds
 >   first — `Ses TTL 38m` when it runs out before it resets, `Wk 22% unspent` when the reset arrives
 >   first and that much expires. A readout only: no selection code reads it.
-> - **[Session titles](docs/usage.md#session-titles-in-the-activity-log)** (`sessionTitles`, on by default):
->   name each activity row after the Claude Code session that sent the request, reading the title
->   `/rename` writes and the one Claude Code generates. A session with neither keeps its short id.
-> - `soonestWeekly` and `distributeSessions` changes now apply on config reload; upstream applies
->   `distributeSessions` only at startup.
+>
+> Setup and use of each: [Fork features](#fork-features).
 >
 > Published as [`@rikcodes/teamclaude`](https://www.npmjs.com/package/@rikcodes/teamclaude); self-update
 > tracks that package, so installs of this fork can never be replaced by an upstream release.
@@ -59,6 +56,11 @@ teamclaude run       # in another terminal: Claude Code through the proxy
 
 Already logged into Claude Code? `teamclaude import` takes its credentials instead of a fresh OAuth round. API keys, and one email holding accounts in several orgs, are covered in [docs/accounts.md](docs/accounts.md).
 
+`teamclaude run` does not require a separate Claude Code login for normal API
+requests. When local Claude OAuth is unavailable or expired, proxy credential
+mode supplies a local-only bootstrap key; the proxy replaces that placeholder
+with the selected TeamClaude account credential before forwarding.
+
 ## What it does
 
 - Rotates to the next account when the 5h session or 7d weekly bucket reaches the threshold (98% by default), preferring the account whose weekly quota resets soonest.
@@ -104,6 +106,91 @@ Every field, plus environment variables and network tuning: [docs/configuration.
 
 Step-by-step lifecycle: [docs/routing.md](docs/routing.md#request-lifecycle).
 
+## Fork features
+
+How to set up and use the features in this fork. Everything else in this README is upstream behaviour.
+
+### OpenAI models via a Codex sidecar
+
+A Claude Code session can use OpenAI models alongside the Claude accounts. They are billed to a ChatGPT Plus/Pro subscription and use their real model names in the same session. TeamClaude does not translate the wire format itself. A local **sidecar** does this: [raine/claude-code-proxy](https://github.com/raine/claude-code-proxy) speaks `/v1/messages` on the front and the Codex Responses API on the back. TeamClaude starts and supervises this process. It sends every `gpt-*` request to the sidecar and keeps every other request on the Claude accounts.
+
+**1. Install the sidecar and log it into your ChatGPT account** (one time):
+
+```bash
+brew install raine/claude-code-proxy/claude-code-proxy
+claude-code-proxy codex auth login
+```
+
+**2. Connect it** — add four pieces to `~/.config/teamclaude.json`:
+
+```json
+{
+  "sidecars": [
+    { "name": "codex", "command": ["claude-code-proxy", "serve", "--no-monitor", "--port", "18765"] }
+  ],
+  "accounts": [
+    { "name": "codex", "type": "oauth", "accessToken": "unused-local-sidecar",
+      "upstream": "http://127.0.0.1:18765", "priority": 100 }
+  ],
+  "routes": [
+    { "name": "codex", "match": ["gpt-*"], "accounts": ["codex"] },
+    { "name": "anthropic", "match": ["*"], "accounts": ["your-claude-account", "..."] }
+  ],
+  "customModels": [
+    { "model": "gpt-5.6-sol",   "label": "GPT-5.6 Sol",   "contextTokens": 272000 },
+    { "model": "gpt-5.6-terra", "label": "GPT-5.6 Terra", "contextTokens": 272000 },
+    { "model": "gpt-5.6-luna",  "label": "GPT-5.6 Luna",  "contextTokens": 272000 }
+  ]
+}
+```
+
+- `sidecars` — the process that TeamClaude owns. It starts with the server, restarts with backoff after a crash, and stops on shutdown. Its pid, restart count and latest stderr lines are in `teamclaude status --json` under `sidecars`.
+- `accounts` — the sidecar as a [third-party backend account](docs/accounts.md#third-party-backend-accounts). The token is a placeholder because the sidecar uses its own Codex login for authentication. `priority: 100` is the convention for third-party backends. The routes determine what reaches it.
+- `routes` — sends `gpt-*` to the sidecar. **Keep the catch-all `*` route.** Without it, the sidecar joins the exhaustion-fallback pool. A spent Claude fleet would then silently send Claude-model requests to the sidecar, which maps `claude-*` names onto GPT models. With the route, a request can reach a GPT model only when it asks for one by name.
+- `customModels` — the rows that make the models visible to Claude Code (next section).
+
+**3. Restart the server.** `teamclaude status --json` should show the sidecar as `running`. If it enters a crash loop, `stderrTail` explains why — the usual cause is that the sidecar is not logged in.
+
+#### How models get into Claude Code
+
+Claude Code offers only models that it knows, and it does not know `gpt-*`. `customModels` closes this gap. Each row contains a model id that the proxy can serve, an optional picker label and description, and the model's context window.
+
+At launch, `teamclaude run` — and the `claude` alias, which passes through `run` — gives these rows to Claude Code:
+
+| Row field | Where it ends up |
+| --- | --- |
+| `model`, `label`, `description` | A `/model` picker row under the **real** model id (`--settings`), so `/model gpt-5.6-sol` works picked or typed |
+| `model` | A dispatchable subagent named after the model (`--agents`), so "dispatch a `gpt-5.6-terra` subagent" works from a Claude parent |
+| `contextTokens` | `CLAUDE_CODE_MAX_CONTEXT_TOKENS`, set to the largest value across rows, so Claude Code compacts at the real window instead of assuming 200k |
+
+For tools that spawn `claude` themselves, `teamclaude env` can set only environment variables. It carries the window and `ANTHROPIC_CUSTOM_MODEL_OPTION` for the **first** row. For GPT subagents under `env`, create `~/.claude/agents/<name>.md` with `model: gpt-5.6-terra` in its frontmatter.
+
+Each request is routed by the model name in its body, so one session can freely mix models: use `claude --model gpt-5.6-sol` for a whole session, `/model gpt-5.6-sol` during a session, or a Claude parent that dispatches a GPT subagent.
+
+**To add a model:**
+
+1. Check that your sidecar build lists it: `curl -s http://127.0.0.1:18765/v1/models`. The sidecar has its own allow-list and rejects any id that it does not know, regardless of the TeamClaude configuration. Upgrade the sidecar if the id is missing.
+2. Add a `customModels` row. Codex publishes the window for each model as `context_window` in `~/.codex/models_cache.json`; copy it to `contextTokens`.
+3. Start a new `teamclaude run` session. The rows are read at launch, so you do not need to restart the server. If you upgraded the sidecar binary, restart the server — or send `SIGTERM` to the sidecar process and let the supervisor restart it with the new binary.
+
+Claude Code prints one `[claude-code:unrecognized_model]` line to stderr for each custom model. This is expected; suppressing it would lose the correct context window. The quota bars for the sidecar account show `unknown` unless the sidecar forwards Codex's rate-limit headers — see [Quota](docs/openai.md#quota). Keep the sidecar on loopback, and use **one** ChatGPT subscription for each person. Pooling several subscriptions is the pattern that OpenAI's fraud systems target ([terms of service](docs/openai.md#terms-of-service)).
+
+Full details: [docs/openai.md](docs/openai.md).
+
+### Soonest-weekly rotation
+
+Default selection is sticky. It re-ranks only when the current account is exhausted, so a weekly window can expire with unused quota. `soonestWeekly` re-ranks continuously. Among equal-priority accounts, the one whose governing weekly window resets soonest is used first. It preempts the current account when another account resets more than `poolHours` sooner.
+
+```json
+"soonestWeekly": { "enabled": true, "poolHours": 12 }
+```
+
+`distributeSessions` works with this setting. New sessions balance across that pool instead of across all equal-priority accounts. Both settings take effect when the configuration reloads (upstream applies `distributeSessions` only at startup). Details: [Routing](docs/routing.md#soonest-weekly-rotation).
+
+### Burn-rate projection
+
+This feature is on by default. Each account row shows which window binds first: `Ses TTL 38m` when the session bucket runs out before it resets, or `Wk 22% unspent` when the weekly reset arrives first and that amount of quota expires. This is a readout only; no selection code reads it. Tune or disable it with `projection: { enabled, windowMinutes, wasteFloor }`. Details: [Quota](docs/quota.md#burn-rate-projection).
+
 ## Documentation
 
 | Page | Contents |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rikcodes/teamclaude",
-  "version": "1.1.13-rik.4",
+  "version": "1.1.14-rik.1",
   "description": "Multi-account Claude proxy with automatic quota-based rotation",
   "type": "module",
   "main": "src/index.js",

package/src/account-id.js

@@ -0,0 +1,52 @@
+// The identifier a config account entry carries, and the reason it has to exist.
+//
+// The config list and the AccountManager's are not positionally aligned:
+// resolveAccounts drops every entry without a usable credential, so from the
+// first drop onward a config index and a manager index name different accounts
+// for the life of the process. Nothing on the records recovers the pairing
+// either. Two entries can agree on name, account, organization and credential,
+// and the credential — the one field that might separate two records of one
+// person — is rewritten by the token refresh that makes the pairing matter.
+//
+// So an entry carries an identifier of its own, assigned before anything can
+// read one, never rewritten afterwards, and copied onto the account built from
+// the entry by makeAccount.
+
+import { randomUUID } from 'node:crypto';
+
+/**
+ * A fresh entry id.
+ *
+ * Minted where an entry and the account built from it are created together — the
+ * TUI's add paths — because the two have to agree on an id before anything reads
+ * one. An entry created anywhere else reaches memory through loadConfig or an
+ * admission from disk, and both of those assign ids, so those paths mint none of
+ * their own.
+ */
+export function mintAccountId() {
+  return randomUUID();
+}
+
+/**
+ * Give every entry in `accounts` an id that no other entry in the list holds,
+ * mutating them in place, and return the list.
+ *
+ * Entry creation mints an id, so this is for entries that arrive already made:
+ * a config written before the field existed, and an entry admitted from disk
+ * while the server runs. Calling it as those enter an in-memory list is what
+ * makes the uniqueness every lookup assumes true from the first read.
+ *
+ * A duplicate is re-minted rather than kept. Copying an account section by hand
+ * copies its id along with it, and two entries answering to one id collapse
+ * onto whichever comes first — the later one would be handed the earlier one's
+ * credential, which is the crossing this field exists to prevent.
+ */
+export function ensureAccountIds(accounts) {
+  const seen = new Set();
+  for (const acct of accounts || []) {
+    if (!acct) continue;
+    if (typeof acct.id !== 'string' || acct.id === '' || seen.has(acct.id)) acct.id = mintAccountId();
+    seen.add(acct.id);
+  }
+  return accounts;
+}