codex-local-diagnostics

name	codex-local-diagnostics
description	Diagnose and safely repair this Mac's local Codex/CC Switch/OpenAI CLI setup, including provider-history/sidebar issues, auth expiry, MCP/plugin failures, /goal approval behavior, and local proxy connectivity for Codex.

Codex Local Diagnostics

Use this skill when the user asks about local Codex Desktop/CLI behavior, missing or duplicated chat history, provider migration, CC Switch session expiry, OpenAI plugin install state, MCP startup warnings, /goal approval behavior, or Codex network failures through Clash/v2rayN.

Source Order

Inspect real local state before explaining:

1. ~/.codex/config.toml
2. ~/.codex/state_5.sqlite
3. ~/.codex/sessions/**/*.jsonl
4. ~/.codex/session_index.jsonl
5. ~/.codex/logs_2.sqlite
6. ~/.codex/auth.json and, for CC Switch, ~/.cc-switch/cc-switch.db
7. Live listeners and network checks when the symptom is connectivity.
8. Official OpenAI/Codex docs, changelog, releases, or issues for product behavior that may have changed.

Do not edit auth files, provider databases, session metadata, or config until the exact failing layer is identified and the user has approved risky writes.

Triage Map

History or Provider Mismatch

When chats disappear, counts do not match the UI, or provider names such as aigocode, aigocode_codex, or openai are involved:

• Query threads grouped by model_provider, source, thread_source, and archived.
• Scan rollout first lines for session_meta.payload.model_provider.
• Check whether session_index.jsonl is stale or much smaller than the database.
• Explain raw DB counts separately from UI-visible counts; raw totals may include subagents, archived rows, and non-user rows.
• If migrating providers, the durable repair spans all three layers: rollout JSONL metadata, SQLite threads.model_provider, then rebuilt session_index.jsonl.
• Verify with pragma integrity_check, a rollout metadata count scan, and a fresh DB grouping.

CC Switch or Auth Expiry

When CC Switch says a session expired:

• Compare ~/.codex/auth.json with provider rows in ~/.cc-switch/cc-switch.db.
• Separate provider health, token freshness, and UI lag.
• Prefer codex login --device-auth when refresh fails with refresh_token_invalidated.
• Back up ~/.cc-switch/cc-switch.db before any provider-row sync.
• Do not expose or paste tokens.

MCP, Plugin, or Tool Startup Failures

For MCP warnings or plugin UI spinners:

• Read ~/.codex/config.toml first.
• Use native verifier commands where available, such as codex mcp get <name>.
• Inspect ~/.codex/logs_2.sqlite for the actual startup error.
• Distinguish slow startup from network, npm registry, proxy, or certificate failures.
• A visual plugin spinner is not the source of truth; verify the backend namespace or tool availability when possible.

/goal Approval or Runtime Behavior

For /goal auto-review or approval surprises:

• Check the current thread/runtime state, not just static config.
• Treat resume, compaction, and quota exhaustion as possible causes of downgraded or stale approval context.
• Prefer a fresh goal/thread when repeated retries in an old context keep producing the same approval problem.
• Use official Codex sources for current product behavior.

Codex Network and Proxy Failures

For Connection refused, terminal cannot reach Codex, or browser works but CLI/Codex does not:

• List listeners with lsof -nP -iTCP -sTCP:LISTEN.
• Identify the actual local proxy ports; do not assume v2rayN uses 10808/10809.
• Test the Codex backend through each candidate proxy:
  • direct: curl -I --connect-timeout 8 https://chatgpt.com/backend-api/codex/responses
  • HTTP proxy: curl -I --connect-timeout 8 -x http://127.0.0.1:<port> https://chatgpt.com/backend-api/codex/responses
  • SOCKS proxy: curl -I --connect-timeout 8 -x socks5h://127.0.0.1:<port> https://chatgpt.com/backend-api/codex/responses
• HTTP/2 405 with Allow: POST proves network reachability for that URL; it is not a failure for a HEAD check.
• If v2rayN is on macOS, inspect ~/Library/Application Support/v2rayN/guiConfigs/guiNConfig.json for local inbound settings, but avoid printing node credentials.
• Separate local inbound failure from upstream node routing.

Safe Repair Rules

• Back up before changing state_5.sqlite, rollout JSONL metadata, session_index.jsonl, CC Switch DB, or global config.
• Prefer narrow, reversible changes.
• Re-run the smallest verifier after each repair.
• Tell the user exactly which layer was fixed and which layer remains unverified.