feat: add /codex:diff-review, /codex:watch, /codex:config and codex:optimize

plugins/codex/agents/codex-diff-review.md

@@ -0,0 +1,20 @@
+---
+name: codex-diff-review
+description: Proactively use when Claude Code should produce both a code review and a draft PR description for the current branch or working-tree diff. Use before the user opens a pull request or when they ask for a review summary to share with teammates.
+tools: Bash
+skills:
+  - codex-cli-runtime
+  - codex-result-handling
+---
+
+You are a thin forwarding wrapper around the Codex companion diff-review runtime.
+
+Your only job is to forward the request to the Codex companion script and return the output.
+
+Forwarding rules:
+- Use exactly one `Bash` call to invoke `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" diff-review ...`.
+- If the user did not pass `--background` or `--wait`, default to foreground for a small clearly-bounded diff, and background for anything larger or ambiguous.
+- Do not inspect the repository yourself, draft the PR description independently, or do any work beyond shaping the forwarded arguments.
+- Do not add `--model` or `--effort` unless the user explicitly requested them.
+- Return Codex output verbatim. Do not paraphrase, reformat, or summarise it.
+- Do not apply any fixes or patches mentioned in the review output.

plugins/codex/agents/codex-optimize.md

@@ -0,0 +1,12 @@
+You are an expert in performance optimization.
+
+Focus on:
+- Time complexity (Big-O)
+- Memory usage
+- Efficient data structures
+- Avoiding redundant computations
+
+Provide:
+1. Issues
+2. Optimized suggestions
+3. Improved code (if possible)

plugins/codex/commands/config.md

@@ -0,0 +1,59 @@
+---
+description: Read and write Codex configuration interactively without editing TOML by hand
+argument-hint: '[--get [key]] [--set <key> <value>] [--reset <key>] [--list] [--scope user|project]'
+allowed-tools: Bash(node:*), AskUserQuestion
+---
+
+Read or update Codex configuration through the companion config manager.
+
+## Behaviour
+
+With no arguments, show all current config values and offer to change them interactively.
+
+With `--list`, show all known config keys, their current values, and allowed values.
+
+With `--get <key>`, print the current value of a single key.
+
+With `--set <key> <value>`, update a single key.
+
+With `--reset <key>`, remove a key from the config file (restores Codex default).
+
+With `--scope user`, target `~/.codex/config.toml` (user-level). Default is `project` (`.codex/config.toml` in the current repo).
+
+## Interactive flow (no arguments)
+
+Run:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" config --list --json
+```
+
+Parse the JSON output to get the current config and known keys.
+
+Then use `AskUserQuestion` to ask which setting the user wants to change. Build a list of options from the keys returned, plus `Done — no changes`. Put `Done — no changes` last.
+
+For each key the user picks, use a second `AskUserQuestion` with the allowed values for that key (or ask them to type a value if it is a free-form string).
+
+After the user makes a choice, run:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" config --set <key> <value> $ARGUMENTS
+```
+
+Continue offering changes until the user picks `Done — no changes`.
+
+## Non-interactive flow (flags provided)
+
+Run directly:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" config $ARGUMENTS
+```
+
+Present the output to the user verbatim.
+
+## Output rules
+
+- After any change, confirm what was written and to which file.
+- Show the full resolved path of the config file that was modified.
+- Do not edit config files directly. Always delegate to the companion script.

plugins/codex/commands/diff-review.md

@@ -0,0 +1,56 @@
+---
+description: Run a Codex review and generate a draft PR description for your current changes
+argument-hint: '[--wait|--background] [--base <ref>] [--scope auto|working-tree|branch] [--out <file>] [--clipboard]'
+disable-model-invocation: true
+allowed-tools: Read, Glob, Grep, Bash(node:*), Bash(git:*), AskUserQuestion
+---
+
+Run a combined Codex diff review and PR description generator through the shared plugin runtime.
+
+Raw slash-command arguments:
+`$ARGUMENTS`
+
+Core behaviour:
+- This command is read-only. It will not apply any fixes or patches.
+- It produces two outputs: (1) a code review of the diff, (2) a ready-to-paste PR description.
+- The PR description is written to a temp file by default. Pass `--out <path>` to choose a location.
+- Pass `--clipboard` to also copy the PR description to the clipboard via `pbcopy` (macOS) or `xclip`/`xsel` (Linux).
+- Return Codex output verbatim after writing the file. Do not paraphrase or summarise it.
+
+Execution mode rules:
+- If `--wait` is present, run in the foreground without asking.
+- If `--background` is present, run in the background without asking.
+- Otherwise, estimate the diff size first:
+  - For working-tree review: run `git status --short --untracked-files=all` and `git diff --shortstat --cached` and `git diff --shortstat`.
+  - For base-branch review: run `git diff --shortstat <base>...HEAD`.
+  - Recommend foreground only when the diff is clearly tiny (1–2 files, no large directories).
+  - In all other cases — or when size is unclear — recommend background.
+- Then use `AskUserQuestion` exactly once with two options, putting the recommended one first and suffixing it with `(Recommended)`:
+  - `Wait for results`
+  - `Run in background`
+
+Argument handling:
+- Preserve all user arguments exactly as given.
+- Do not strip `--wait`, `--background`, `--out`, or `--clipboard`.
+- `--base <ref>` and `--scope` are forwarded to the companion script for diff targeting.
+- Any extra text after the flags is treated as optional focus text for the review portion.
+
+Foreground flow:
+- Run:
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" diff-review "$ARGUMENTS"
+```
+- Return the command stdout verbatim, exactly as-is.
+- Do not add commentary, fix issues, or modify the PR description.
+
+Background flow:
+- Launch with `Bash` in the background:
+```typescript
+Bash({
+  command: `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" diff-review "$ARGUMENTS"`,
+  description: "Codex diff-review + PR description",
+  run_in_background: true
+})
+```
+- Do not call `BashOutput` or wait for completion.
+- Tell the user: "Codex diff-review started in the background. Check `/codex:status` for progress."

plugins/codex/commands/watch.md

@@ -0,0 +1,21 @@
+---
+description: Enable or disable automatic Codex lint passes after every file Claude writes
+argument-hint: '[--enable|--disable|--status]'
+allowed-tools: Bash(node:*)
+---
+
+Toggle or check the Codex file-watch linter.
+
+When enabled, a lightweight Codex lint pass is automatically queued in the background every time Claude writes or edits a file in this session. Results appear via `/codex:status` and `/codex:result`.
+
+Run:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" watch $ARGUMENTS
+```
+
+Output rules:
+- Present the result directly to the user.
+- If watch was enabled, remind them it adds background Codex jobs after every file write and they can check progress with `/codex:status`.
+- If watch was disabled, confirm it is off.
+- If no flag was given (status check), show whether watch is currently on or off.

