subrouter 0.1.0__tar.gz

subrouter-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,173 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      create_github_release:
+        description: "Create or update the GitHub release"
+        required: true
+        type: boolean
+        default: false
+      publish_npm:
+        description: "Publish to npm through trusted publishing"
+        required: true
+        type: boolean
+        default: false
+      publish_pypi:
+        description: "Publish to PyPI through trusted publishing"
+        required: true
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and verify artifacts
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Determine release version
+        id: version
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            version="${GITHUB_REF_NAME#v}"
+          else
+            version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          fi
+
+          package_version="$(node -p "require('./package.json').version")"
+          python_version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+
+          if [[ "${version}" != "${package_version}" || "${version}" != "${python_version}" ]]; then
+            echo "version mismatch: release=${version} package.json=${package_version} pyproject.toml=${python_version}" >&2
+            exit 1
+          fi
+
+          echo "version=${version}" >> "${GITHUB_OUTPUT}"
+
+      - name: Test Go packages
+        run: CGO_ENABLED=0 go test ./...
+
+      - name: Build Go release binaries
+        run: scripts/build-release.sh "${{ steps.version.outputs.version }}"
+
+      - name: Check npm package
+        run: npm pack --dry-run
+
+      - name: Build Python package
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/subrouter-*.tar.gz dist/subrouter-*.whl
+
+      - name: Upload Go release artifacts
+        uses: actions/upload-artifact@v5
+        with:
+          name: release-assets
+          path: dist/release/*
+          if-no-files-found: error
+
+      - name: Upload Python distributions
+        uses: actions/upload-artifact@v5
+        with:
+          name: python-dist
+          path: |
+            dist/subrouter-*.tar.gz
+            dist/subrouter-*.whl
+          if-no-files-found: error
+
+  github-release:
+    name: Publish GitHub release
+    needs: build
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'push' || github.event.inputs.create_github_release == 'true' }}
+    permissions:
+      contents: write
+    steps:
+      - name: Download Go release artifacts
+        uses: actions/download-artifact@v5
+        with:
+          name: release-assets
+          path: dist/release
+
+      - name: Create or update GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG_NAME: v${{ needs.build.outputs.version }}
+        run: |
+          set -euo pipefail
+          if gh release view "${TAG_NAME}" >/dev/null 2>&1; then
+            gh release upload "${TAG_NAME}" dist/release/* --clobber
+          else
+            gh release create "${TAG_NAME}" dist/release/* \
+              --title "Subrouter ${TAG_NAME}" \
+              --notes "Subrouter ${TAG_NAME}"
+          fi
+
+  npm-publish:
+    name: Publish npm package
+    needs: build
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'push' || github.event.inputs.publish_npm == 'true' }}
+    environment: npm
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Publish to npm
+        run: npm publish --access public
+
+  pypi-publish:
+    name: Publish PyPI package
+    needs: build
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'push' || github.event.inputs.publish_pypi == 'true' }}
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download Python distributions
+        uses: actions/download-artifact@v5
+        with:
+          name: python-dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

subrouter-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+/subrouter
+bin/
+!npm/bin/
+!npm/bin/*.js
+*.test
+coverage.out
+.venv/
+__pycache__/
+dist/
+*.egg-info/

subrouter-0.1.0/AGENTS.md

@@ -0,0 +1,11 @@
+# subrouter
+
+Go service for routing AI coding-agent traffic across subscription accounts and API keys.
+
+## Development
+
+- Use `go test ./...` before handing off changes.
+- Keep credential handling read-only unless a command explicitly delegates to the upstream account manager, such as `cx`.
+- Do not log access tokens, refresh tokens, API keys, request bodies, or complete Authorization headers.
+- Prefer standard-library networking primitives unless a dependency removes meaningful complexity.
+

subrouter-0.1.0/LICENSE

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

subrouter-0.1.0/Makefile

@@ -0,0 +1,24 @@
+export CGO_ENABLED := 0
+
+.PHONY: test run build build-linux accounts mock-upstream
+
+test:
+	go test ./...
+
+run:
+	go run ./cmd/subrouter serve
+
+build:
+	CGO_ENABLED=1 go build -ldflags='-linkmode external' -o bin/subrouter ./cmd/subrouter
+	CGO_ENABLED=1 go build -ldflags='-linkmode external' -o bin/mockupstream ./cmd/mockupstream
+	codesign -s - -f bin/subrouter
+	codesign -s - -f bin/mockupstream
+
+build-linux:
+	GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o bin/subrouter-linux-amd64 ./cmd/subrouter
+
+accounts:
+	go run ./cmd/subrouter accounts
+
+mock-upstream:
+	go run ./cmd/mockupstream

subrouter-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: subrouter
+Version: 0.1.0
+Summary: Routes AI coding-agent traffic across subscription accounts and API keys.
+Project-URL: Homepage, https://github.com/manaflow-ai/subrouter
+Project-URL: Repository, https://github.com/manaflow-ai/subrouter
+Project-URL: Issues, https://github.com/manaflow-ai/subrouter/issues
+Author: Manaflow
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Go
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Subrouter
+
+Subrouter is a local AI coding-agent proxy. It routes traffic across Codex accounts with sticky conversation-to-account assignment so cached context stays useful.
+
+## Goals
+
+- Run fast on a Mac Mini.
+- Forward requests with normal Go reverse-proxy behavior, including headers and streaming responses.
+- Support subscription accounts first, API keys second.
+- Keep each conversation pinned to one account.
+- Pick a fresh account for a new conversation based on available rate-limit headroom.
+- Provide the Codex account manager and daemon in one Go binary.
+
+## Current shape
+
+```bash
+make accounts
+make run
+```
+
+This repo sets `CGO_ENABLED=0` in `Makefile` because the local macOS Go 1.22 toolchain is currently producing cgo test binaries that fail before startup with `missing LC_UUID load command`.
+
+## Install
+
+Install with npm:
+
+```bash
+npm install -g subrouter
+```
+
+Install with Python:
+
+```bash
+pipx install subrouter
+```
+
+Both packages install `subrouter`, `sr`, and `cx`. The wrappers download the matching Go release binary for macOS, Linux, Windows, FreeBSD, OpenBSD, or NetBSD on amd64, arm64, or supported 32-bit variants. Set `SUBROUTER_BIN` to use a local binary instead.
+
+## Local macOS daemon
+
+On macOS, install Subrouter as a localhost-only LaunchAgent:
+
+```bash
+make build
+./bin/subrouter install-daemon
+```
+
+This installs the binary to `~/bin/subrouter`, installs `~/bin/cx` as a symlink to the same Go binary, writes `~/Library/LaunchAgents/ai.manaflow.subrouter.plist`, creates `~/.subrouter/transcripts`, starts the service, and runs:
+
+```bash
+~/bin/subrouter serve --addr 127.0.0.1:31415 --transcripts ~/.subrouter/transcripts --cx-switch-interval 10m
+```
+
+The 10 minute `cx` auto-switch interval is the default. Override it with `subrouter install-daemon --cx-switch-interval 5m`, or disable it with `--cx-switch-interval 0`. This command is macOS-specific; use a systemd unit or another supervisor on Linux.
+
+Useful endpoints:
+
+```text
+GET /_subrouter/health
+GET /_subrouter/accounts
+GET /_subrouter/sessions
+GET /_subrouter/dashboard
+GET /_subrouter/transcripts
+```
+
+## GCP deployment
+
+See [deploy/gcp/README.md](deploy/gcp/README.md) for the small GCP + Tailscale Subrouter deployment flow.
+
+To persist raw Subrouter transcripts, pass a transcript directory:
+
+```bash
+subrouter serve --transcripts ~/.subrouter/transcripts
+```
+
+Transcripts are JSONL files keyed by agent type and session id under `by-agent/<agent-type>/by-session/<agent-session-id>.jsonl`. They include Subrouter metadata, redacted headers, HTTP bodies, SSE bodies, and WebSocket message payloads as base64 with byte counts and SHA-256 hashes. Each event includes `agent_type` and `agent_session_id`; Codex events also include `codex_session_id` for matching `~/.codex/sessions` JSONL files. This is intentionally storage-heavy and can contain sensitive request/response payloads. Authorization-style headers are redacted, but bodies are stored in full.
+
+When transcript recording is enabled, `/_subrouter/dashboard` serves an internal HTML dashboard over the same Subrouter listener. It shows token usage over time, usage by user email, usage by selected account, session assignments, transcript summaries, and links to sanitized transcript event JSON under `/_subrouter/transcripts/<agent-type>/<session-id>`. Raw internal trajectory JSON with decoded body text is available under `/_subrouter/transcripts/<agent-type>/<session-id>/raw`.
+
+To mirror transcripts to GCS without blocking proxy requests, also pass a `gs://` destination:
+
+```bash
+subrouter serve --transcripts ~/.subrouter/transcripts --transcript-gcs-uri gs://bucket/prefix
+```
+
+The daemon shells out to `gsutil -m rsync -r` on a background interval. Local transcript writes stay on the request path; GCS upload failures are logged and retried later.
+
+For best cache behavior, clients should send a stable header per conversation:
+
+```text
+X-Subrouter-Session: <conversation-or-thread-id>
+```
+
+If that header is missing, Subrouter checks Codex headers such as `x-codex-window-id` and `x-codex-turn-state`, common session headers, query params, and small JSON bodies for `session_id`, `conversation_id`, or `thread_id`.
+
+Subrouter scopes sticky assignments and transcript files by agent type. It infers `codex`, `claude`, or `gemini` from provider session headers, and clients can set an explicit namespace:
+
+```text
+X-Subrouter-Agent: codex
+```
+
+For teammate-level graphs, clients can also send a self-reported user header:
+
+```text
+X-Subrouter-User-Email: alice@example.com
+```
+
+Subrouter stores the normalized email on the session assignment, includes it in proxy logs as `user`, and exposes it in `GET /_subrouter/sessions`. This is observability metadata, not authentication. To force a selected account, send `X-Subrouter-Account-ID`; API-key labels can omit the `apikey:` prefix. Subrouter strips `X-Subrouter-Session`, `X-Subrouter-Agent`, `X-Subrouter-User-Email`, `X-Subrouter-User`, `X-User-Email`, `X-Subrouter-Account-ID`, and `X-Subrouter-Account` before forwarding upstream.
+
+## Codex CLI
+
+`subrouter codex` is a direct Codex wrapper. Use it anywhere you would use `codex`:
+
+```bash
+subrouter codex
+subrouter codex exec "your prompt"
+subrouter codex --version
+```
+
+The wrapper injects this config override into the child Codex process:
+
+```toml
+openai_base_url = "http://127.0.0.1:31415/v1"
+```
+
+It does not edit Codex config or set auth environment variables. Do not set a dummy `OPENAI_API_KEY` for normal subscription routing. Leave Codex logged in the same way it already is. If Codex is in ChatGPT auth mode, `/model` keeps the subscription model picker. Subrouter replaces outbound credentials with the selected `cx` account before forwarding.
+
+Override the subrouter URL with `SUBROUTER_CODEX_BASE_URL` if needed. See [docs/codex.md](docs/codex.md) for details and the custom-provider fallback.
+
+Set `SUBROUTER_CODEX_USER_EMAIL` to attribute Codex traffic to a teammate:
+
+```bash
+SUBROUTER_CODEX_USER_EMAIL=alice@example.com subrouter codex exec "your prompt"
+```
+
+Force a specific Subrouter account, including an API-key account, with `SUBROUTER_CODEX_ACCOUNT_ID`:
+
+```bash
+SUBROUTER_CODEX_ACCOUNT_ID=team-codex-1 subrouter codex exec "your prompt"
+SUBROUTER_CODEX_ACCOUNT_ID=apikey:team-codex-1 subrouter codex exec "your prompt"
+```
+
+When either variable is set, the wrapper uses a custom `subrouter` provider with WebSockets enabled so Codex can send `X-Subrouter-User-Email` and `X-Subrouter-Account-ID`. Subrouter still replaces outbound credentials before forwarding upstream. `SUBROUTER_CODEX_USER_EMAIL` is only teammate observability metadata; account selection belongs in `SUBROUTER_CODEX_ACCOUNT_ID`.
+
+## Codex accounts
+
+Subrouter has a native Go implementation of the Codex account manager. It reads and writes the existing `cx` store format:
+
+```text
+~/.codex-accounts/accounts/*.json
+```
+
+Account-management commands are built into the `subrouter` binary:
+
+```bash
+go run ./cmd/subrouter cx add
+go run ./cmd/subrouter cx import
+go run ./cmd/subrouter cx list
+go run ./cmd/subrouter cx status
+
+# direct aliases also work
+go run ./cmd/subrouter status
+sr status
+```
+
+The supported Codex commands include `add`, `add-key`, `import`, `list`, `switch`, `gui-switch`, `remove`, `status`, `usage`, `add-admin-key`, `admin-keys`, `remove-admin-key`, and `attach-project`.
+
+`cx switch` also syncs compatible ChatGPT Codex credentials into:
+
+```text
+~/.codex/auth.json
+~/.local/share/opencode/auth.json      # provider key: openai
+~/.pi/agent/auth.json                  # provider key: openai-codex
+```
+
+OpenCode uses XDG data home, so `XDG_DATA_HOME` changes its auth path. pi uses `PI_CODING_AGENT_DIR` when set. Existing unrelated provider credentials in those files are preserved.
+
+Claude profiles are also native Go and use the existing `~/.codex-accounts/claude.json` format:
+
+```bash
+cx claude list
+cx claude switch <profile>
+cx claude env
+cx claude run <profile>
+```
+
+Gemini has its own `cx gemini` namespace and store scaffold so future routing cannot collide with Codex or Claude state.
+
+## Selection policy
+
+On startup, Subrouter fetches current Codex usage for OAuth accounts and scores each account by its most constrained usage window. The scheduler keeps existing sessions sticky. For a new session it protects low-headroom accounts, spends healthy quota that resets soonest, then breaks ties by live assigned-session counts.
+If all else ties, subscription OAuth accounts are preferred before API-key accounts.
+
+The daemon also refreshes usage and updates Codex, OpenCode, and pi auth every 10 minutes by default so local agents follow the same OAuth-only policy. Configure it with `subrouter serve --cx-switch-interval 5m`, or disable it with `--cx-switch-interval 0`. If `--fetch-usage=false`, auto-switch is disabled because fresh usage is required.
+
+By default, OAuth accounts are forwarded to `https://chatgpt.com/backend-api/codex` and API-key accounts are forwarded to `https://api.openai.com`. Subrouter accepts either `/v1/responses` or `/responses` from clients and normalizes the path for the selected account type.
+
+Live headroom comes from Codex subscription usage. API-key spend comes from the OpenAI organization usage endpoints through stored `sk-admin-*` keys. Claude profile usage comes from the Anthropic OAuth usage endpoint when profile credentials are readable.
+
+See [docs/saturation.md](docs/saturation.md) for the 5h/7d placement strategy and simulation tests.
+
+## Security defaults
+
+- Bind to `127.0.0.1` unless explicitly exposed.
+- Do not log tokens, refresh tokens, API keys, request bodies, or full Authorization headers.
+- Keep `~/.codex-accounts` credentials as the canonical local store.

subrouter-0.1.0/README.md

@@ -0,0 +1,206 @@
+# Subrouter
+
+Subrouter is a local AI coding-agent proxy. It routes traffic across Codex accounts with sticky conversation-to-account assignment so cached context stays useful.
+
+## Goals
+
+- Run fast on a Mac Mini.
+- Forward requests with normal Go reverse-proxy behavior, including headers and streaming responses.
+- Support subscription accounts first, API keys second.
+- Keep each conversation pinned to one account.
+- Pick a fresh account for a new conversation based on available rate-limit headroom.
+- Provide the Codex account manager and daemon in one Go binary.
+
+## Current shape
+
+```bash
+make accounts
+make run
+```
+
+This repo sets `CGO_ENABLED=0` in `Makefile` because the local macOS Go 1.22 toolchain is currently producing cgo test binaries that fail before startup with `missing LC_UUID load command`.
+
+## Install
+
+Install with npm:
+
+```bash
+npm install -g subrouter
+```
+
+Install with Python:
+
+```bash
+pipx install subrouter
+```
+
+Both packages install `subrouter`, `sr`, and `cx`. The wrappers download the matching Go release binary for macOS, Linux, Windows, FreeBSD, OpenBSD, or NetBSD on amd64, arm64, or supported 32-bit variants. Set `SUBROUTER_BIN` to use a local binary instead.
+
+## Local macOS daemon
+
+On macOS, install Subrouter as a localhost-only LaunchAgent:
+
+```bash
+make build
+./bin/subrouter install-daemon
+```
+
+This installs the binary to `~/bin/subrouter`, installs `~/bin/cx` as a symlink to the same Go binary, writes `~/Library/LaunchAgents/ai.manaflow.subrouter.plist`, creates `~/.subrouter/transcripts`, starts the service, and runs:
+
+```bash
+~/bin/subrouter serve --addr 127.0.0.1:31415 --transcripts ~/.subrouter/transcripts --cx-switch-interval 10m
+```
+
+The 10 minute `cx` auto-switch interval is the default. Override it with `subrouter install-daemon --cx-switch-interval 5m`, or disable it with `--cx-switch-interval 0`. This command is macOS-specific; use a systemd unit or another supervisor on Linux.
+
+Useful endpoints:
+
+```text
+GET /_subrouter/health
+GET /_subrouter/accounts
+GET /_subrouter/sessions
+GET /_subrouter/dashboard
+GET /_subrouter/transcripts
+```
+
+## GCP deployment
+
+See [deploy/gcp/README.md](deploy/gcp/README.md) for the small GCP + Tailscale Subrouter deployment flow.
+
+To persist raw Subrouter transcripts, pass a transcript directory:
+
+```bash
+subrouter serve --transcripts ~/.subrouter/transcripts
+```
+
+Transcripts are JSONL files keyed by agent type and session id under `by-agent/<agent-type>/by-session/<agent-session-id>.jsonl`. They include Subrouter metadata, redacted headers, HTTP bodies, SSE bodies, and WebSocket message payloads as base64 with byte counts and SHA-256 hashes. Each event includes `agent_type` and `agent_session_id`; Codex events also include `codex_session_id` for matching `~/.codex/sessions` JSONL files. This is intentionally storage-heavy and can contain sensitive request/response payloads. Authorization-style headers are redacted, but bodies are stored in full.
+
+When transcript recording is enabled, `/_subrouter/dashboard` serves an internal HTML dashboard over the same Subrouter listener. It shows token usage over time, usage by user email, usage by selected account, session assignments, transcript summaries, and links to sanitized transcript event JSON under `/_subrouter/transcripts/<agent-type>/<session-id>`. Raw internal trajectory JSON with decoded body text is available under `/_subrouter/transcripts/<agent-type>/<session-id>/raw`.
+
+To mirror transcripts to GCS without blocking proxy requests, also pass a `gs://` destination:
+
+```bash
+subrouter serve --transcripts ~/.subrouter/transcripts --transcript-gcs-uri gs://bucket/prefix
+```
+
+The daemon shells out to `gsutil -m rsync -r` on a background interval. Local transcript writes stay on the request path; GCS upload failures are logged and retried later.
+
+For best cache behavior, clients should send a stable header per conversation:
+
+```text
+X-Subrouter-Session: <conversation-or-thread-id>
+```
+
+If that header is missing, Subrouter checks Codex headers such as `x-codex-window-id` and `x-codex-turn-state`, common session headers, query params, and small JSON bodies for `session_id`, `conversation_id`, or `thread_id`.
+
+Subrouter scopes sticky assignments and transcript files by agent type. It infers `codex`, `claude`, or `gemini` from provider session headers, and clients can set an explicit namespace:
+
+```text
+X-Subrouter-Agent: codex
+```
+
+For teammate-level graphs, clients can also send a self-reported user header:
+
+```text
+X-Subrouter-User-Email: alice@example.com
+```
+
+Subrouter stores the normalized email on the session assignment, includes it in proxy logs as `user`, and exposes it in `GET /_subrouter/sessions`. This is observability metadata, not authentication. To force a selected account, send `X-Subrouter-Account-ID`; API-key labels can omit the `apikey:` prefix. Subrouter strips `X-Subrouter-Session`, `X-Subrouter-Agent`, `X-Subrouter-User-Email`, `X-Subrouter-User`, `X-User-Email`, `X-Subrouter-Account-ID`, and `X-Subrouter-Account` before forwarding upstream.
+
+## Codex CLI
+
+`subrouter codex` is a direct Codex wrapper. Use it anywhere you would use `codex`:
+
+```bash
+subrouter codex
+subrouter codex exec "your prompt"
+subrouter codex --version
+```
+
+The wrapper injects this config override into the child Codex process:
+
+```toml
+openai_base_url = "http://127.0.0.1:31415/v1"
+```
+
+It does not edit Codex config or set auth environment variables. Do not set a dummy `OPENAI_API_KEY` for normal subscription routing. Leave Codex logged in the same way it already is. If Codex is in ChatGPT auth mode, `/model` keeps the subscription model picker. Subrouter replaces outbound credentials with the selected `cx` account before forwarding.
+
+Override the subrouter URL with `SUBROUTER_CODEX_BASE_URL` if needed. See [docs/codex.md](docs/codex.md) for details and the custom-provider fallback.
+
+Set `SUBROUTER_CODEX_USER_EMAIL` to attribute Codex traffic to a teammate:
+
+```bash
+SUBROUTER_CODEX_USER_EMAIL=alice@example.com subrouter codex exec "your prompt"
+```
+
+Force a specific Subrouter account, including an API-key account, with `SUBROUTER_CODEX_ACCOUNT_ID`:
+
+```bash
+SUBROUTER_CODEX_ACCOUNT_ID=team-codex-1 subrouter codex exec "your prompt"
+SUBROUTER_CODEX_ACCOUNT_ID=apikey:team-codex-1 subrouter codex exec "your prompt"
+```
+
+When either variable is set, the wrapper uses a custom `subrouter` provider with WebSockets enabled so Codex can send `X-Subrouter-User-Email` and `X-Subrouter-Account-ID`. Subrouter still replaces outbound credentials before forwarding upstream. `SUBROUTER_CODEX_USER_EMAIL` is only teammate observability metadata; account selection belongs in `SUBROUTER_CODEX_ACCOUNT_ID`.
+
+## Codex accounts
+
+Subrouter has a native Go implementation of the Codex account manager. It reads and writes the existing `cx` store format:
+
+```text
+~/.codex-accounts/accounts/*.json
+```
+
+Account-management commands are built into the `subrouter` binary:
+
+```bash
+go run ./cmd/subrouter cx add
+go run ./cmd/subrouter cx import
+go run ./cmd/subrouter cx list
+go run ./cmd/subrouter cx status
+
+# direct aliases also work
+go run ./cmd/subrouter status
+sr status
+```
+
+The supported Codex commands include `add`, `add-key`, `import`, `list`, `switch`, `gui-switch`, `remove`, `status`, `usage`, `add-admin-key`, `admin-keys`, `remove-admin-key`, and `attach-project`.
+
+`cx switch` also syncs compatible ChatGPT Codex credentials into:
+
+```text
+~/.codex/auth.json
+~/.local/share/opencode/auth.json      # provider key: openai
+~/.pi/agent/auth.json                  # provider key: openai-codex
+```
+
+OpenCode uses XDG data home, so `XDG_DATA_HOME` changes its auth path. pi uses `PI_CODING_AGENT_DIR` when set. Existing unrelated provider credentials in those files are preserved.
+
+Claude profiles are also native Go and use the existing `~/.codex-accounts/claude.json` format:
+
+```bash
+cx claude list
+cx claude switch <profile>
+cx claude env
+cx claude run <profile>
+```
+
+Gemini has its own `cx gemini` namespace and store scaffold so future routing cannot collide with Codex or Claude state.
+
+## Selection policy
+
+On startup, Subrouter fetches current Codex usage for OAuth accounts and scores each account by its most constrained usage window. The scheduler keeps existing sessions sticky. For a new session it protects low-headroom accounts, spends healthy quota that resets soonest, then breaks ties by live assigned-session counts.
+If all else ties, subscription OAuth accounts are preferred before API-key accounts.
+
+The daemon also refreshes usage and updates Codex, OpenCode, and pi auth every 10 minutes by default so local agents follow the same OAuth-only policy. Configure it with `subrouter serve --cx-switch-interval 5m`, or disable it with `--cx-switch-interval 0`. If `--fetch-usage=false`, auto-switch is disabled because fresh usage is required.
+
+By default, OAuth accounts are forwarded to `https://chatgpt.com/backend-api/codex` and API-key accounts are forwarded to `https://api.openai.com`. Subrouter accepts either `/v1/responses` or `/responses` from clients and normalizes the path for the selected account type.
+
+Live headroom comes from Codex subscription usage. API-key spend comes from the OpenAI organization usage endpoints through stored `sk-admin-*` keys. Claude profile usage comes from the Anthropic OAuth usage endpoint when profile credentials are readable.
+
+See [docs/saturation.md](docs/saturation.md) for the 5h/7d placement strategy and simulation tests.
+
+## Security defaults
+
+- Bind to `127.0.0.1` unless explicitly exposed.
+- Do not log tokens, refresh tokens, API keys, request bodies, or full Authorization headers.
+- Keep `~/.codex-accounts` credentials as the canonical local store.