how to contribute debugging

Debugging

Where DroidProxy writes logs, the common failure modes, and the tools for inspecting a running instance.

Where logs go

NSLog (Console.app)

All lifecycle and runtime logging uses NSLog (not print/os_log). View it in Console.app, or stream it from the terminal:

log stream --predicate 'process == "CLIProxyMenuBar"' --info

Filter by the bracketed prefixes the code uses:

• [ThinkingProxy] — proxy request handling, rewrites, routing.
• [ServerManager] — backend process lifecycle, config merge, login flows.
• [AuthStatus] — account parsing and auth state.
• [SettingsView] — settings UI actions.

Per-request file log: /tmp/droidproxy-debug.log

ThinkingProxy writes a compact per-request line to /tmp/droidproxy-debug.log so you can see what Droid actually sent and what the proxy did, without dumping whole prompts:

tail -f /tmp/droidproxy-debug.log

Line types to look for:

• REQUEST REASONING: — the parsed reasoning / reasoning_effort / thinking / output_config / service_tier / generationConfig for the request, e.g. REQUEST REASONING: model=gpt-5.5 reasoning={"effort":"xhigh","summary":"auto"}. Confirms the effort Droid is sending.
• REWRITE MODEL / REWRITE PATH — model-alias and Gemini /v1/responses → /v1/chat/completions rewrites.
• INJECTED service_tier — fast-mode (service_tier=priority) injection for enabled Codex/GPT models.
• SANITIZED CLAUDE THINKING BLOCKS — when ClaudeThinkingBlockSanitizer removed stale thinking blocks.

See Thinking proxy for the meaning of each rewrite.

Verbose backend logs: ~/.cli-proxy-api/logs/

The bundled CLIProxyAPI backend writes its own logs to ~/.cli-proxy-api/logs/. These are enabled by the Verbose logging toggle in the Settings window; the change is hot-reloaded into the running backend (no restart needed). Use these to inspect what the backend sent upstream and the upstream response. See Server manager.

Common issues

Orphaned cli-proxy-api processes

If the menu-bar app crashes or is force-quit, the bundled backend can be left running and hold port 8318. ServerManager.killOrphanedProcesses clears these on startup via pgrep/pkill. To clear them by hand:

pgrep -fl cli-proxy-api
pkill -x cli-proxy-api

dev-relaunch.sh already does this kill step before relaunching.

Port 8317 or 8318 already in use

ThinkingProxy binds :8317 and the backend binds 127.0.0.1:8318. If either is taken (an orphaned process, or another app), startup fails. Find the holder:

lsof -nP -iTCP:8317 -sTCP:LISTEN
lsof -nP -iTCP:8318 -sTCP:LISTEN

Bind-address fallback

If a configured custom bind address fails to bind, the backend can fall back to listening on all interfaces. Check the [ServerManager] logs and the generated ~/.cli-proxy-api/merged-config.yaml host: value. Local backend traffic is intended to stay on 127.0.0.1:8318.

Auth not detected

Accounts live as JSON files in ~/.cli-proxy-api/. If a login isn't picked up:

• Check the file exists and has a recognized type field: ls ~/.cli-proxy-api/*.json and inspect type (claude, codex, gemini, kimi).
• AuthDirectoryMonitor is a debounced watcher — a change can take a moment to register. Adding, changing, or removing a JSON file fires the onChange callback after the debounce window.

See Auth.

Factory not showing the models

After clicking Apply in the Settings window to write the Factory custom-model config, restart Factory / Droid so it re-reads the model catalog. If models still don't appear, re-run Apply and restart again.

Backend management dashboard

The backend exposes a management dashboard at:

http://127.0.0.1:8318/management.html

It requires remote management to be configured (the remote-access settings in the Settings window inject allow-remote / secret-key into the merged config). See Server manager.

Quick triage flow

flowchart TD
    A[Something's wrong] --> B{App running?}
    B -- No --> C[Check Console.app for CLIProxyMenuBar crash]
    B -- Yes --> D{Requests failing?}
    D -- Yes --> E[tail -f /tmp/droidproxy-debug.log]
    E --> F{Wrong rewrite / tier / model?}
    F -- Yes --> G[Inspect [ThinkingProxy] NSLog]
    F -- No --> H[Enable Verbose logging, read ~/.cli-proxy-api/logs/]
    D -- No --> I{Models missing in Factory?}
    I -- Yes --> J[Re-run Apply, restart Factory]
    I -- No --> K[Check ports 8317/8318 + orphaned cli-proxy-api]

Loading