Oh My Diff

Keep Codex. Mod everything.
Codex CLI with a host for TypeScript mods: add commands, tools, context and screens without leaving codex.

Install Oh My Diff

Website · Docs · Mods · Changelog

You still run codex, with your settings, sign-in and sessions, and you can go back to plain Codex at any time with nothing to migrate. OMD is in beta and runs only on Apple Silicon macOS.

What a mod can do

A mod is a small TypeScript program. It can add a slash command, give the model a new tool, add context to a request, draw a status line, panel or dialog, or react when the agent runs a tool. Before a mod runs, OMD shows its source, license and the permissions it asks for. You control which mods run, subject to any administrator policy.

How OMD works · Trust and permissions · Write your first mod

Included mods

OMD+ comes with these, among others:

• Grouped tool lines: adjacent shell commands collapse into one row; open it for the full output.
• Status line: configurable, edited with /statusline.
• Privacy: redacts text that matches its secret and personal-data rules in requests sent to the model. Web search, transcripts and logs aren't covered (off; turn on in /mods).
• Usage: context, cache, cost and quota by request (off; turn on in /mods).
• Auto-continue: off until you turn it on; an unanswered approval or question no longer stalls the turn.

Experimental mods add other providers, a workspace dock, /undo and language-server feedback. The included mods page lists every one and says which are on by default and which are experimental.

Works with

Codex CLI   Claude (experimental)   Cursor (experimental)   OpenAI and Anthropic API keys (experimental)   T3 Code (experimental)   + any app that runs codex app-server

Install

You need an Apple Silicon Mac, Codex 0.167 (npm install -g @openai/codex@0.167, which needs Node, or Homebrew's Codex while it's on 0.167.x) and Python 3.12 or later. The install guide lists every requirement.

OMD+ (recommended)

The mod host plus the included mods.

curl --proto '=https' --tlsv1.2 -fsSL https://github.com/dzkchen/oh-my-diff/releases/latest/download/install.sh | sh -s -- --profile full

OMD Core

Only the mod host: the /mods screen, update notices and the OMD logo. Codex otherwise looks and behaves as it always has. Choose it to add only mods you pick yourself, or to write your own.

curl --proto '=https' --tlsv1.2 -fsSL https://github.com/dzkchen/oh-my-diff/releases/latest/download/install.sh | sh -s -- --profile platform

You can switch later by running the other command.

First run

codex

Run it in any folder. Codex asks you to sign in if you haven't before, then shows the OMD logo. Type /mods to see which mods are on and to turn others on or off; Esc closes it. Outside codex, run omd for a short summary of the commands that install, update and manage mods. If codex still starts plain Codex, see troubleshooting.

Status

OMD is in beta; expect bugs. Mod API 1.0.0 is stable, while entries marked experimental can change (support policy). Experimental mods need more testing and fixes; contributions are welcome.

Community and support

• Missing a capability? The API is young: request it. New features are best written as mods.
• Bugs and docs problems: open an issue, or see troubleshooting first.
• Security: report it privately, not in a public issue.
• Core contributor: open an issue and say so.
• Show support: star the repo to follow along.

Developing

See CONTRIBUTING.md to run OMD locally or send a change, the mod API reference for the full API, and the agent mod guide for coding agents writing mods.

OMD is upstream Codex plus one patch pinned to a single Codex release. The patch adds a mod host that has no features of its own; every feature is a TypeScript mod running in its own sandboxed runner process.

flowchart LR
  subgraph codex["codex process (Codex + OMD patch)"]
    direction TB
    upstream["Codex CLI<br/>threads, turns, tools, TUI"]
    ext["codex-omd-extension<br/>runtime/native"]
    host["codex-omd mod host<br/>runtime/omd"]
    upstream <--> ext <--> host
  end
  subgraph runners["omd-runner processes (embedded V8, macOS sandbox)"]
    direction TB
    a["mod package A"]
    b["mod package B"]
  end
  host <-->|"callbacks / host calls<br/>checked against granted permissions"| a
  host <--> b
  mods["TypeScript mods<br/>mods/first-party, your own"] -. loaded into .-> runners

Loading

How OMD works explains the design and contributing to the patched runtime covers changing the Rust.

License

Oh My Diff is free and open source under the MIT License (Codex patch notice, third-party notices). It is not affiliated with or endorsed by OpenAI.