Agent Troubleshooter (Claude Code & Codex)

A step-by-step decision tree for when Claude Code or Codex won't log in, connect or behave

$19.90

Agent Troubleshooter helps your agent diagnose the problems that stop Claude Code or the OpenAI Codex CLI from working: the binary is not found, login loops on a remote machine, an API key silently overrides your subscription, a corporate proxy breaks TLS, an MCP server shows as failed, a skill you installed never appears, or every command hits a permission prompt or sandbox denial.

How it works

The agent first collects the facts that matter (tool, version, OS, install method, exact error, what changed), then follows a decision tree that maps the error text to one layer: install and PATH, authentication, network and proxy, limits and capacity, MCP servers, skills, permissions and sandbox, or config precedence. Each branch is a short sequence of checks using the tools' own diagnostics, with one change at a time and a verification step. It never asks you to paste secrets: it checks whether a key is set, not what it is.

What you get

  • SKILL.md with the decision tree and eight diagnostic branches
  • A Claude Code reference: commands, settings files, MCP scopes, permission rules, environment variables
  • A Codex reference: login options for headless machines, config.toml, approval and sandbox settings, MCP tables, log locations
  • A worked example that fixes a failing MCP server and a skill that would not load

Both CLIs change quickly. The skill tells the agent to check --version and the current docs whenever a detail differs. Not affiliated with Anthropic or OpenAI.

Highlights

  • Decision tree from exact error text to the layer that is broken
  • Login loops, API key vs subscription, proxies and corporate TLS
  • Rate limits vs usage limits vs overloaded errors, told apart
  • MCP servers that fail, skills that never load, sandbox denials
  • Config, log and skill paths for both tools, with version caveats

Example

Login loop over SSH
You

codex login opens a URL but the page says it can't connect to localhost. I'm on a remote dev box over SSH.

Agent + skill
Cause: browser sign-in finishes by redirecting to a local callback server that Codex starts on the remote machine (port 1455 in recent versions). Your laptop's browser cannot reach the remote's localhost.

Options (check `codex login --help` for what your version supports):
1. Device-code sign-in, if listed in --help (`codex login --device-auth`).
2. Port forwarding: on your laptop run `ssh -L 1455:localhost:1455 you@devbox`, then in that session run `codex login` and open the printed URL in your local browser.
3. API key instead: `printenv OPENAI_API_KEY | codex login --with-api-key` (bills the API account, not your ChatGPT plan).

Verify with `codex login status`.
Unexpected API bill
You

I have Claude Max but Claude Code is charging my API account. Why?

Agent + skill
Most likely an ANTHROPIC_API_KEY is set in your environment, and Claude Code uses it instead of your subscription login.

Check without printing it: `env | grep -i anthropic | sed 's/=.*/=<set>/'`. Then run `/status` in a session; it shows the active auth method.

Fix: remove the export from your shell profile (~/.zshrc or ~/.bashrc) or the IDE's environment settings, open a new terminal, run `/login` and choose your subscription account. Re-check `/status`. Keep the key for scripts that need it by setting it only in those scripts' environment.
Skill not showing up
You

I unzipped a skill into ~/.claude/skills but Claude Code doesn't see it.

Agent + skill
Checking the three usual causes:

1. Nesting: `ls ~/.claude/skills/*/SKILL.md` shows nothing, but `ls ~/.claude/skills/*/*/SKILL.md` finds ~/.claude/skills/seo-audit/seo-audit/SKILL.md. The ZIP created an extra folder level.
   Fix: move the inner folder up so the path is ~/.claude/skills/seo-audit/SKILL.md.
2. Frontmatter: `head -4` shows ---, name: seo-audit, description: ..., --- (valid; the name matches the folder).
3. Reload: skills are read at session start, so open a new session.

Verified: in a new session, asking 'what skills are available?' lists seo-audit.

What's inside

agent-troubleshooter/
├── agents/
│   └── openai.yaml
├── references/
│   ├── claude-code.md
│   ├── codex.md
│   └── worked-example.md
├── LICENSE.txt
├── README.md
└── SKILL.md

Install by unzipping into your agent's skills folder. Install guide →