AGENTS.md

Build & Run

The Swift package lives in src/. Run all swift build, swift run, and swift package commands from there, not from the repo root.

# Preferred dev loop: kill any running DroidProxy, rebuild the .app bundle, and
# launch the freshly signed build. Use this instead of running create-app-bundle.sh
# + open by hand — it guarantees the old menu-bar process and bundled
# cli-proxy-api are stopped before the new app starts.
./dev-relaunch.sh

# Debug build (no .app bundle, no relaunch)
cd src && swift build

# Run the app manually (menu bar app — swift run does not work for LSUIElement apps)
# Build the .app bundle first, then open it:
./create-app-bundle.sh && open DroidProxy.app

# Release .app bundle at repo root
# Picks up CODESIGN_IDENTITY / APP_VERSION / TARGET_ARCH from env when present
./create-app-bundle.sh

dev-relaunch.sh is the preferred way to run DroidProxy during development. It calls create-app-bundle.sh (which runs swift build -c release and assembles the signed .app) after killing any running CLIProxyMenuBar / cli-proxy-api processes, then launches the fresh bundle. Do not use it for releases — those go through .github/workflows/release.yml.

create-app-bundle.sh currently builds DroidProxy.app at the repo root and bundles resources from src/Sources/Resources/.

Notarization (local)

ditto -c -k --sequesterRsrc --keepParent "DroidProxy.app" "DroidProxy-notarize.zip"
xcrun notarytool submit "DroidProxy-notarize.zip" --keychain-profile "notarytool" --wait
xcrun stapler staple "DroidProxy.app"

Sparkle update signing

src/.build/artifacts/sparkle/Sparkle/bin/sign_update DroidProxy-arm64.zip

Source Of Truth

