# claude-codex-judge

A [Claude Code](https://claude.com/claude-code) skill that uses OpenAI's `codex`
CLI (`gpt-5.5` at `xhigh` reasoning) as an independent, **read-only judging
agent** — a second model that reviews Claude's plans, designs, diffs, and
decisions and argues back. The judge keeps a session across turns, so Claude can
rebut and drill in rather than getting a one-shot opinion.

## What's here

```
.claude/skills/codex-judge/
  SKILL.md          # when/how Claude should invoke the judge
  codex-judge.sh    # wrapper: start | ask | new (handles session continuity)
CLAUDE.md           # language-agnostic behavioral guidelines that tell Claude to use the judge
```

## Prerequisites

- [Claude Code](https://claude.com/claude-code)
- The [`codex` CLI](https://github.com/openai/codex) installed and logged in
  (`codex login`). Tested against `codex-cli` 0.130.0.

## Install

Drop the skill into the project (or user) `.claude/skills/` directory:

```bash
# from your project root
mkdir -p .claude/skills
cp -R /path/to/claude-codex-judge/.claude/skills/codex-judge .claude/skills/
```

Optionally adopt the root `CLAUDE.md` (it instructs Claude to route significant
work through the judge). Merge it with any existing project guidelines.

## Use

Claude invokes the skill on its own when a decision is worth a second opinion.
You can also drive the wrapper directly:

```bash
# start a judging session (prompt via heredoc, stdin, or argument)
.claude/skills/codex-judge/codex-judge.sh start <<'EOF'
You are a strict, skeptical reviewer. Judge the plan below and end with a
verdict (SHIP / REVISE / REJECT) and the single most important fix.

PLAN: ...
EOF

# judge a diff (the piped content is appended to the instruction)
git diff | .claude/skills/codex-judge/codex-judge.sh start "Judge the diff below for correctness and simplicity. Give a SHIP/REVISE/REJECT verdict."

# continue the same conversation, with full prior context
.claude/skills/codex-judge/codex-judge.sh ask "You flagged the retry loop — it's bounded by MAX_RETRIES=5. Resolved?"

# forget the session when switching topics
.claude/skills/codex-judge/codex-judge.sh new
```

The judge runs in a **read-only** sandbox on every turn (start and resume), so it
can read the repo for context but never edits files. Override reasoning effort
with `CODEX_JUDGE_EFFORT` (default `xhigh`).

See [`.claude/skills/codex-judge/SKILL.md`](.claude/skills/codex-judge/SKILL.md)
for the full guidance Claude follows.