npm - @legioncodeinc/rflectr - Versions diffs - 0.1.0 → 0.1.2 - Mend

@legioncodeinc/rflectr 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (69) hide show

package/library/knowledge/public/guides/claude-desktop.md DELETED Viewed

@@ -1,382 +0,0 @@
-# Claude Desktop Setup
-> Category: Guide | Version: 1.0 | Date: June 2026 | Status: Active
-Point **Claude Desktop** at an **rflectr** gateway on your machine. You get OpenCode Zen, Go, and your configured providers (Groq, Mistral, OpenAI, Gemini, Ollama, …) in Desktop's model picker, with a catalog size you control.
-**What's available:** with third-party inference, Desktop gives you **Cowork** and **Code** only. The regular **Chat** tab (claude.ai-style chat) is not available in this mode. Anthropic calls this **third-party inference** in the Developer menu.
-For Anthropic's upstream docs, see [Installation and setup](https://claude.com/docs/cowork/3p/installation) and [Configuration reference](https://claude.com/docs/cowork/3p/configuration).
----
-## Contents
-- [What you get](#what-you-get)
-- [Known limitations](#known-limitations)
-- [Prerequisites](#prerequisites)
-- [Quick start: automated setup](#quick-start-automated-setup)
-- [Manual setup (network / advanced)](#manual-setup-network--advanced)
-- [Gateway values cheat sheet](#gateway-values-cheat-sheet)
-- [Restore Claude Desktop to Anthropic's servers](#restore-claude-desktop-to-anthropics-servers)
-- [Disable Developer Mode](#disable-developer-mode)
-- [Troubleshooting](#troubleshooting)
-- [Official references](#official-references)
----
-## What you get
-| Piece | Role |
-|---|---|
-| `rflectr server` | Local gateway on port **17645** — Zen, Go, and registry providers. |
-| Claude Desktop gateway config | Desktop sends inference to your machine instead of only claude.ai. |
-| Server wizard filters | Exposed providers, optional favorites-only catalog, discovery-id masking. |
-| **Cowork** tab | Agentic sessions (files, research, multi-step) against your gateway models. |
-| **Code** tab | Claude Code inside Desktop, against your gateway models. |
-**Not included:** Chat (the standard claude.ai chat UI). For that, sign in to Claude Desktop normally without a custom gateway, or use claude.ai in the browser. Billing runs through your OpenCode / provider keys. Keep the server terminal open while you use Desktop.
----
-## Known limitations
-These are Anthropic product constraints, not rflectr bugs.
-| Feature | With rflectr gateway (3P) | With Anthropic 1P (normal sign-in) |
-|---|---|---|
-| **Chat tab** | Not available | Available |
-| **Cowork / Code** | Available | Available (with subscription) |
-| **Claude in Chrome** (browser extension) | **Not available** | Requires Pro, Max, Team, or Enterprise |
-### Claude in Chrome does not work with the gateway
-**Claude in Chrome** (Anthropic's browser-automation extension) is **not compatible** with third-party inference — including a rflectr gateway on `127.0.0.1`. Per Anthropic's [Claude Code + Chrome docs](https://code.claude.com/docs/en/chrome):
-- It requires a direct Anthropic plan (Pro, Max, Team, or Enterprise).
-- It is **not available** through third-party providers (Bedrock, Vertex, Foundry, or a custom gateway).
-- Using Claude exclusively through a gateway means you'd need a **separate claude.ai paid account** for Claude in Chrome — and that extension routes through **Anthropic's servers**, not your gateway.
-API/console credits do not unlock it. **What gateway users can do instead:** use Cowork and Code in Desktop (this guide), use `rflectr claude` in the terminal, or use a dedicated browser-automation tool (e.g. Playwright, a browser MCP). To use Claude in Chrome, [restore 1P mode](#restore-claude-desktop-to-anthropics-servers) and sign in with a paid claude.ai plan.
----
-## Prerequisites
-1. **rflectr** installed: `npm install -g @legioncodeinc/rflectr`.
-2. **OpenCode API key** configured at least once (for `rflectr server`):
-   ```bash
-   rflectr providers add   # if starting fresh
-   rflectr claude          # stores the key in Keychain / credential store
-   ```
-3. **Latest Claude Desktop** from [claude.com/download](https://claude.com/download). Older builds may not show the third-party inference UI.
-4. *(Optional)* providers configured in rflectr — whatever you've set up appears in the server catalog automatically.
-5. *(Optional)* **Favorites** via `rflectr models` to cap the catalog at up to 20 models.
-6. *(Optional)* **Google Vertex** — configure in Desktop (**Developer → third-party inference → Vertex**).
----
-## Quick start: automated setup
-On macOS or Windows, the easiest path is the **automated** command:
-```bash
-rflectr claude-app
-```
-1. Run it.
-2. Select a provider and a model.
-3. rflectr **enables Developer Mode**, configures the gateway to point at itself, and launches Claude Desktop.
-4. **Keep the terminal running** — it's the live proxy for Desktop.
-5. When done, press `Ctrl+C` to stop the proxy and restore your original Desktop configuration.
-If the terminal crashes or you need to recover manually:
-```bash
-rflectr claude-app --restore
-```
----
-## Manual setup (network / advanced)
-Use this if the gateway runs on a different machine (remote desktop, container, home server) or you want a permanent background gateway.
-### Step 1: Start the rflectr server
-```bash
-rflectr server
-```
-Leave it running. First-time wizard recommendations:
-| Prompt | Recommendation |
-|---|---|
-| **Configure & start** vs **Start with saved settings** | *Configure & start* the first time. |
-| **Exposed providers** | Add only what you want in Desktop (Zen, Go, OpenAI, …). |
-| **Mask gateway model ids for discovery?** | **Yes** — Desktop filters competitor names in gateway ids; masking keeps discovery working while display names stay readable. |
-| **Expose only favorite models?** | Optional. |
-| **Listen mode** | **Local only** (`127.0.0.1`) when Desktop runs on the same machine. |
-When it's up:
-```text
-Rflectr server running
-  Anthropic:  http://127.0.0.1:17645/anthropic
-  OpenAI:     http://127.0.0.1:17645/openai
-  API key:    any non-empty value
-```
-Optional health check:
-```bash
-curl -s http://127.0.0.1:17645/health
-curl -s http://127.0.0.1:17645/anthropic/v1/models | head
-```
-### Step 2: Enable Developer Mode
-Third-party inference lives behind **Developer Mode**.
-- **macOS** — menu bar: **Help → Troubleshooting → Enable Developer Mode**.
-- **Windows** — application menu (☰): **Help → Troubleshooting → Enable Developer Mode**.
-The app may relaunch (normal). A **Developer** menu then appears. If you already use Claude Desktop, just enable it from the menu and move on.
-### Step 3: Configure third-party inference
-1. **Developer → Configure third-party inference**.
-2. Open the **Connection** section.
-3. Set:
-| Field | Value |
-|---|---|
-| **Inference provider** | **Gateway** (Anthropic-compatible) |
-| **Gateway base URL** | `http://127.0.0.1:17645/anthropic` |
-| **Gateway API key** | Any non-empty string (e.g. `rflectr`) |
-| **Gateway auth scheme** | `bearer` |
-> ⚠️ **Do not append `/v1` to the base URL.** Claude Desktop adds API paths itself (`/v1/models`, `/v1/messages`). A `.../anthropic/v1` URL breaks discovery and inference.
-4. Leave **model discovery** enabled.
-5. Hit **Test connection** and **Test model discovery** if present.
-6. Click **Apply locally** — the app saves config and relaunches.
-Config lands here:
-| Platform | Path |
-|---|---|
-| macOS | `~/Library/Application Support/Claude-3p/configLibrary/` |
-| Windows | `%LOCALAPPDATA%\Claude-3p\configLibrary\` |
-`Claude-3p` is Anthropic's on-disk layout for third-party inference; ignore it day to day.
-### Step 4: Use Claude Desktop
-1. Make sure `rflectr server` is still running.
-2. Open the **Cowork** or **Code** tab (Chat won't be there).
-3. Open the model picker — you should see your gateway models.
-4. Pick a model and start a session.
-If discovery worked in Step 3, you're done — no extra launch step.
----
-## Gateway values cheat sheet
-| Setting | Local rflectr server |
-|---|---|
-| Provider | Gateway (Anthropic-compatible) |
-| Base URL | `http://127.0.0.1:17645/anthropic` |
-| API key | Any non-empty value (local mode has no server password) |
-| Auth scheme | `bearer` |
-| Discovery (internal) | `GET http://127.0.0.1:17645/anthropic/v1/models` |
-| Messages (internal) | `POST http://127.0.0.1:17645/anthropic/v1/messages` |
-### Network mode (another device on your LAN)
-| Setting | Value |
-|---|---|
-| Base URL | `http://<server-ip>:17645/anthropic` |
-| API key | The **server password** printed when the server started |
----
-## Restore Claude Desktop to Anthropic's servers
-To stop routing through rflectr and return to normal Claude Desktop (Anthropic sign-in, Chat tab, claude.ai inference):
-### Verified revert (macOS, Claude Desktop 1.11847.5)
-Three on-disk changes plus a relaunch:
-| What | Why |
-|---|---|
-| Remove `Claude-3p/configLibrary/` | Drops the gateway config that keeps Desktop in 3P mode. |
-| Set `"allowDevTools": false` | Hides the **Developer** menu — current builds have *Enable* but no *Disable* toggle. |
-| Set `"deploymentMode": "1p"` | Pins first-party mode in the standard `Claude/` data folder. |
-**Before you start:** fully quit Claude Desktop (`Cmd+Q` on macOS — not just the window). Back up the folders below if you want an undo path.
-**Step 1 — Remove the gateway config**
-```bash
-# macOS
-rm -rf ~/Library/Application\ Support/Claude-3p/configLibrary/
-```
-```powershell
-# Windows (PowerShell)
-Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Claude-3p\configLibrary"
-```
-This deletes the applied third-party inference profile. It does **not** delete Cowork session history under `Claude-3p/` or `~/Claude/`.
-**Step 2 — Disable Developer Mode** — edit `developer_settings.json` in the **standard** (1P) data folder:
-- macOS: `~/Library/Application Support/Claude/developer_settings.json`
-- Windows: `%APPDATA%\Claude\developer_settings.json`
-```json
-{ "allowDevTools": false }
-```
-Create the file if it doesn't exist.
-**Step 3 — Pin first-party mode** — add to the standard config file:
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-```json
-{
-  "preferences": { },
-  "deploymentMode": "1p"
-}
-```
-Merge with existing keys — don't delete your `preferences` block.
-**Step 4 — Relaunch**
-```bash
-open -a Claude
-```
-Optional one-shot override if Desktop still picks up stale 3P state:
-```bash
-/Applications/Claude.app/Contents/MacOS/Claude --boot-1p-once
-```
-Stop the rflectr server (`Ctrl+C`) if you no longer need the gateway.
-**How to confirm it worked:** the Chat tab and Anthropic sign-in are back, no **Cowork 3P | Gateway** label appears bottom-left, the **Developer** menu is gone, and logs write to `~/Library/Logs/Claude/main.log` showing `claude.ai account active and logged in`.
-### Option A — In-app (if the Developer menu is still available)
-Open **Developer → Configure third-party inference**, clear or replace the gateway settings, and apply. You may still need [Step 2](#restore-claude-desktop-to-anthropics-servers) afterward — clearing the gateway doesn't hide the Developer menu.
-### Option B — Log out → Anthropic sign-in
-In 3P mode, **Log out** (bottom-left) can surface the sign-in screen with an option to use Anthropic directly. It's easy to miss; the verified revert above is more reliable.
-### Full reset (deletes local Desktop history)
-Only if the above isn't enough:
-| Platform | Delete |
-|---|---|
-| macOS | `~/Library/Application Support/Claude-3p/` and optionally `~/Claude/` |
-| Windows | `%LOCALAPPDATA%\Claude-3p\` and optionally `%USERPROFILE%\Claude\` |
-> ⚠️ Conversation history in that folder is not recoverable after deletion.
-**Managed / enterprise profiles:** if IT pushed a managed profile (Jamf, Intune, Group Policy), local `configLibrary/` edits may be ignored or restored on launch. Talk to IT.
----
-## Disable Developer Mode
-There is **no "Disable Developer Mode" menu item** in Claude Desktop v1.11847.5. To turn it off after reverting:
-1. Fully quit Claude Desktop.
-2. Edit `developer_settings.json` in the **standard** `Claude/` folder (paths above).
-3. Set `"allowDevTools": false`.
-4. Relaunch.
-To re-enable later: set `"allowDevTools": true` and relaunch, or use **Help → Troubleshooting → Enable Developer Mode** again.
----
-## Troubleshooting
-### Gateway config doesn't seem to apply
-- Confirm **Connection** uses **Gateway** with a valid base URL and API key.
-- Config is read at launch — fully quit and reopen Desktop after **Apply locally**.
-- **Help → Troubleshooting → Copy Managed Configuration Report** shows what the app loaded (secrets redacted).
-- Logs: macOS `~/Library/Logs/Claude-3p/main.log`, Windows `%LOCALAPPDATA%\Claude-3p\Logs\main.log`.
-### Test connection / model discovery fails
-| Check | Action |
-|---|---|
-| Server not running | Start `rflectr server` and keep the terminal open. |
-| Wrong base URL | `http://127.0.0.1:17645/anthropic`, no `/v1` suffix. |
-| Empty API key | Any non-empty string for local mode. |
-| Network mode | Base URL uses the server's LAN IP; API key matches the server password. |
-| Firewall | Allow local connections to port `17645`. |
-```bash
-curl -s http://127.0.0.1:17645/health
-curl -s -H "Authorization: Bearer test" http://127.0.0.1:17645/anthropic/v1/models
-```
-### Model picker shows 0 models or fewer than expected
-- **Discovery id masking:** answer **Yes** in the server wizard — Desktop hides models whose gateway ids contain competitor vendor strings.
-- **Provider filter:** re-run the wizard and add the providers you need.
-- **Favorites-only:** add models with `rflectr models`, or turn favorites-only off.
-- **Providers:** `rflectr providers list` — ensure the providers you want are configured.
-### Models show in `curl` but not in Desktop
-Enable **Mask gateway model ids for discovery**, restart the server, relaunch Desktop.
-### `Missing OPENCODE_API_KEY` when starting the server
-Run `rflectr claude` once to store your key, or export `OPENCODE_API_KEY` before `rflectr server`.
-### `No providers configured`
-```bash
-rflectr providers add   # or: rflectr providers import
-```
-### Authentication errors from the gateway (401)
-- **Local mode:** any non-empty bearer token works.
-- **Network mode:** the gateway API key in Desktop must match the server password exactly.
-### Generate a diagnostic report
-**Help → Troubleshooting → Generate Diagnostic Report**, then share the saved folder. No conversation content is included.
----
-## Official references
-| Topic | Link |
-|---|---|
-| Third-party inference overview | [claude.com/docs/cowork/3p/overview](https://claude.com/docs/cowork/3p/overview) |
-| Installation and setup | [claude.com/docs/cowork/3p/installation](https://claude.com/docs/cowork/3p/installation) |
-| Configuration reference | [claude.com/docs/cowork/3p/configuration](https://claude.com/docs/cowork/3p/configuration) |
-| User identity and local data | [claude.com/docs/cowork/3p/data-storage](https://claude.com/docs/cowork/3p/data-storage) |
-| Claude Desktop download | [claude.com/download](https://claude.com/download) |
-| rflectr API server | [API Server guide](api-server.md) |
----
-## Related guides
-- [API Server](api-server.md) · [Providers](providers.md) · [Troubleshooting](../faqs/troubleshooting.md)

package/library/knowledge/public/guides/codex.md DELETED Viewed

@@ -1,296 +0,0 @@
-# Codex
-> Category: Guide | Version: 1.0 | Date: June 2026 | Status: Active
-Use **OpenAI Codex** — the terminal CLI or the desktop app — with any model from your rflectr registry: Anthropic, xAI, Google Gemini, Nvidia, DeepSeek, OpenAI, and more.
-| Command | Launches | Config target |
-|---|---|---|
-| `rflectr codex` | Codex **terminal** (TUI) | A temporary sidecar profile — never touches your main Codex config. |
-| `rflectr codex-app` | Codex **desktop app** (macOS / Windows) | Patches `~/.codex/config.toml` with a backup; restored on `Ctrl+C`. |
-Both use the same registry (`~/.rflectr/providers.json`) and provider picker. The CLI uses OpenAI directly when possible; the desktop app always uses the local Responses proxy so it can keep Codex's built-in provider identity and preserve history visibility.
-> 📖 Full flags: `rflectr codex --help` and `rflectr codex-app --help`.
-> 🤖 Automating it? See [AI Agents & automation](ai-agents.md) or run `rflectr --ai`.
----
-## Prerequisites
-1. **rflectr** on your PATH (`npm install -g @legioncodeinc/rflectr`, or `npm run build && npm link` locally).
-2. **At least one provider:** `rflectr providers add` (or `rflectr providers import`).
-3. **Codex installed:**
-   - CLI: `npm install -g @openai/codex` (for `rflectr codex`)
-   - Desktop: [Codex for macOS or Windows](https://developers.openai.com/codex/cli) (for `rflectr codex-app`)
-Registry providers plus OpenCode Zen/Go cloud backends all route through rflectr's local Responses proxy.
----
-## How it works
-Codex speaks the **OpenAI Responses API** (`POST /v1/responses`). Most registry providers don't, so rflectr bridges the gap with a two-tier routing model:
-```mermaid
-flowchart LR
-    codex["Codex"]
-    codex -->|"Tier 1: OpenAI only"| openai["OpenAI directly"]
-    codex -->|"Tier 2: everyone else"| proxy["rflectr Responses proxy<br/>(127.0.0.1)"]
-    proxy --> sdk["Vercel AI SDK"]
-    sdk --> upstream["Anthropic / xAI / Gemini / DeepSeek / …"]
-```
-| Tier | Providers | What rflectr does |
-|---|---|---|
-| **Tier 1 — Direct** | OpenAI (API key or ChatGPT OAuth) | Points Codex at OpenAI; no local proxy. |
-| **Tier 2 — Proxy** | Anthropic, xAI, Gemini, Nvidia, DeepSeek, most others | Local server translates Responses ↔ upstream SDK. |
-Your real API keys stay in rflectr (keychain / registry). The proxy holds them in memory for the session only.
----
-## Codex CLI (`rflectr codex`)
-### Quick start
-```bash
-rflectr codex
-```
-Pick provider → pick model → the Codex TUI opens. Under the hood rflectr runs `codex --profile rflectr-launch -m <model-id>`.
-### Flags
-| Flag | Purpose |
-|---|---|
-| *(none)* | Interactive launch. |
-| `--restore` | Remove leftover CLI files after a crash. |
-| `--config` | Write profile + catalog to disk, print paths, exit (no launch). |
-| `--help` | Help text. |
-rflectr manages `--profile` and `-m` / `--model`; pass any other Codex flag directly (no `--` needed):
-```bash
-rflectr codex -s workspace-write
-```
-### Files rflectr owns (CLI)
-| File | Purpose |
-|---|---|
-| `~/.codex/rflectr-launch.config.toml` | Temporary profile for this session. |
-| `~/.rflectr/codex/models-<provider>.json` | Model catalog. |
-| `~/.rflectr/codex/session.json` | Session lock (one CLI session at a time). |
-rflectr **never edits** `~/.codex/config.toml` for CLI launches — your personal Codex settings still apply.
-### Cleanup (CLI)
-| Situation | What happens |
-|---|---|
-| Normal exit (including `Ctrl+C` in Codex) | Overlay files removed automatically. |
-| Crash / force-quit | Files may remain; next launch auto-recovers when possible. |
-| Manual | `rflectr codex --restore`. |
-### What rflectr injects (CLI)
-| Variable | When | Why |
-|---|---|---|
-| `RFLECTR_CODEX_KEY=proxy-local` | Tier 2 only | Placeholder so Codex hits the local proxy; the real key stays in the proxy. |
-| `OPENAI_API_KEY` (etc.) | Tier 1 OpenAI | Codex calls OpenAI natively. |
-rflectr **strips CI env vars** (`CI`, `CODEX_CI`, `GITHUB_ACTIONS`, …) before spawning Codex so IDE terminals don't accidentally force read-only CI mode. `RFLECTR_CODEX_KEY` does **not** control sandbox policy.
-### Sandbox and network (CLI)
-Two layers people confuse:
-1. **Codex's sandbox** — shell commands inside Codex (files, network, approvals). Lives in `~/.codex/config.toml` and Codex CLI flags.
-2. **rflectr's proxy** — model API traffic only.
-`rflectr codex` **defaults to `danger-full-access`** (set in both the launch profile and the spawn args) so shell tools (`curl`, `nlm`, npm, MCP CLIs) reach the network without passing `-s` each time. Override per session:
-```bash
-rflectr codex -s workspace-write
-```
-To change the sandbox for bare `codex` (without rflectr), edit `~/.codex/config.toml` yourself:
-```toml
-sandbox = "danger-full-access"
-ask_for_approval = "never"
-[shell_environment_policy]
-inherit = "all"
-```
-On macOS, profile TOML alone may not be enough; rflectr also passes `-s danger-full-access` on spawn ([Codex #10390](https://github.com/openai/codex/issues/10390)).
----
-## Codex desktop app (`rflectr codex-app`)
-### Quick start
-```bash
-rflectr codex-app
-```
-Pick provider → pick model → the Codex **app** opens. **Keep the rflectr terminal open** until you're done — the app always uses the foreground proxy. Press **`Ctrl+C`** to stop the proxy and restore your previous Codex config.
-**Platforms:** macOS and Windows (no Codex desktop app on Linux).
-### Flags
-| Flag | Purpose |
-|---|---|
-| *(none)* | Interactive launch + open app. |
-| `--restore` | Restore `config.toml` and remove rflectr app files. |
-| `--config` | **Preview only** — print the TOML that would be written; no disk writes, no app, no proxy. |
-| `--help` | Help text. |
-`--config` skips the picker and uses your last Codex provider/model (or the first compatible provider). The shown port `54321` is a placeholder; a real launch uses a random port.
-### Files rflectr owns (App)
-| File | Purpose |
-|---|---|
-| `~/.codex/config.toml` | **Patched while active** — restored on `Ctrl+C` or `--restore`. |
-| `~/.rflectr/codex/app-models-<provider>.json` | Model catalog. |
-| `~/.rflectr/codex/session-app.json` | App session lock. |
-| `~/.rflectr/codex/app-restore-state.json` | Snapshot of your pre-session root keys (for surgical restore). |
-| `~/.rflectr/codex/backups/config.toml.*.bak` | Rotating backups before each patch. |
-CLI and App files are separate — running one after the other won't break the other.
-### What gets written to `config.toml`
-```toml
-model = "claude-sonnet-4-6"
-model_provider = "openai"
-openai_base_url = "http://127.0.0.1:<random-port>/v1"
-model_catalog_json = "/Users/you/.rflectr/codex/app-models-anthropic.json"
-model_context_window = 1000000
-model_auto_compact_token_limit = 700000
-```
-The app deliberately keeps `model_provider = "openai"` and redirects the built-in provider with `openai_base_url`. Codex records the provider on every local thread and filters history by provider; a separate custom provider would hide your existing OpenAI/ChatGPT threads while a rflectr session is active. No conversations are deleted. (See [Context management](#context-management) for the two context fields.)
-### Cleanup (App)
-| Situation | What to do |
-|---|---|
-| Normal end of session | `Ctrl+C` in the rflectr terminal → config restored, proxy stopped. |
-| Codex already running | rflectr offers to **restart Codex** so new settings apply; decline and reopen manually if you prefer. |
-| Crash / killed terminal | Next launch auto-recovers, or `rflectr codex-app --restore`. |
-| Live session still running | `--restore` refuses until you `Ctrl+C` the other terminal. |
-### App vs CLI — config safety
-| | CLI | App |
-|---|---|---|
-| Touches `~/.codex/config.toml`? | **Never** | Yes, with backup + restore |
-| Proxy lifetime | Until Codex CLI exits | Until **`Ctrl+C`** in the rflectr terminal |
-| Picker every launch? | Yes (prefs pre-highlight last choice) | Yes |
----
-## Favorites catalog mode
-When you've saved favorites via `rflectr models`, both commands show your starting model + favorites in the mid-session picker. Zen/Go favorites are included when an OpenCode API key is available.
-- **Slugs** — CLI uses `${providerId}__${modelId}` so models from different providers never collide. The App uses bare ids for single-provider catalogs and the same collision-safe slug for favorites.
-- **Auth** — CLI favorites give the Codex child `OPENAI_API_KEY=proxy-local`; the app keeps its normal OpenAI login while `openai_base_url` points at the proxy. Either way the proxy holds the real credentials.
-- **Warm-up** — with ~20 favorites across many providers, the first request may be slow as the proxy initializes one `LanguageModel` per favorite. Subsequent requests are fast.
----
-## Reasoning effort
-Codex shows a **reasoning-effort** picker when rflectr's catalog includes supported levels. rflectr fills `supported_reasoning_levels`, `default_reasoning_level`, and `supports_reasoning_summaries` from its reasoning resolver — provider metadata first, provider-specific rules second. You control effort in **Codex's native UI**; rflectr adds no menu of its own. For `codex-app`, an existing `model_reasoning_effort` in your config is **preserved**.
-| Provider npm | Example models | Picker levels | Wire mapping |
-|---|---|---|---|
-| `@ai-sdk/anthropic` | claude-sonnet-4-6, claude-opus-4-6 | low, medium, high | SDK `thinking: adaptive` + `effort` |
-| `@ai-sdk/openai` | gpt-5.5, gpt-5.4-codex | low, medium, high, xhigh | `reasoningEffort` on Responses API |
-| `@ai-sdk/google` | gemini-2.5-pro, gemini-3-flash | low, medium, high | Gemini 2.5 → token budget; Gemini 3 → `thinkingLevel` |
-| `@ai-sdk/mistral` | mistral-large, magistral-* | **high, off only** | `reasoningEffort: high \| none` |
-| `@ai-sdk/xai` | grok-* | none, low, medium, high | `reasoningEffort` |
-| `@openrouter/ai-sdk-provider` | z-ai/glm-5.2, models with `reasoning` support | none, minimal, low, medium, high, xhigh | `providerOptions.openrouter.reasoning.effort` |
-| `@ai-sdk/openai-compatible` | unknown backends | *(picker hidden)* | no effort sent |
-Unrecognized local models (e.g. Ollama `llama3:8b`) get an empty picker — best-effort, no guarantee.
----
-## Provider routing
-| Provider | CLI route | App route | Notes |
-|---|---|---|---|
-| **OpenAI** | Tier 1 direct | Local proxy | `rflectr providers auth openai` for ChatGPT OAuth. |
-| **Anthropic, xAI, Gemini, Nvidia, DeepSeek, …** | Tier 2 proxy | Local proxy | SDK translation path. |
-| **OpenCode Zen / Go** | Tier 2 proxy | Local proxy | Requires an OpenCode API key. |
----
-## OAuth
-Tokens (e.g. xAI, OpenAI OAuth) refresh **at launch only**. Long sessions may return 401 when a token expires — restart `rflectr codex` or `rflectr codex-app`.
----
-## Context management
-**Codex App is a stateless client:** it sends the full accumulated conversation history with every request (the Responses API `previous_response_id` field is not implemented in the app binary). Each turn therefore grows larger, and a long GPT-5.5 session (which OpenAI manages server-side) can't be transparently resumed on a different model — the full local history is sent inline, and a 1 M-token model rejects a 2 M-token payload.
-rflectr protects against overflow in two layers:
-1. **Early auto-compaction via `config.toml`.** rflectr writes `model_context_window` and `model_auto_compact_token_limit` (70% of the limit). Codex compacts before hitting the threshold, leaving headroom for the compaction request itself.
-2. **Proxy-level truncation as a last resort.** If an over-threshold conversation reaches the proxy (e.g. after switching off a GPT-5.5 session), rflectr drops the oldest messages to bring the estimate under ~85% of the window — degraded but functional rather than crashing.
-**"Custom" label:** Codex App labels any catalog-loaded model as **"Custom"** (e.g. "Custom · Medium"). That's expected — the model rflectr selected is in use; the label is cosmetic.
-**Background requests:** Codex App's internal agent periodically sends background requests with hardcoded OpenAI model ids (`gpt-5.4`, `gpt-5.4-mini`, `gpt-5.5`). rflectr's proxy silently routes these to the session's starting model. Harmless — it handles UI state, not your conversation.
----
-## Troubleshooting
-### CLI (`rflectr codex`)
-| Symptom | Fix |
-|---|---|
-| Provider missing in picker | `rflectr providers add` |
-| Leftover files after crash | Next launch auto-cleans, or `rflectr codex --restore` |
-| "Another session running" | Wait, or `--restore` |
-| Shell tools have no network | Confirm `rflectr codex --config` shows `sandbox = "danger-full-access"`, or pass `-s danger-full-access` |
-| Read-only / CI behavior | rflectr strips CI vars; try Terminal.app outside your IDE |
-| `codex` not found | `npm install -g @openai/codex` |
-### App (`rflectr codex-app`)
-| Symptom | Fix |
-|---|---|
-| Conversations disappear during a session | Update rflectr — older releases used a custom `model_provider`; current releases keep `openai` and preserve history. |
-| App didn't open | Open Codex once manually, then re-run `rflectr codex-app` |
-| Model errors / disconnected | Keep the rflectr terminal open (the proxy must run) |
-| Stuck on rflectr settings | `rflectr codex-app --restore` |
-| `--restore` blocked | `Ctrl+C` the other `codex-app` terminal first |
-| Wrong config after a test | `--restore`; backups live in `~/.rflectr/codex/backups/` |
-| "prompt too long" after many turns | History outgrew the context limit — start a fresh conversation. See [Context management](#context-management). |
-| Model shows as "Custom" | Expected — the correct model is in use. |
-### Shared
-| Symptom | Fix |
-|---|---|
-| Anthropic key rejected on `providers add` | Update rflectr (Bearer vs `x-api-key` fix). |
-| "rflectr forced sandbox" | It didn't — check Codex sandbox flags, not `RFLECTR_CODEX_KEY`. |
----
-## Related guides
-- [AI Agents & automation](ai-agents.md) · [Providers](providers.md) · [Troubleshooting](../faqs/troubleshooting.md)
-- [Codex advanced config](https://developers.openai.com/codex/config-advanced) · [Codex approvals & security](https://developers.openai.com/codex/agent-approvals-security)