The compiled app code is under src/. Treat src/Sources/**, src/Info.plist, and create-app-bundle.sh as source of truth. There is no longer a mirrored top-level resources/ tree — older AGENTS notes about it are stale.

Architecture

DroidProxy is a macOS menu bar app (LSUIElement) with:

1. ThinkingProxy on localhost:8317, the user-facing TCP proxy.
2. Bundled CLIProxyAPI on 127.0.0.1:8318, managed as a child process by ServerManager.
3. A separate localhost-only Copilot API gateway on 127.0.0.1:8319, managed by CopilotGatewayManager.

Typical request flow:

Client -> :8317 ThinkingProxy -> :8318 CLIProxyAPI -> upstream provider

Selected GitHub Copilot models instead use:

Client -> :8319 Copilot API gateway -> GitHub Copilot

Meta Muse models (muse-wonder-1.0, muse-wonder-1.0-contributor, muse-wonder-full-1.0, muse-wonder-full-1.0-contributor) split by API:

• Responses (/v1/responses, /responses/compact): ThinkingProxy TLS-forwards to https://api.meta.ai/v1 with the minted Model API key. CLIProxyAPI's generic openai-compatibility executor otherwise rewrites Responses into /chat/completions, which drops reasoning.encrypted_content and breaks long Muse/Foundry runs.
• Chat Completions: still :8317 -> :8318 -> api.meta.ai via the openai-compatibility block ServerManager writes into merged-config.yaml, so multi-account failover keeps working for Completions clients.

Current ThinkingProxy behavior

Reasoning effort is owned by Droid CLI, not the proxy. Each Factory custom model is registered with native reasoning metadata (enableThinking, supportedReasoningEfforts, defaultReasoningEffort, reasoningEffort) so Droid's per-session selector exposes every level the model supports, and Droid sends the chosen value in the request body. The proxy does not inject thinking, reasoning, reasoning_effort, output_config, budget_tokens, or generationConfig.thinkingConfig for any model — it forwards the request unchanged.

What it still does today:

• Anthropic-Beta rewriting: When a Claude request has thinking.type of enabled/adaptive/auto, the proxy strips redact-thinking-2026-02-12 from the Anthropic-Beta header and appends the visible-thinking beta list (interleaved-thinking, prompt-caching-scope, etc.). It never injects fast-mode-* and always strips it if Factory/Droid sent it — CLIProxyAPI treats any Fast-marked 429 as request-scoped, which blocks OAuth seat failover. Claude has no Fast mode. Without the redact-thinking strip, Claude emits only signed empty thinking blocks.
• Service tier (fast mode) for Responses API paths (/v1/responses, /api/v1/responses): injects "service_tier":"priority" for gpt-6-astra, gpt-6.1-sol, gpt-6.1-terra, or gpt-6-luna when AppPreferences.gpt6AstraFastMode / gpt61SolFastMode / gpt61TerraFastMode / gpt6LunaFastMode is enabled and the client did not already set service_tier. Fast mode is API priority and is independent of reasoning effort.
• Grok routing: every Grok chat/Responses model goes to cli-chat-proxy.grok.com (Grok Build billing). Never send them to api.x.ai: the same OAuth bearer there is billed as X API usage (productUsage Api instead of GrokBuild in /v1/billing?format=credits). Only grok-imagine-* image requests still use api.x.ai. grok-4.7-build-fast is a separate SuperGrok catalog model (same OAuth bearer as grok-4.7) that the public API does not serve. ThinkingProxy sends both with X-XAI-Token-Auth: xai-grok-cli, x-grok-model-override: <requested model id> (grok-4.7 or grok-4.7-build-fast), x-grok-client-version, and x-grok-client-identifier: grok-shell. The proxy rejects a missing client version. The JSON model field stays grok-4.7-build-fast. Reasoning effort stays whatever Droid put in the body.
• Grok native tool-call rewrite: Grok often leaks Factory markup (<|tool_calls_begin|> / <|tool_call_begin|>) into message.content, or a fenced {"name","arguments"} JSON object. Factory's first-party Grok adapter parses the markup; the custom OpenAI route does not, so the worker turn ends as plain text. The proxy buffers Grok responses and lifts markup or JSON into OpenAI tool_calls before the client sees it.
• Grok EndFeatureRun repair: Grok often calls EndFeatureRun without handoff, or with validatorsPassed as a thought-string. Factory rejects those and the worker loops. The proxy inserts a stub handoff and coerces validatorsPassed before the client sees the call.
• Grok Execute repair: Grok often calls Execute with only summary (or cmd/input/shell) and Factory rejects it (command is required). The proxy remaps aliases, lifts a command embedded in summary or a same-turn fenced code block, and promotes a summary that is already a shell string. It does not invent a command from English. On the request path, GrokRequestSanitizer also pins command as a required Execute/Bash/Shell parameter so xAI sees the field.
• Gemini path rewrite: /v1/responses (and /api/v1/responses) are rewritten to /v1/chat/completions for OAuth Code Assist Gemini models (the -preview-suffixed names) since CLIProxyAPI does not support those via the Responses API endpoint.
• Meta Muse Responses TLS-forward: muse-wonder-1.0 / muse-wonder-1.0-contributor / muse-wonder-full-1.0 / muse-wonder-full-1.0-contributor POSTs to /v1/responses (and /responses/compact) skip CLIProxyAPI and go to api.meta.ai with the minted Model API key, preserving encrypted reasoning. Chat Completions for those models still use the openai-compatibility block. All four variants accept reasoning efforts minimal through max (live-verified; none/ultra return 400 and are not advertised).
• Meta usage sniffing: Meta has no usage endpoint, so the proxy inspects (never modifies) relayed Meta Responses bytes for response.subscription_usage SSE events (window 5h + weekly percents with resets_at) and records them per serving account into MetaMuseUsageStore, which backs the Meta cards in OAuth Quota Usage with muse /usage-style "as of" semantics.
• Usage endpoint: GET /droidproxy/usage[?provider=codex|claude|grok|meta&account=<id|email>] on :8317 is answered locally by UsageEndpoint (never forwarded) with live quota windows as JSON (remaining_percent, resets_at, resets_in_seconds per window). Clicking a gauge in OAuth Quota Usage copies a curl for that account so an agent can poll its own quota and stop before it runs out (Droid gives up retrying failed requests after ~30s). No auth or loopback restriction, by design.
• Control API: /droidproxy/control/ on :8317 is answered locally by ControlAPI (never forwarded). See "Control API" below.
• Per-request reasoning log to /tmp/droidproxy-debug.log: each POST emits a REQUEST REASONING: line that extracts just reasoning / reasoning_effort / thinking / output_config / service_tier / generationConfig from the parsed body so the actual values Droid is sending are visible without dumping the whole prompt. Example: REQUEST REASONING: model=gpt-6.1-sol reasoning={"effort":"high","summary":"auto"}.
• Preserves JSON key order by editing the raw JSON string instead of re-serializing (critical for Anthropic's prompt cache). The remaining helpers (injectJSONField, findTopLevelFieldLocation, etc.) exist for processOpenAIFastMode.

What it no longer does (removed in the Droid-CLI-thinking refactor):

• No Claude adaptive thinking injection (Opus 4.8 / Sonnet 5 — thinking + output_config)
• No classic thinking.budget_tokens injection
• No Codex reasoning.effort injection
• No Gemini generationConfig.thinkingConfig injection
• No Kimi reasoning_effort injection
• No claude-opus-4-8(high) / gpt-5.2(xhigh) etc. “advanced variant” suffix parsing — every level now ships in the single base entry via Droid CLI metadata
• No Max Budget Mode override
• No Amp CLI routing (the /auth/cli-login redirect, /provider/* rewrite, ampcode.com management forwarding, and Amp response normalization were removed when switching to mainline CLIProxyAPI)

Control API

Version 1 of the API Droid Office uses to drive DroidProxy (its contract is docs/subscriptions.md in nikships/droid-office). ThinkingProxy serves it on its own port under /droidproxy/control/; parsing, authorization, routing and JSON live in ControlAPI (pure, unit tested), the work in ProviderController.

• Discovery. At launch DroidProxy writes ~/.droidproxy/control.json (folder 0700, file 0600, temp file and rename): { "api": 1, "port": 8317, "token": "<64 hex>", "version", "pid" }. The token is 32 bytes from SecRandomCopyBytes, new at every launch, and is never logged. The file is removed at quit.
• Every request needs Authorization: Bearer <token> (compared in constant time; else 401) and is refused with 403 from a non-loopback peer, with any Origin header, or with a Host other than 127.0.0.1:<port> or localhost:<port>. A POST without Content-Type: application/json is 415; a body over 64 KiB is 413 (refused from its Content-Length before it is read). Errors are { "error": "<words for the owner>" }.

• Availability (AvailabilityJudge): disabled when the provider is off; signed-out with no account that isn't expired or disabled (Grok: the active credential only). An account is expired only when its file's expired time (the access token's) has passed and it has no refresh_token: CLIProxyAPI renews a refreshable token on the next request (AuthAccount.isExpired vs isAccessExpired); ok when any such account has every covering window above 0% or no usage to go by, unknown when none of them has usage (and always for Antigravity, Kimi, Junie and Copilot, which have no usage reader); else exhausted with the window and until of the account that comes back first (an account is back when the last of its exhausted windows resets). A window covers every model of its provider except Claude's family windows (Weekly (Opus) only Opus, Weekly (Sonnet) only Sonnet) and Claude's other-product windows (Weekly (OAuth Apps), (Cowork), (Omelette)), which cover none.
• Usage source (ControlUsage): route every Codex, Claude and Grok quota fetch through OAuthUsageTracker.fetchUsage and its shared OAuthUsageCache. The cache keys by provider and credential-file path, not endpoint filter or bearer token, and coalesces in-flight reads across /models, /usage and Settings. Claude waits at least five minutes plus 0–30 s jitter after each attempt; 429 fallback waits grow 5/10/20/40/60 minutes, never shorter than Retry-After. Other providers retain a 15 s interval. Failed reads preserve the last successful windows and sample time while carrying the error. Samples, request reservations and cooldowns survive restart in ~/.droidproxy/usage-cache.json (0600, no tokens). Do not bypass the cache on manual refresh or token rotation. Meta comes from its stored snapshot without a probe in /models, so polling models never spends Meta quota.
• Launched by Droid Office. open -g -a DroidProxy.app --args --launched-by droid-office runs normally but shows nothing of its own: no notification prompt or "Server Started" banner, and Sparkle starts only when the owner opens Settings or Check for Updates (LaunchContext).

Auth And Providers

The current app/UI exposes these provider types:

• claude
• codex
• gemini
• kimi
• copilot (device-code OAuth; credentials stay in ~/.droidproxy/copilot-api/; the separate local Copilot API gateway serves only the user-selected models)
• meta (Meta Muse subscription; device-code OAuth against auth.meta.com reproduces the muse CLI's own login flow, then mints a Model API key from api.meta.ai/muse-code/key. Completions keys are written into a generic openai-compatibility block in merged-config.yaml; Responses are TLS-forwarded by ThinkingProxy. This contract is reverse-engineered from the muse binary and a third-party client, not official docs.)

Auth data for AuthManager-managed providers lives in ~/.cli-proxy-api/ as JSON files. Copilot is the exception: its gateway owns ~/.droidproxy/copilot-api/github_token, which DroidProxy never reads. Meta Muse is a second exception: its per-account identity tokens and minted Model API keys live in ~/.droidproxy/meta/accounts.json (mode 0600, parent directory 0700; legacy credentials.json is migrated automatically), never in ~/.cli-proxy-api/.

• type
• email
• login
• expired
• disabled

Behavior to know:

• Multiple accounts per provider are supported
• Per-account disable/enable is supported via the disabled field in each auth JSON
• The last enabled account for a provider cannot be disabled
• Provider-level toggles in SettingsView are separate from per-account disable flags
• Provider-level disable writes oauth-excluded-models into ~/.cli-proxy-api/merged-config.yaml
• CLIProxyAPI hot-reloads config changes, so provider enable/disable does not require a restart
• The app watches ~/.cli-proxy-api/ for changes from both AppDelegate and SettingsView

Key Files

Conventions

• Use NSLog, not print or os_log
• Source-of-truth edits land under src/ (especially src/Sources/**, src/Sources/Resources/, src/Info.plist) and create-app-bundle.sh at the repo root; there is no longer a parallel top-level resources/ mirror
• Treat DroidProxy.app, CLIProxyMenuBar, and com.droidproxy.app as the active app identity
• CLIProxyAPI is bundled as src/Sources/Resources/cli-proxy-api
• ThinkingProxy uses surgical string insertion for JSON edits to preserve cache-sensitive key ordering (do not switch to JSONSerialization.data round-trips)
• Local backend traffic is intended to stay on localhost only (127.0.0.1:8318)

Release Notes For Agents

Release automation lives in .github/workflows/release.yml (no Makefile or scripts/create-release.sh in this repo). The app ships as a single arm64 build; there is no x86_64 appcast or Intel release path.

If a task touches release tooling, audit the current workflow and create-app-bundle.sh.

Models that wait on a CLIProxyAPI release

CLIProxyAPI resolves providers from its model registry only, so a catalog PR for a model the bundled binary does not list yet fails with unknown provider for model <id>. To ship such a PR together with the bump that fixes it:

1. Add the awaiting-cliproxyapi label to the PR.
2. Put one Requires-CLIProxyAPI-Model: <model-id> line per model in the PR body.

When update-cliproxyapi.yml opens the next bump-cliproxyapi-* PR, .github/workflows/merge-gated-prs.yml checks whether the bumped binary's embedded registry lists every declared id. If so it merges the gated branch into the bump branch, waits for the Swift Build check, squash-merges the combined PR (one release), and closes the gated PR. PRs whose models are still missing are left alone. Re-run it manually with the workflow's workflow_dispatch (bump_pr, optional dry_run).