feat: add OpenAI Codex hook support

Adds provider-aware hooks for OpenAI Codex, setup output for ~/.codex/hooks.json, docs, tests, and the 0.67.0 version bump.

Closes #191

Author: Siddhant-K-code

README.md

@@ -36,12 +36,13 @@ uvx agent-strace replay
 
 ## Quick start
 
-**Option 1: Claude Code hooks** — captures everything (prompts, responses, every tool call)
+**Option 1: CLI hooks** — captures prompts, responses, and hook-visible tool calls
 
 ```bash
-agent-strace setup   # prints hooks config — add to ~/.claude/settings.json
-agent-strace list    # list sessions
-agent-strace replay  # replay the latest
+agent-strace setup             # Claude Code hooks for ~/.claude/settings.json
+agent-strace setup --cli codex # OpenAI Codex hooks for ~/.codex/hooks.json
+agent-strace list              # list sessions
+agent-strace replay            # replay the latest
 ```
 
 Full config and JSON: [docs/setup.md](docs/setup.md)
@@ -138,7 +139,7 @@ Install **agent-strace** from the [Extensions panel](https://open-vsx.org/extens
 
 ```bash
 pip install agent-strace   # 1. install
-agent-strace setup         # 2. add hooks to Claude Code
+agent-strace setup         # 2. add hooks to Claude Code or use --cli codex for Codex
 # 3. open project in VS Code — extension activates when .agent-traces/ exists
 # 4. start Claude Code — status bar appears immediately
 ```

docs/commands.md

@@ -27,9 +27,9 @@ Capture an MCP HTTP/SSE server session. Listens on `--port` (default: 3100) and
 
 ### `setup`
 ```
-agent-strace setup [--no-redact] [--global]
+agent-strace setup [--cli claude|codex|all] [--no-redact] [--global]
 ```
-Print Claude Code hooks config JSON for `~/.claude/settings.json`. Use `--global` to scope hooks to all projects (default scopes to the current project). Secret redaction is enabled by default; use `--no-redact` only for trusted local traces.
+Print hooks config JSON for supported agent CLIs. `--cli claude` prints Claude Code settings JSON for `~/.claude/settings.json`; `--cli codex` prints OpenAI Codex hooks JSON for `~/.codex/hooks.json`; `--cli all` prints both. Secret redaction is enabled by default; use `--no-redact` only for trusted local traces.
 
 ### `import`
 ```

docs/integrations.md

@@ -48,6 +48,19 @@ Each integration is an optional extra — the core package stays dependency-free
 
 ---
 
+## Agent CLI hooks
+
+Use setup-generated hooks when the agent CLI has its own lifecycle hook system.
+
+| CLI | Setup | What's traced |
+|---|---|---|
+| Claude Code | `agent-strace setup --cli claude` | Session start/end, user prompts, assistant responses, tool calls/results |
+| OpenAI Codex | `agent-strace setup --cli codex` | Session start, user prompts, assistant responses, `PreToolUse`/`PostToolUse` tools |
+
+Both paths write the same event stream under `.agent-traces/`, so replay, timeline, explain, why, watch, export, and audit commands work the same way after capture.
+
+---
+
 ## OpenAI Agents SDK
 
 ```python

docs/setup.md

@@ -4,14 +4,20 @@ Three ways to capture agent sessions. Pick the one that matches your agent.
 
 ---
 
-## Option 1: Claude Code hooks (recommended)
+## Option 1: CLI hooks (recommended)
 
 Captures everything: user prompts, assistant responses, and every tool call (Bash, Edit, Write, Read, Agent, Grep, Glob, WebFetch, WebSearch, all MCP tools).
 
 ```bash
-# Generate and apply hooks config
+# Generate Claude Code hooks config
 agent-strace setup
 
+# Generate OpenAI Codex hooks config
+agent-strace setup --cli codex
+
+# Generate both hook configs
+agent-strace setup --cli all
+
 # For all projects (global config)
 agent-strace setup --global
 
@@ -43,6 +49,24 @@ agent-strace replay   # replay the latest
 agent-strace explain  # plain-English summary
 ```
 
+### OpenAI Codex hooks
+
+`agent-strace setup --cli codex` prints hooks JSON for `~/.codex/hooks.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{ "matcher": "startup|resume|clear|compact", "hooks": [{ "type": "command", "command": "agent-strace hook --provider codex session-start" }] }],
+    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "agent-strace hook --provider codex user-prompt" }] }],
+    "PreToolUse": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "agent-strace hook --provider codex pre-tool" }] }],
+    "PostToolUse": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "agent-strace hook --provider codex post-tool" }] }],
+    "Stop": [{ "hooks": [{ "type": "command", "command": "agent-strace hook --provider codex stop" }] }]
+  }
+}
+```
+
+Codex sends one JSON object to each command hook on stdin. agent-strace records the common Codex fields (`session_id`, `turn_id`, `tool_use_id`, `tool_name`, `tool_input`, `tool_response`, `prompt`, and `last_assistant_message`) into the same `.agent-traces/` session store used by Claude Code.
+
 ### Import existing sessions
 
 Already ran sessions without hooks? Import from Claude Code's native JSONL logs:

src/agent_trace/__init__.py

@@ -1,3 +1,3 @@
 """agent-trace: strace for AI agents."""
 
-__version__ = "0.66.0"
+__version__ = "0.67.0"

src/agent_trace/cli.py

@@ -450,16 +450,18 @@ def cmd_stats(args: argparse.Namespace) -> int:
     return 0
 
 
-def cmd_setup(args: argparse.Namespace) -> None:
-    """Generate Claude Code hooks configuration."""
+def _hook_command_prefix(args: argparse.Namespace, provider: str = "claude") -> str:
     redact_env = ""
     if args.no_redact:
         redact_env = "AGENT_TRACE_NO_REDACT=1 "
     elif args.redact:
         redact_env = "AGENT_TRACE_REDACT=1 "
+    provider_arg = "" if provider == "claude" else f"--provider {provider} "
+    return f"{redact_env}agent-strace hook {provider_arg}".rstrip()
 
-    cmd_prefix = f"{redact_env}agent-strace hook"
 
+def _claude_hooks_config(args: argparse.Namespace) -> dict:
+    cmd_prefix = _hook_command_prefix(args, provider="claude")
     config = {
         "hooks": {
             "UserPromptSubmit": [{
@@ -488,16 +490,69 @@ def cmd_setup(args: argparse.Namespace) -> None:
             }],
         }
     }
+    return config
+
+
+def _codex_hooks_config(args: argparse.Namespace) -> dict:
+    cmd_prefix = _hook_command_prefix(args, provider="codex")
+    return {
+        "hooks": {
+            "SessionStart": [{
+                "matcher": "startup|resume|clear|compact",
+                "hooks": [{
+                    "type": "command",
+                    "command": f"{cmd_prefix} session-start",
+                }],
+            }],
+            "UserPromptSubmit": [{
+                "hooks": [{
+                    "type": "command",
+                    "command": f"{cmd_prefix} user-prompt",
+                }],
+            }],
+            "PreToolUse": [{
+                "matcher": ".*",
+                "hooks": [{
+                    "type": "command",
+                    "command": f"{cmd_prefix} pre-tool",
+                }],
+            }],
+            "PostToolUse": [{
+                "matcher": ".*",
+                "hooks": [{
+                    "type": "command",
+                    "command": f"{cmd_prefix} post-tool",
+                }],
+            }],
+            "Stop": [{
+                "hooks": [{
+                    "type": "command",
+                    "command": f"{cmd_prefix} stop",
+                }],
+            }],
+        }
+    }
+
+
+def cmd_setup(args: argparse.Namespace) -> None:
+    """Generate hooks configuration for supported agent CLIs."""
+    cli = getattr(args, "cli", "claude") or "claude"
 
-    output = json.dumps(config, indent=2)
+    configs: list[tuple[str, str, dict]] = []
+    if cli in ("claude", "all"):
+        configs.append(("Claude Code", "~/.claude/settings.json", _claude_hooks_config(args)))
+    if cli in ("codex", "all"):
+        configs.append(("OpenAI Codex", "~/.codex/hooks.json", _codex_hooks_config(args)))
 
-    sys.stderr.write("Add this to ~/.claude/settings.json:\n\n")
+    for idx, (name, path, config) in enumerate(configs):
+        if idx:
+            sys.stdout.write("\n")
+        sys.stderr.write(f"Add this to {path} for {name}:\n\n")
+        sys.stdout.write(json.dumps(config, indent=2) + "\n")
 
-    sys.stdout.write(output + "\n")
     sys.stderr.write(
-        "\nThis captures the full Claude Code session: user prompts, "
-        "assistant responses, and every tool call (Bash, Edit, Write, "
-        "Read, Agent, and all MCP tools).\n"
+        "\nThis captures full agent sessions: user prompts, assistant "
+        "responses, and hook-visible tool calls.\n"
         "Replay with: agent-strace replay\n"
     )
 
@@ -622,12 +677,14 @@ def build_parser() -> argparse.ArgumentParser:
     p_stats.add_argument("--include-subagents", action="store_true",
                          help="roll up stats across all subagent sessions")
 
-    # hook (called by Claude Code hooks system)
-    p_hook = sub.add_parser("hook", help="handle a Claude Code hook event (internal)")
+    # hook (called by agent CLI hooks systems)
+    p_hook = sub.add_parser("hook", help="handle an agent CLI hook event (internal)")
+    p_hook.add_argument("--provider", choices=["claude", "codex"], default="claude",
+                        help="hook provider (default: claude)")
     p_hook.add_argument("event", nargs="?", help="hook event: session-start, session-end, pre-tool, post-tool, post-tool-failure")
 
-    # setup (generate Claude Code hooks config)
-    p_setup = sub.add_parser("setup", help="generate Claude Code hooks configuration")
+    # setup (generate agent CLI hooks config)
+    p_setup = sub.add_parser("setup", help="generate agent CLI hooks configuration")
     setup_redaction = p_setup.add_mutually_exclusive_group()
     setup_redaction.add_argument(
         "--redact",
@@ -640,6 +697,8 @@ def build_parser() -> argparse.ArgumentParser:
         help="disable automatic secret redaction in generated hooks",
     )
     p_setup.add_argument("--global", dest="global_config", action="store_true", help="output config for ~/.claude/settings.json (all projects)")
+    p_setup.add_argument("--cli", choices=["claude", "codex", "all"], default="claude",
+                         help="agent CLI to configure (default: claude)")
 
     # import (Claude Code JSONL session logs)
     p_import = sub.add_parser("import", help="import a Claude Code JSONL session log")
@@ -1332,7 +1391,10 @@ def main() -> None:
 
     # hook subcommand is handled separately (reads stdin)
     if args.command == "hook":
-        hook_main([args.event] if args.event else [])
+        hook_args = ["--provider", getattr(args, "provider", "claude")]
+        if args.event:
+            hook_args.append(args.event)
+        hook_main(hook_args)
         sys.exit(0)
 
     if args.command == "setup":