rtk-ai · xuegaoge · May 24, 2026 · May 24, 2026 · May 24, 2026
diff --git a/README.md b/README.md
@@ -104,7 +104,7 @@ rtk gain        # Should show token savings stats
 # 1. Install for your AI tool
 rtk init -g                     # Claude Code / Copilot (default)
 rtk init -g --gemini            # Gemini CLI
-rtk init -g --codex             # Codex (OpenAI)
+rtk init -g --codex             # Codex plugin (OpenAI)
 rtk init -g --agent cursor      # Cursor
 rtk init --agent windsurf       # Windsurf
 rtk init --agent cline          # Cline / Roo Code
@@ -360,7 +360,7 @@ RTK supports 13 AI coding tools. Each integration rewrites shell commands to `rt
 | **GitHub Copilot CLI** | `rtk init -g --copilot` | PreToolUse deny-with-suggestion (CLI limitation) |
 | **Cursor** | `rtk init -g --agent cursor` | preToolUse hook (hooks.json) |
 | **Gemini CLI** | `rtk init -g --gemini` | BeforeTool hook |
-| **Codex** | `rtk init -g --codex` | AGENTS.md + RTK.md instructions |
+| **Codex** | `rtk init -g --codex` | Codex plugin with RTK skill + PreToolUse hook |
 | **Windsurf** | `rtk init --agent windsurf` | .windsurfrules (project-scoped) |
 | **Cline / Roo Code** | `rtk init --agent cline` | .clinerules (project-scoped) |
 | **OpenCode** | `rtk init -g --opencode` | Plugin TS (tool.execute.before) |

diff --git a/docs/contributing/TECHNICAL.md b/docs/contributing/TECHNICAL.md
@@ -315,7 +315,7 @@ Start here, then drill down into each README for file-level details.
 | [`cursor/`](../hooks/cursor/README.md) | Cursor IDE | Shell hook, empty JSON response requirement |
 | [`cline/`](../hooks/cline/README.md) | Cline / Roo Code | Rules file (prompt-level, no programmatic hook) |
 | [`windsurf/`](../hooks/windsurf/README.md) | Windsurf / Cascade | Rules file (workspace-scoped) |
-| [`codex/`](../hooks/codex/README.md) | OpenAI Codex CLI | Awareness document, AGENTS.md integration |
+| [`codex/`](../hooks/codex/README.md) | OpenAI Codex CLI | Codex plugin package, RTK skill, PreToolUse hook |
 | [`opencode/`](../hooks/opencode/README.md) | OpenCode | TypeScript plugin, zx library, in-place mutation |
 
 ---
@@ -333,7 +333,7 @@ RTK supports the following LLM agents through hook integrations:
 | Gemini CLI | Rust binary | `rtk hook gemini` reads JSON | Yes (`hookSpecificOutput`) |
 | Cline/Roo Code | Rules file | Prompt-level guidance | N/A (prompt) |
 | Windsurf | Rules file | Prompt-level guidance | N/A (prompt) |
-| Codex CLI | Awareness doc | AGENTS.md integration | N/A (prompt) |
+| Codex CLI | Codex plugin | `rtk hook codex` PreToolUse processor | Yes (`updatedInput`) |
 | OpenCode | TS plugin | `tool.execute.before` event | Yes (in-place mutation) |
 
 > **Details**: [`hooks/README.md`](../hooks/README.md) has the full JSON schemas for each agent. [`src/hooks/README.md`](../src/hooks/README.md) covers installation, integrity verification, and the rewrite command.

diff --git a/docs/guide/getting-started/supported-agents.md b/docs/guide/getting-started/supported-agents.md
@@ -39,7 +39,7 @@ Agent runs "cargo test"
 | Hermes | Python plugin (`terminal` command mutation) | Yes |
 | Cline / Roo Code | Rules file (prompt-level) | N/A |
 | Windsurf | Rules file (prompt-level) | N/A |
-| Codex CLI | AGENTS.md instructions | N/A |
+| Codex CLI | Codex plugin (`PreToolUse`) | Yes |
 | Kilo Code | Rules file (prompt-level) | N/A |
 | Google Antigravity | Rules file (prompt-level) | N/A |
 | Mistral Vibe | Planned ([#800](https://github.com/rtk-ai/rtk/issues/800)) | Pending upstream |
@@ -142,9 +142,12 @@ rtk init --windsurf    # creates .windsurfrules in current project
 ### Codex CLI
 
 ```bash
