Codex Plugin

Author: nhorton

README.md

@@ -28,6 +28,17 @@ Then start a new session and define your first job:
 
 > **Note:** DeepWork stores job definitions in `.deepwork/jobs/` and creates work branches in Git. Your project folder should be a Git repository. If it isn't, run `git init` first, or ask Claude to do so.
 
+### Codex
+
+When you run the DeepWork MCP server with `--platform codex`, DeepWork bootstraps
+repo-local Codex hooks for you by ensuring:
+
+- `.codex/config.toml` enables `codex_hooks`
+- `.codex/hooks.json` contains the DeepWork `SessionStart` and `PostToolUse` handlers
+
+This keeps the Codex hook setup checked into the project instead of relying on a
+manual one-time local setup step.
+
 ---
 
 ## The Problem

doc/architecture.md

@@ -133,6 +133,8 @@ The serve command:
 - Creates `.deepwork/tmp/` lazily for session state
 - Launches the FastMCP server (stdio or SSE transport)
 - No config file required — works out of the box
+- When started with `--platform codex`, also ensures repo-local Codex hook files
+  exist under `.codex/` so SessionStart and PostToolUse DeepWork hooks are enabled
 
 ### 2. Hook Command (`hook.py`)
 
@@ -180,6 +182,10 @@ Platform-specific delivery is now handled by plugins in `plugins/`:
 - **Claude Code**: `plugins/claude/` — installed as a Claude Code plugin via marketplace
 - **Gemini CLI**: `plugins/gemini/` — skill files copied to `.gemini/skills/`
 
+Codex hook integration is repo-local rather than plugin-local today. When the MCP
+server starts with `--platform codex`, DeepWork ensures `.codex/config.toml`
+enables `codex_hooks` and `.codex/hooks.json` contains the DeepWork hook entries.
+
 Each plugin contains static files (skill, hooks, MCP config) rather than generated content. The shared skill body lives in `platform/skill-body.md` as the single source of truth.
 
 ---
@@ -1108,4 +1114,3 @@ deepwork serve --transport sse --port 8000
 - [JSON Schema](https://json-schema.org/)
 - [Model Context Protocol](https://modelcontextprotocol.io/)
 - [FastMCP Documentation](https://github.com/jlowin/fastmcp)
-

src/deepwork/cli/codex_hook.py

@@ -0,0 +1,21 @@
+"""Internal Codex hook entrypoints for DeepWork."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from deepwork.codex_hooks import CodexHookSetupError, run_codex_hook
+
+
+@click.command(name="codex-hook", hidden=True)
+@click.argument("hook_name", type=click.Choice(["session_start", "post_tool_use"]))
+def codex_hook(hook_name: str) -> None:
+    """Run a DeepWork Codex hook and emit the JSON response expected by Codex."""
+    raw_input = sys.stdin.read() if not sys.stdin.isatty() else ""
+    try:
+        click.echo(run_codex_hook(hook_name, raw_input))
+    except CodexHookSetupError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)

src/deepwork/cli/main.py

@@ -11,12 +11,14 @@ def cli() -> None:
 
 
 # Import commands
+from deepwork.cli.codex_hook import codex_hook  # noqa: E402
 from deepwork.cli.hook import hook  # noqa: E402
 from deepwork.cli.install import install, sync  # noqa: E402
 from deepwork.cli.jobs import jobs  # noqa: E402
 from deepwork.cli.review import review  # noqa: E402
 from deepwork.cli.serve import serve  # noqa: E402
 
+cli.add_command(codex_hook)
 cli.add_command(hook)
 cli.add_command(jobs)
 cli.add_command(review)

src/deepwork/cli/review.py

@@ -15,7 +15,7 @@
 @click.option(
     "--instructions-for",
     "instructions_for",
-    type=click.Choice(["claude"]),
+    type=click.Choice(["claude", "codex"]),
     required=True,
     help="Target platform for review instructions.",
 )
@@ -54,15 +54,15 @@ def review(
 
     \b
       # Pipe from git
-      git diff --name-only HEAD~3 | deepwork review --instructions-for claude
+      git diff --name-only HEAD~3 | deepwork review --instructions-for codex
 
     \b
       # Glob (shell expands the pattern)
-      printf '%s\n' src/**/*.py | deepwork review --instructions-for claude
+      printf '%s\n' src/**/*.py | deepwork review --instructions-for codex
 
     \b
       # find
-      find src -name '*.py' | deepwork review --instructions-for claude
+      find src -name '*.py' | deepwork review --instructions-for codex
     """
     project_root = Path(path).resolve()
 
@@ -101,7 +101,7 @@ def review(
         sys.exit(1)
 
     # Step 5: Format and output
-    if instructions_for == "claude":
+    if instructions_for in {"claude", "codex"}:
         output = format_for_claude(task_files, project_root)
         click.echo(output)