From a6559e461b30a163de9443aab6ac1de885778229 Mon Sep 17 00:00:00 2001
From: Munawwar <munawwarfiroz@hotmail.com>
Date: Sat, 14 Feb 2026 18:33:07 +0400
Subject: [PATCH] Add fork feature summary to README

Document what this fork adds over the official OpenAI Codex CLI,
including the Native SDK, Agents framework integration, Reverie
enhancements, Agents Suite, LSP integration, and more.
---
 README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/README.md b/README.md
index ae5073bea..b64f7d38c 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,81 @@ If you want Codex in your code editor (VS Code, Cursor, Windsurf), <a href="http
 
 ---
 
+## What this fork adds over the official Codex CLI
+
+This is a fork of the [official OpenAI Codex CLI](https://github.com/openai/codex) by [ScriptedAlchemy](https://github.com/ScriptedAlchemy) (Zack Jackson, creator of Module Federation). It transforms Codex from a standalone terminal tool into an **embeddable, programmable agent platform**. The fork is actively maintained and regularly syncs with upstream.
+
+### 1. Native Node.js SDK with Rust NAPI Bindings (`sdk/native/`)
+
+**Package**: `@codex-native/sdk`
+
+Embeds the Codex Rust runtime directly into Node.js via [napi-rs](https://napi.rs/) instead of spawning child processes. Key capabilities:
+
+- **Thread management** -- `startThread()`, `run()`, `runStreamed()`, `resumeThread()`, `fork()`
+- **Custom tool registration** -- Register JS functions as tools the AI can invoke, including overriding built-in tools (`shell`, `apply_patch`, `read_file`, etc.)
+- **Tool interceptors** -- Wrap built-in tools with pre/post-processing logic
+- **Structured output** -- JSON schema validation for model responses
+- **Streaming** -- Async generator-based event streaming powered by the Tokio runtime
+- **Programmatic code review** -- `codex.review()` API for diff review against branches, commits, or custom prompts
+- **Conversation forking** -- Branch from earlier messages to explore alternate paths
+- **Skills system** -- Register named skills programmatically (no SKILL.md files needed)
+- **Approval callbacks** -- JavaScript-side approval gating for sensitive operations
+- **Cross-platform** -- macOS (arm64/x64), Linux (x64/arm64, glibc/musl), Windows (x64/arm64)
+
+### 2. OpenAI Agents Framework Integration
+
+A full `ModelProvider` implementation (`CodexProvider`) for the [OpenAI Agents JS SDK](https://github.com/openai/openai-agents-js). This allows using the Codex runtime as the execution backend for the OpenAI Agents framework:
+
+```typescript
+import { CodexProvider } from "@codex-native/sdk";
+import { Agent, run } from "@openai/agents";
+
+const provider = new CodexProvider({ defaultModel: "gpt-5.1-codex" });
+const agent = new Agent({
+  name: "CodeAssistant",
+  model: provider.getModel(),
+  instructions: "Fix the failing tests",
+});
+const result = await run(agent, "Investigate the CI failure");
+```
+
+Features include buffered and streamed model responses, thread continuity, tool execution inside the Codex sandbox, and a tool registry for mapping Codex tools to the Agents framework.
+
+### 3. GitHub Copilot / OpenCode Model Provider
+
+Allows authenticating via GitHub Copilot tokens to use models (including GPT-5) through the Copilot API, without requiring a direct OpenAI API key.
+
+### 4. Enhanced Reverie (Conversation History Search)
+
+Major improvements to the Reverie system -- Codex's semantic memory for past conversations:
+
+- **Multi-vector embeddings** with max-pooling for per-message precision
+- **Query expansion** with 60+ technical synonym mappings
+- **Hybrid scoring** -- 70% semantic similarity + 30% keyword relevance
+- **Embedding-based quality filtering** replacing hardcoded pattern matching
+- **Multi-stage pipeline** -- Search → Quality Filter → Score Split → LLM Grade → Deduplicate
+- **Multi-level search** -- Project-wide, branch-specific, and file-specific tiers
+- **+35% improvement** in average search relevance (58% → 78.5%)
+
+### 5. Codex Agents Suite (`codex-agents-suite/`)
+
+A higher-level multi-agent workflow toolkit providing four turnkey workflows:
+
+- **PR Review & CI Orchestrator** -- End-to-end review, CI triage, reverie hints, optional auto-fix
+- **Diff Reviewer** -- Structured diff analysis with per-file risk scoring and LSP diagnostics
+- **Merge Conflict Solver** -- Autonomous merge with coordinator/worker/reviewer pipeline and supervisor approval
+- **CI Auto-Fix Orchestrator** -- Iterative fix-and-rerun loop with bounded concurrency
+
+### 6. LSP Integration (`sdk/native/src/lsp/`)
+
+An LSP client that collects diagnostics (type errors, lint warnings) from language servers (TypeScript, Pyright, etc.) during agent execution, enriching tool outputs with compiler/linter data.
+
+### 7. PR Worktree Automation
+
+Scripts for automated PR review workflows using git worktrees.
+
+---
+
 ## Quickstart
 
 ### Installing and running Codex CLI