-rtk init --codex    # creates AGENTS.md or patches existing one
+rtk init --codex       # registers local RTK Codex plugin marketplace
+rtk init -g --codex    # registers personal RTK Codex plugin marketplace
 ```
 
+The Codex plugin bundles an RTK skill and a Bash `PreToolUse` hook. The hook matches Codex's Bash tool payloads, but the installed command delegates directly to the native RTK binary with `rtk hook codex` on Linux/macOS and `rtk.exe hook codex` on Windows. After installation, restart Codex, enable or install the RTK plugin if Codex prompts for it, and review/trust the plugin hook in `/hooks`. Codex currently supports rewritten input only with `permissionDecision: "allow"`, so RTK does not emit unsupported `ask` rewrites. RTK preserves the original Bash `tool_input` and replaces only `command`.
+
 ### Kilo Code
 
 ```bash
@@ -173,7 +176,7 @@ Support is blocked on upstream `BeforeToolCallback` ([mistral-vibe#531](https://
 | **Plugin** | TypeScript, JavaScript, or Python in agent's plugin system | Transparent, in-place mutation when the agent allows it |
 | **Rules file** | Prompt-level instructions | Guidance only — agent is told to prefer `rtk <cmd>` |
 
-Rules file integrations (Cline, Windsurf, Codex, Kilo Code, Antigravity) rely on the model following instructions. Full hook integrations (Claude Code, Cursor, Gemini) are guaranteed — the command is rewritten before the agent sees it. Plugin integrations (OpenCode, Pi) use in-place mutation via the agent's TypeScript extension API.
+Rules file integrations (Cline, Windsurf, Kilo Code, Antigravity) rely on the model following instructions. Full hook integrations (Claude Code, Cursor, Gemini, Codex) are guaranteed after their hooks are enabled and trusted -- the command is rewritten before the agent sees it. Plugin integrations (OpenCode, Pi, Hermes) use the agent's plugin API to mutate commands before execution.
 
 ## Windows support
 

diff --git a/docs/usage/CODEX_PRETOOLUSE_ADAPTER.md b/docs/usage/CODEX_PRETOOLUSE_ADAPTER.md
@@ -0,0 +1,107 @@
+# Codex PreToolUse Adapter
+
+This guide installs RTK for Codex Desktop or Codex CLI with a native
+`PreToolUse` hook. The hook rewrites supported Bash commands through RTK before
+Codex executes them.
+
+## Quick setup
+
+Use this on machines that may or may not already have RTK installed. The
+commands reuse a working RTK installation when `rtk gain` succeeds, and install
+RTK only when it is missing or the wrong `rtk` binary is on `PATH`.
+
+```bash
+set -eu
+
+if ! command -v rtk >/dev/null 2>&1 || ! rtk gain >/dev/null 2>&1; then
+  curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh
+fi
+
+export PATH="$HOME/.local/bin:$PATH"
+
+rtk init -g --codex
+```
+
+Restart Codex, enable or install the RTK plugin if Codex prompts for it, then
+review and trust the RTK hook from `/hooks` or the Codex settings panel.
+
+## What gets installed
+
+`rtk init -g --codex` registers the RTK Codex plugin in the user-level Codex
+environment:
+
+- `$CODEX_HOME/plugins/rtk-codex/` or `~/.codex/plugins/rtk-codex/`
+- `~/.agents/plugins/marketplace.json`
+- A plugin-owned `PreToolUse` hook that runs `rtk hook codex`
+- A bundled `$rtk` skill that explains RTK behavior and validation
+
+For project-local setup, run `rtk init --codex` inside the project. That writes
+the local plugin package under the project plugin directory and registers it in
+the local marketplace.
+
+## Behavior
+
+- Handles Codex `Bash` tool calls only.
+- Uses RTK's native `rtk hook codex` processor, so new rewrite rules are picked
+  up by the installed RTK binary.
+- Rewrites supported commands such as `git status` to `rtk git status`.
+- Preserves the rest of Codex's original `tool_input`; only `command` is
+  replaced.
+- Produces no hook output when RTK has no rewrite, the payload is malformed, the
+  tool is not Bash, the command is already RTK-prefixed, or the command contains
+  a heredoc.
+- Returns rewritten input only with `permissionDecision: "allow"`, matching the
+  Codex hook contract.
+
+## Verify
+
+Check the RTK binary:
+
+```bash
+rtk --version
+rtk gain
+```
+
+Check the Codex installation:
+
+```bash
+rtk init --show --codex
+```
+
+Preview a rewrite:
+
+```bash
+rtk hook check git status
+```
+
+After Codex has restarted and the hook is trusted, run a simple Bash command
+such as:
+
+```bash
+git status
+```
+
+When the hook is active, Codex should execute the RTK-prefixed form and RTK
+usage should appear in:
+
+```bash
+rtk gain
+```
+
+## Uninstall
+
+For global setup:
+
+```bash
+rtk init -g --codex --uninstall
+```
+
+For project-local setup:
+
+```bash
+rtk init --codex --uninstall
+```
+
+Uninstall removes only RTK-managed plugin state, marketplace entries, and legacy
+RTK-managed Codex guidance. Unrelated Codex plugins and marketplace entries are
+preserved.
diff --git a/hooks/README.md b/hooks/README.md
@@ -2,7 +2,7 @@
 
 ## Scope
 
-**Deployed hook artifacts** — the actual files installed on user machines by `rtk init`. These are shell scripts, TypeScript plugins, and rules files that run outside the Rust binary. They are **thin delegates**: parse agent-specific JSON, call `rtk rewrite` as a subprocess, format agent-specific response. Zero filtering logic lives here.
+**Deployed hook artifacts** — the actual files installed on user machines by `rtk init`. These are shell scripts, Codex plugin files, TypeScript plugins, and rules files that run outside the Rust binary. They are **thin delegates**: parse agent-specific JSON, call the native RTK processor or `rtk rewrite`, and format agent-specific responses. Zero filtering logic lives here.
 
 Owns: per-agent hook scripts and configuration files for 9 supported agents (Claude Code, Copilot, Cursor, Cline, Windsurf, Codex, OpenCode, Hermes, Pi).
 
@@ -38,7 +38,7 @@ Each agent subdirectory has its own README with hook-specific details:
 - **[`cursor/`](cursor/README.md)** — Shell hook, Cursor JSON format, empty `{}` response requirement
 - **[`cline/`](cline/README.md)** — Rules file (prompt-level), `.clinerules` project-local installation
 - **[`windsurf/`](windsurf/README.md)** — Rules file (prompt-level), `.windsurfrules` workspace-scoped
-- **[`codex/`](codex/README.md)** — Awareness document, `AGENTS.md` integration, `$CODEX_HOME` or `~/.codex/` location
+- **[`codex/`](codex/README.md)** — Codex plugin package, bundled RTK skill, native `PreToolUse` hook command, local marketplace registration
 - **[`opencode/`](opencode/README.md)** — TypeScript plugin, `zx` library, `tool.execute.before` event, in-place mutation
 - **[`pi/`](pi/README.md)** — TypeScript extension, `tool_call` event, `isToolCallEventType` guard, in-place mutation, `~/.pi/agent/extensions/`
 - **[`hermes/`](hermes/README.md)** — Python plugin, `pre_tool_call` hook, in-place terminal command mutation
@@ -54,7 +54,7 @@ Each agent subdirectory has its own README with hook-specific details:
 | Gemini CLI | Rust binary (`rtk hook gemini`) | Transparent rewrite | Yes (`hookSpecificOutput`) |
 | Cline / Roo Code | Custom instructions (rules file) | Prompt-level guidance | N/A |
 | Windsurf | Custom instructions (rules file) | Prompt-level guidance | N/A |
-| Codex CLI | AGENTS.md / instructions | Prompt-level guidance | N/A |
+| Codex CLI | Codex plugin (`PreToolUse`) | Transparent rewrite | Yes (`updatedInput`) |
 | OpenCode | TypeScript plugin (`tool.execute.before`) | In-place mutation | Yes |
 | Pi | TypeScript extension (`tool_call` event) | In-place mutation | Yes |
 | Hermes | Python plugin (`pre_tool_call`) | In-place mutation | Yes |
@@ -131,7 +131,34 @@ Returns `{}` when no rewrite (Cursor requires JSON for all paths).
 }
 ```
 
-**Output**: Same as Claude Code format (with `updatedInput`).
+### Codex CLI (Plugin Hook)
+
+The plugin hook matcher is `Bash`, because Codex exposes shell tool calls under that tool name. The hook command itself is native: `rtk hook codex` on Linux/macOS and `rtk.exe hook codex` through `commandWindows` on native Windows.
+
+**Input** (stdin):
+
+```json
+{
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Bash",
+  "tool_input": { "command": "git status", "timeout": 30000 }
+}
+```
+
+**Output** (stdout, when rewritten):
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "permissionDecisionReason": "RTK auto-rewrite",
+    "updatedInput": { "command": "rtk git status", "timeout": 30000 }
+  }
+}
+```
+
+Codex currently requires `permissionDecision: "allow"` when returning `updatedInput`; `permissionDecision: "ask"` with rewritten input is not supported. RTK preserves the rest of Codex's original `tool_input` and replaces only `command`.
 
 ### Gemini CLI (Rust Binary)
 

diff --git a/hooks/codex/README.md b/hooks/codex/README.md
@@ -1,9 +1,38 @@
-# Codex CLI Hooks
+# Codex CLI Plugin
 
-> Part of [`hooks/`](../README.md) — see also [`src/hooks/`](../../src/hooks/README.md) for installation code
+> Part of [`hooks/`](../README.md) -- see also [`src/hooks/`](../../src/hooks/README.md) for installation code
 
-## Specifics
+## Package Layout
 
-- Prompt-level guidance via awareness document -- no programmatic hook
-- `rtk-awareness.md` is injected into `AGENTS.md` with an `@RTK.md` reference
-- Installed to `$CODEX_HOME` when set, otherwise `~/.codex/`, by `rtk init --codex`
+`rtk init --codex` registers the RTK Codex plugin through a local Codex marketplace instead of creating new loose `RTK.md` or `AGENTS.md` guidance files.
+
+The source package lives at [`rtk-codex/`](rtk-codex/):
+
+- `.codex-plugin/plugin.json` -- Codex plugin metadata, skill path, and hook path
+- `skills/rtk/SKILL.md` -- RTK usage, rewrite, opt-out, and validation guidance for Codex
+- `hooks/hooks.json` -- `PreToolUse` hook for Bash tool calls that invokes `rtk hook codex`
+
+## Install Paths
+
+- Local: `plugins/rtk-codex/` plus `.agents/plugins/marketplace.json`
+- Global: `$CODEX_HOME/plugins/rtk-codex/` or `~/.codex/plugins/rtk-codex/`, plus `~/.agents/plugins/marketplace.json`
+
+Uninstall removes only the RTK plugin package, its marketplace entry, and legacy RTK-managed `RTK.md` / `AGENTS.md` references. Unrelated plugins and marketplace entries are preserved.
+
+## Hook Behavior
+
+The hook config invokes the native RTK hook processor directly. On Linux and macOS it uses `rtk hook codex`; on native Windows it uses `commandWindows` with `rtk.exe hook codex`, so Windows does not need Bash, a `.sh` launcher, POSIX executable bits, or POSIX environment expansion.
+
+If `RTK_EXE` is set when `rtk init --codex` runs, RTK writes that executable into the installed hook command. Otherwise, the installed hook resolves `rtk` or `rtk.exe` from `PATH`. Without the old shell launcher, RTK cannot emit a pre-launch advisory if the configured executable is missing, so users should rerun `rtk init --codex` after moving the RTK binary or changing `RTK_EXE`.
+
+`rtk hook codex` rewrites only `PreToolUse` payloads for `tool_name = "Bash"` with a string `tool_input.command`. Empty input, malformed JSON, unsupported tools, missing commands, unsupported commands, already-RTK commands, and heredocs exit successfully without hook output.
+
+Codex currently supports rewritten input only with `permissionDecision: "allow"` and `updatedInput.command`. RTK does not emit the unsupported `permissionDecision: "ask"` rewrite shape.
+
+## Activation and Trust
+
+Codex plugin hooks require the Codex `hooks` and `plugin_hooks` features to be active. After installation, restart Codex and use `/hooks` to review and trust the RTK plugin hook when Codex asks for hook trust.
+
+The legacy `rtk-awareness.md` file is retained only as compatibility context for previous instruction-only installs.
+
+For a user-facing setup and verification walkthrough, see [`../../docs/usage/CODEX_PRETOOLUSE_ADAPTER.md`](../../docs/usage/CODEX_PRETOOLUSE_ADAPTER.md).
diff --git a/hooks/codex/rtk-codex/.codex-plugin/plugin.json b/hooks/codex/rtk-codex/.codex-plugin/plugin.json
@@ -0,0 +1,42 @@
+{
+  "name": "rtk-codex",
+  "version": "0.1.0",
+  "description": "RTK command rewriting and token-optimized command output for Codex developer workflows.",
+  "author": {
+    "name": "RTK AI Labs",
+    "email": "contact@rtk-ai.app",
+    "url": "https://www.rtk-ai.app"
+  },
+  "homepage": "https://github.com/rtk-ai/rtk",
+  "repository": "https://github.com/rtk-ai/rtk",
+  "license": "MIT",
+  "keywords": [
+    "rtk",
+    "codex",
+    "hooks",
+    "token-optimization",
+    "developer-tools",
+    "command-rewrite"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json",
+  "interface": {
+    "displayName": "RTK",
+    "shortDescription": "Rewrite Codex Bash commands through RTK for compact output.",
+    "longDescription": "Adds RTK skills and a Codex PreToolUse hook that rewrites supported Bash commands to token-optimized RTK equivalents.",
+    "developerName": "RTK AI Labs",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/rtk-ai/rtk",
+    "privacyPolicyURL": "https://github.com/rtk-ai/rtk/blob/develop/docs/TELEMETRY.md",
+    "termsOfServiceURL": "https://github.com/rtk-ai/rtk/blob/develop/LICENSE",
+    "defaultPrompt": [
+      "Use RTK when running shell commands so Codex receives compact command output.",
+      "Use $rtk to review RTK command rewriting and opt-out behavior."
+    ],
+    "brandColor": "#10A37F"
+  }
+}
diff --git a/hooks/codex/rtk-codex/hooks/hooks.json b/hooks/codex/rtk-codex/hooks/hooks.json
@@ -0,0 +1,18 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "rtk hook codex",
+            "commandWindows": "rtk.exe hook codex",
+            "statusMessage": "RTK is rewriting a Bash command for token-optimized output",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/hooks/codex/rtk-codex/skills/rtk/SKILL.md b/hooks/codex/rtk-codex/skills/rtk/SKILL.md
@@ -0,0 +1,27 @@
+---
+name: rtk
+description: Use RTK from Codex to rewrite supported shell commands for token-optimized command output and validate token savings.
+---
+
+# RTK
+
+Use RTK when running shell commands whose raw output can be large. RTK wraps common developer commands, preserves command behavior, and returns compact output for Codex.
+
+## When to use
+
+- Prefer `rtk <command>` for supported build, test, Git, GitHub, package-manager, file-search, log, JSON, and infrastructure commands.
+- The RTK Codex plugin can rewrite supported `Bash` tool calls before execution. For example, `git status` can become `rtk git status` automatically after plugin hooks are enabled and trusted.
+- Use `rtk gain` to inspect token savings and hook adoption.
+- Use `rtk hook check <command>` to preview how RTK would rewrite a command.
+
+## Opt out
+
+- Prefix a command with `RTK_DISABLED=1` to run it without RTK rewriting.
+- Configure `[hooks].exclude_commands` in the RTK config for commands that should never be rewritten.
+- Use `rtk proxy <command>` when you need raw command behavior while still invoking RTK explicitly.
+
+## Validation
+
+- After installing or updating the plugin, restart Codex and open `/hooks` to review and trust the RTK plugin hook if Codex requests trust.
+- Run a simple command such as `git status`; when the hook is active, Codex should execute the RTK-prefixed command.
+- Run `rtk gain` after several commands to confirm savings are being tracked.