From 7edf5d40d8e378544a569c877c5e486f5c99dc45 Mon Sep 17 00:00:00 2001
From: 0xGunDone <125687774+0xGunDone@users.noreply.github.com>
Date: Sat, 21 Mar 2026 23:46:12 +0300
Subject: [PATCH] docs: surface Codex CLI support

---
 INSTALL.md                   | 66 ++++++++++++++++++++++++++++++++++++
 README.md                    | 37 ++++++++++++++++++++
 hooks/rtk-awareness-codex.md | 10 +++++-
 3 files changed, 112 insertions(+), 1 deletion(-)

diff --git a/INSTALL.md b/INSTALL.md
index 98457d09..860dc502 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -87,6 +87,16 @@ rtk gain  # MUST show token savings, not "command not found"
             No hook, no global effect
 ```
 
+**Using Codex CLI instead?**
+
+```bash
+rtk init --codex        # Local AGENTS.md + RTK.md
+rtk init -g --codex     # ~/.codex/AGENTS.md + ~/.codex/RTK.md
+rtk init --show --codex # Verify Codex setup
+```
+
+Codex support is awareness-based: RTK adds concise instructions, and Codex should prefer explicit `rtk ...` commands. It does **not** patch a hook registry like Claude Code.
+
 ### Recommended: Global Hook-First Setup
 
 **Best for: All projects, automatic RTK usage**
@@ -148,6 +158,34 @@ rtk init  # Creates ./CLAUDE.md with full RTK instructions (137 lines)
 
 **Token savings**: Instructions loaded only for this project
 
+### Codex CLI Setup
+
+**Best for: Codex CLI users who want RTK awareness without Claude hook patching**
+
+```bash
+# Global Codex setup
+rtk init -g --codex
+# → Creates ~/.codex/RTK.md
+# → Adds @RTK.md reference to ~/.codex/AGENTS.md
+
+# Project-local Codex setup
+rtk init --codex
+# → Creates ./RTK.md
+# → Adds @RTK.md reference to ./AGENTS.md
+
+# Verify
+rtk init --show --codex
+```
+
+**Usage pattern in Codex**:
+```bash
+rtk git status
+rtk git diff
+rtk read file.rs
+rtk grep "pattern" .
+rtk cargo test
+```
+
 ### Upgrading from Previous Version
 
 #### From old 137-line CLAUDE.md injection (pre-0.22)
@@ -210,6 +248,24 @@ rtk init -g --no-patch
 # Restart Claude Code
 ```
 
+### Codex CLI User
+```bash
+# 1. Install RTK
+brew install rtk
+rtk gain  # Verify (must show token stats)
+
+# 2. Setup for Codex
+rtk init -g --codex
+
+# 3. Verify
+rtk init --show --codex
+
+# 4. In Codex sessions, prefer explicit rtk commands
+rtk git status
+rtk read README.md
+rtk cargo test
+```
+
 ### Temporary Trial
 ```bash
 # Install hook
@@ -255,6 +311,16 @@ rtk init -g --uninstall
 # Restart Claude Code after uninstall
 ```
 
+**Codex CLI global uninstall:**
+
+```bash
+rtk init -g --codex --uninstall
+
+# What gets removed:
+#   - Context: ~/.codex/RTK.md
+#   - Reference: @RTK.md line from ~/.codex/AGENTS.md
+```
+
 **For Local Projects**: Manually remove RTK block from `./CLAUDE.md`
 
 ### Binary Removal
diff --git a/README.md b/README.md
index d818e2af..f6e4b570 100644
--- a/README.md
+++ b/README.md
@@ -104,6 +104,11 @@ rtk init --global
 # Follow instructions to register in ~/.claude/settings.json
 # Claude Code only by default (use --opencode for OpenCode, --gemini for Gemini CLI)
 
+# Codex CLI (awareness mode, no hook patching)
+rtk init -g --codex
+# Creates ~/.codex/RTK.md and adds @RTK.md to ~/.codex/AGENTS.md
+# Then prefer explicit rtk commands such as: rtk git status
+
 # 2. Restart Claude Code, then test
 git status  # Automatically rewritten to rtk git status
 ```
@@ -330,6 +335,38 @@ mkdir -p ~/.config/opencode/plugins
 cp hooks/opencode-rtk.ts ~/.config/opencode/plugins/rtk.ts
 ```
 
+## Codex CLI Support (Global or Local)
+
+RTK supports Codex CLI through lightweight awareness files rather than hook-based command rewriting.
+
+**Install for Codex CLI:**
+```bash
+rtk init --codex        # Configure local AGENTS.md + RTK.md
+rtk init -g --codex     # Configure ~/.codex/AGENTS.md + ~/.codex/RTK.md
+rtk init --show --codex # Verify current Codex configuration
+```
+
+**What it creates:**
+- `RTK.md` with concise Codex-specific RTK guidance
+- `@RTK.md` reference in `AGENTS.md`
+
+**How to use it in Codex:**
+```bash
+rtk git status
+rtk git diff
+rtk read src/main.rs
+rtk grep "pattern" .
+rtk cargo test
+rtk pytest
+```
+
+**Behavior note:** unlike Claude Code, Gemini CLI, and OpenCode, Codex support is instruction-based today. Use explicit `rtk ...` commands for the highest reliability.
+
+**Uninstall:**
+```bash
+rtk init -g --codex --uninstall
+```
+
 ### Commands Rewritten
 
 | Raw Command | Rewritten To |
diff --git a/hooks/rtk-awareness-codex.md b/hooks/rtk-awareness-codex.md
index 7ae285e1..558f3b79 100644
--- a/hooks/rtk-awareness-codex.md
+++ b/hooks/rtk-awareness-codex.md
@@ -1,15 +1,22 @@
 # RTK - Rust Token Killer (Codex CLI)
 
-**Usage**: Token-optimized CLI proxy for shell commands.
+**Usage**: Token-optimized CLI proxy for shell-heavy commands in Codex.
+
+Prefer explicit `rtk ...` commands for noisy shell output.
 
 ## Rule
 
 Always prefix shell commands with `rtk`.
 
+Use raw shell commands only when you need exact unfiltered output, exact line slices, or exact patch hunks.
+
 Examples:
 
 ```bash
 rtk git status
+rtk git diff
+rtk read src/main.rs
+rtk grep "pattern" .
 rtk cargo test
 rtk npm run build
 rtk pytest -q
@@ -28,5 +35,6 @@ rtk proxy <cmd>     # Run raw command without filtering
 ```bash
 rtk --version
 rtk gain
+rtk init --show --codex
 which rtk
 ```