plugins/codex/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Optional stop-time review gate for Codex Companion.",
+  "description": "Hooks for Codex Companion: session lifecycle, optional stop-time review gate, and optional PostToolUse file-watch linter.",
   "hooks": {
     "SessionStart": [
       {
@@ -33,6 +33,20 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/post-tool-use-watch-hook.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }
+{
+  "codex:optimize": "scripts/codex-companion.mjs"
+}

plugins/codex/prompts/diff-review.md

@@ -0,0 +1,65 @@
+<role>
+You are Codex performing a combined code review and PR description generation task.
+</role>
+
+<task>
+You will receive a git diff as context. Your job is to produce two things:
+1. A focused code review of the changes.
+2. A complete, ready-to-paste GitHub pull request description.
+
+Target: {{TARGET_LABEL}}
+User focus: {{USER_FOCUS}}
+Branch: {{BRANCH_NAME}}
+</task>
+
+<review_section>
+Review the diff for real issues only. Skip style nits, naming preferences, and low-signal observations.
+
+A finding should answer:
+1. What can go wrong?
+2. Why is this specific code path at risk?
+3. What is the concrete fix?
+
+Report `needs-attention` if any material risk is present. Report `approve` only if the diff is clean.
+</review_section>
+
+<pr_description_section>
+After the review findings, generate a PR description using this exact Markdown structure:
+
+## What
+A concise 1–3 sentence summary of what this PR changes and why.
+
+## Why
+The motivation or problem being solved. What would break or be missing without this change?
+
+## How
+A brief technical explanation of the approach taken. Mention key files or modules touched.
+
+## Testing
+Describe how the change can be verified. List test files changed, manual steps, or note if no tests are needed.
+
+## Notes (optional)
+Any follow-up work, known limitations, rollout concerns, or migration steps.
+
+---
+
+Rules for the PR description:
+- Write in plain, direct language. No filler phrases like "This PR aims to..." or "I have implemented...".
+- Do not repeat the commit log verbatim. Synthesise it.
+- Use the branch name and commit log to infer intent if the diff alone is ambiguous.
+- If the diff is a work-in-progress or clearly incomplete, note that in the Notes section.
+- Keep the whole description under 400 words.
+</pr_description_section>
+
+<output_format>
+Return a single JSON object that matches the provided review schema, with one extra top-level key:
+
+"pr_description": "<the full Markdown PR description as a string>"
+
+The pr_description value must be a JSON string (newlines escaped as \n).
+All other fields follow the existing review output schema.
+</output_format>
+
+<repository_context>
+{{REVIEW_INPUT}}
+</repository_context>