codex-debugging — Claude Code skill: what it does, how to install
codex-debugging guides debugging across the codex-rs repository. Essential when investigating runtime bugs, CLI behavior, or config parsing issues.
MIT 108 installs ★ 7,554 updated 2026-10-20
npx skills add steipete/agent-scripts --skill codex-debugging -a claude-codeWhat codex-debugging does
This skill provides a systematic debugging workflow for the codex-rs codebase. It directs the agent to investigate submodules such as CLI, TUI, app server, and configuration handling before touching any code.
Local source code comes first. The workflow inspects codex-rs/AGENTS.md and uses rg to trace symbols and errors across specific crates. Only after verifying the source contract does the agent inspect ~/.codex/config.toml. Speculation is avoided in favor of small reproductions and adjacent tests.
For browser automation in the CLI, you must use $browser-use because the bundled Browser plugin runs exclusively in the Codex desktop app.
What it helps with
- trace runtime bugs across
codex-rssubmodules - debug configuration parsing issues in
~/.codex/config.toml - verify app-server protocol wiring before patching
- create focused reproduction tests for CLI failures
Example prompts for the agent
- Inspect the error in
codex-rs/cliand check adjacent tests - Investigate configuration parsing issues in
~/.codex/config.tomlusingcodex-rs/config - Trace the failure in
app-server-protocolbefore suggesting fixes
How to install codex-debugging
1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill codex-debugging -a claude-code2Manually: put the files in place
~/.claude/skills/codex-debugging/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/codex-debugging/
1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill codex-debugging -a codex2Manually: put the files in place
.agents/skills/codex-debugging/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill codex-debugging -a cursor2Manually: put the files in place
.cursor/skills/codex-debugging/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install steipete/agent-scripts skills/codex-debugging2Manually: put the files in place
.github/skills/codex-debugging/SKILL.md1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill codex-debugging -a gemini-cli2Platform CLI
gemini skills install https://github.com/steipete/agent-scripts --path skills/codex-debuggingManually: put the files in place
.devin/skills/codex-debugging/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill codex-debugging -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about codex-debugging
How do I install codex-debugging in Claude Code?
Run npx skills add steipete/agent-scripts --skill codex-debugging -a claude-code. The skill file is placed at ~/.claude/skills/codex-debugging/SKILL.md.
What does codex-debugging do?
It establishes an inspection routine for the codex-rs architecture. The skill prioritizes local source code and targeted tests over external documentation.
How do I automate browser actions in CLI mode?
Use $browser-use for command-line browser tasks. The bundled Browser plugin works only inside the Codex desktop app.
Source text
SKILL.md · MIT
---
name: codex-debugging
description: "Codex debugging: codex-rs core/tui/exec/cli/app-server/config."
---
# Codex Debugging
Use when investigating Codex CLI/app behavior, config parsing, tool behavior, prompts, MCP/app wiring, or runtime bugs.
## Source First
Prefer local source before web/docs:
```bash
cd ~/Projects/codex
sed -n '1,220p' codex-rs/AGENTS.md
```
Then search targeted areas:
```bash
rg "<symbol|setting|error|feature>" codex-rs/{core,tui,exec,cli,app-server,app-server-protocol,config}
```
## Workflow
1. Identify whether the behavior is CLI, TUI, app server, protocol, config, or exec/tooling.
2. Read the owning module and adjacent tests before proposing changes.
3. Check local config in `~/.codex/config.toml` only after understanding the source contract.
4. Prefer small repros or focused tests over broad speculation.
## Notes
- For OpenAI API/product docs, use the official-docs path only when source is insufficient.
- For local browser automation in CLI, use `$browser-use`; the bundled Browser plugin is Codex app-only.
© steipete · MIT · steipete/agent-scripts