| 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:
~/.codex/config.toml~/.codex/state_5.sqlite~/.codex/sessions/**/*.jsonl~/.codex/session_index.jsonl~/.codex/logs_2.sqlite~/.codex/auth.json and, for CC Switch, ~/.cc-switch/cc-switch.db- Live listeners and network checks when the symptom is connectivity.
- 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.
