Skip to content
Get packs

Codex Debugging Guide

Investigate Codex CLI bugs by reading local source code and targeted tests first

Source Download skill
Repository
steipete/agent-scripts
Stars
7,433
Licence
MIT
Files
1 file

What it does

This skill gives an AI agent a checklist for debugging the Codex command-line tool and related app. Instead of guessing, the agent is told to look at the local Codex source code first, search the relevant modules (core, terminal UI, exec, CLI, app server, config), read the nearby tests, and then try small reproductions before proposing fixes. It only checks a local config file after it understands the expected behaviour in the source.

Great for

  • Developers who maintain or contribute to the open-source Codex codebase
  • Engineers chasing config parsing, tool-call, prompt, or MCP wiring bugs in Codex
  • Anyone who has a local clone of the codex-rs repository and wants the agent to work from source

Skip it if

  • People who simply use Codex and want general help: the skill assumes a local checkout at ~/Projects/codex and is written for maintainers, not end users
  • Non-code tasks or general OpenAI API questions, since the skill only points to official docs as a fallback (the reason: it is scoped to Codex internals)

Try asking

  • “Why is my Codex config.toml setting being ignored? Check the config parsing code first.”
  • “Investigate why a tool call in the Codex exec module returns the wrong output.”
  • “Find where the TUI handles this error message and propose a focused fix with a test.”
  • “Trace how MCP servers are wired into the Codex app server.”
Step-by-step guide: how to use Codex Debugging GuideInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 1 original files, the MIT licence and an attribution note.

    codex-debugging.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip codex-debugging.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip codex-debugging.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Point the agent at your real Codex checkout, or edit the hardcoded ~/Projects/codex path first.
  • Give the agent a concrete symptom, error text, or setting name so its rg search has a target.
  • Ask for a small reproduction or failing test before any code changes are made.

What's inside

  • SKILL.md

Redistributed unmodified from steipete/agent-scripts under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.