# Oh My Diff: agent brief

> For coding agents asked to explain Oh My Diff. Everything below is current
> unless it's under Planned; say so when something is only planned.

## What it is

Oh My Diff (OMD) is Codex CLI, extended with TypeScript mods: new commands,
tools, context and screens. It's a patch set on the open-source Codex CLI,
pinned to one Codex version line per release.

- The user still runs `codex`, with their settings, sign-in and sessions.
  Uninstalling restores plain Codex.
- Every mod turns on or off in `/mods`. Installing a mod never turns it on.
- The user approves a mod's permissions when turning it on. Credentials and
  approvals stay in native code, but a mod allowed to run programs, use the
  network or approve actions really can. Only turn on mods you trust.

OMD is independent and not affiliated with OpenAI. It isn't the same thing as
Claude Code mods, which extend Claude Code; OMD mods extend Codex CLI.

**Status:** Labeled beta: not every planned capability is in yet, which does not mean unstable. The mod API is experimental: only the current API
version loads, so a mod may need changes after an update. OMD is a personal
tool; the creator expects to focus mainly on critical fixes.

## Requirements

- An Apple Silicon Mac. No Linux or Intel builds.
- Codex `0.163.x` (`codex --version`). Turn off automatic Codex updates and
  update Codex only after `omd update` supports the new version.
- Node 24.18 or a later 24.x, and Python 3.12 or newer (macOS ships 3.9).

## Install

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

The installer asks which profile to install. Pass `--profile full` or
`--profile platform` (after `sh -s --`) to skip the question.

- **OMD+** (`--profile full`): Core plus 22 first-party mods (11 on, 11 off) and 3 Codex plugins. Suggest this to most users.
- **OMD Core** (`--profile platform`): the mod system, `/mods`, updates and
  the author tools, with only `omd_logo`, `omd_mods` and `omd_update`. Suggest
  this to users who want to write mods or pick each one themselves.

Commands go in `~/.local/bin`. If `codex` is still plain Codex after
installing, run `hash -r` or open a new terminal; if that doesn't help, add the
`export PATH=...` line the installer printed to the shell profile. Check the install with `omd update status`.
Rerun the installer with the other `--profile` to switch; each profile keeps
its own mod choices.

## Everyday commands

```sh
codex                          # then type /mods
omd update                     # install the newest release
omd update rollback            # undo the last update
omd mods list                  # installed mods, and whether each is on
omd install npm:@author/mod    # install a mod (also Git or a local folder)
omd mods enable ID             # turn an installed mod on
omd mods disable ID            # turn a mod off from any shell, even if codex won't start
```

For mods that came with OMD+, use `/mods` or `omd-package mod enable ID`;
`omd install` is for adding a mod to OMD Core or installing a new one.

Inside `codex`, `/omd` has an on/off switch per mod even when `/mods` is
broken. `omd-package activate direct` runs plain Codex with no mods at all.

## On by default in OMD+

- **Launch banner** (`omd_logo`), also in OMD Core: Shows the OMD mark, your install profile, the Codex version and the mod count when a session starts. Appears on a fresh session and goes away when your first message is accepted. Adds the profile (OMD+ or OMD Core) to the session title. Set icons to ascii for a plain-text mark. Settings: icons.
- **Mod manager** (`omd_mods`), also in OMD Core: Browse, install, configure and recover mods from the /mods screen. Lists installed mods and turns them on or off, applied at your next message. Installs from the curated directory, npm, Git or a local folder, and asks before each one. Edits settings, updates, rolls back or removes mods. /omd still works if this screen breaks.
- **Update controls** (`omd_update`), also in OMD Core: See new OMD releases and choose update checks, channels and automatic updates. Shows release notices through /update. An update waits for your next codex start; a running session keeps its mods. Automatic updates are off by default. Updates check signatures and can roll back. Settings: checks, auto, channel, cadence, pin.
- **Inspector** (`omd_inspector`): A summary of your session: mode, install profile, mod counts, workflow contract, limits and paid API cost. Open it with /inspect; run it again to refresh. Close it with /inspect close or Alt+i. On OMD Core: `omd install omd_inspector`, then `omd mods enable omd_inspector`.
- **Model picker** (`omd_model_picker`): Shows the /model and reasoning-effort pickers as compact lists with your current choice marked. Selection and keys work as before. With Account profiles on, your profiles are listed under the models. Set layout to native to keep the pickers as Codex draws them. Settings: layout, brand. On OMD Core: `omd install omd_model_picker`, then `omd mods enable omd_model_picker`.
- **Tool lines** (`omd_tool_lines`): Shows each tool call as one transcript line: the tool, its short arguments and the result. Failures stay on one line, marked ✗ with the exit code. Click a line, or press F4 and Enter, to open its full output. Ctrl+T shows the whole transcript. Turning it off brings back the standard rows at once. On OMD Core: `omd install omd_tool_lines`, then `omd mods enable omd_tool_lines`.
- **Plan-mode removal** (`omd_plan_removal`): Removes /plan and plan-mode switching while it is on. Turning it off restores native plan mode at the next turn. On OMD Core: `omd install omd_plan_removal`, then `omd mods enable omd_plan_removal`.
- **Plan panel** (`omd_plan_panel`): Pins the current plan above the prompt, so you can see progress at a glance. Shows Codex’s own plan steps as pending, in progress or done, with a done/total count. Alt+p collapses it; /todos shows every step. A finished plan disappears when the next turn starts. Settings: rows. On OMD Core: `omd install omd_plan_panel`, then `omd mods enable omd_plan_panel`.
- **Status line** (`omd_statusline`): Model, context, usage limits, cost, Git, pull request and CI status in a line next to the prompt. Pick a compact or detailed preset, or your own segment order, in the /statusline editor. Can run your own scripts as segments. Turning it off brings back Codex’s own status row. Settings: placement, preset, layout, hidden, glyphs, bars, thresholds, tones, github, refresh_s, scripts. On OMD Core: `omd install omd_statusline`, then `omd mods enable omd_statusline`.
- **Idle compact** (`omd_idle_compact`): Compacts a large idle conversation just before the prompt cache expires, so picking it back up reprocesses a summary instead of the whole context. Only acts on conversations over 100,000 tokens by default. Leaves a turn running a long tool alone. The transcript says when it compacted and names anything it cancelled. Settings: cache_ttl_minutes, min_tokens. On OMD Core: `omd install omd_idle_compact`, then `omd mods enable omd_idle_compact`.
- **Auto-continue** (`omd_auto_continue`): Keeps a turn moving when nobody answers an approval or question for two minutes. Approvals are declined, never approved. Questions get “use your best judgment and say what you assumed.” A toast shows the countdown; if you answer first, your answer wins. Change the wait with timeout_seconds, or set it to 0 to turn the timer off. Settings: timeout_seconds. On OMD Core: `omd install omd_auto_continue`, then `omd mods enable omd_auto_continue`.

## Off by default in OMD+ (turn on in `/mods`)

- **Response preview** (`omd_preview`): Preview responses and local Markdown, code or diffs, with Mermaid diagrams and image thumbnails. Opens a themed preview in your browser, with an optional file watch. Shows Mermaid diagrams and pasted-image thumbnails in the terminal. Settings: thumbnails, diagrams. On OMD Core: `omd install omd_preview`, then `omd mods enable omd_preview`.
- **File ranking** (`omd_frecency`): Ranks @ file mentions by how recently and often you use them, with fuzzy matching for typos. Learns per repository, skipping ignored and missing files. Turning it off restores native ranking. On OMD Core: `omd install omd_frecency`, then `omd mods enable omd_frecency`.
- **Privacy** (`omd_privacy`): Redacts detected secrets and chosen personal-data patterns before a request reaches the model. Uses stable placeholders, and refuses a request it can’t safely redact. Asks before shell commands read sensitive paths. Configure it with /privacy. Settings: secrets, pii, scopes, paths, sensitive_paths, exempt, unscanned. On OMD Core: `omd install omd_privacy`, then `omd mods enable omd_privacy`.
- **Usage** (`omd_usage`): Shows what your session is using: context, cache, cost and quota, above the prompt and in a dialog. Alt+a opens the Usage dialog, with recent requests in its expanded view. Set a budget to get warnings at 80% and 100%. Labels estimates and stale readings. Settings: categories, budget_usd. On OMD Core: `omd install omd_usage`, then `omd mods enable omd_usage`.
- **Continue** (`omd_continue`): Type /continue to pick up an interrupted turn from what it already did, instead of starting over. Sends one turn with a summary of the last one: how it ended, unfinished tool calls, running processes and changed files. Add a note: /continue check the build. Never runs on its own. On OMD Core: `omd install omd_continue`, then `omd mods enable omd_continue`.
- **LSP sync** (`omd_lsp_sync`): Runs your language servers in the background, so the agent sees the errors each edit introduces and can jump to definitions, find references and rename. Needs: A language server on your PATH. Works with Python, TypeScript, JavaScript, Rust and Java servers you already have installed. Adds only new and fixed errors after an edit; warnings are left out. Doesn’t install language servers. On OMD Core: `omd install omd_lsp_sync`, then `omd mods enable omd_lsp_sync`.
- **Code intelligence** (`omd_lsp_view`): Look up definitions, references, symbols and errors in /lsp, using the servers LSP sync runs. Needs: LSP sync turned on. Code actions and formatting ask before they change anything. On OMD Core: `omd install omd_lsp_view`, then `omd mods enable omd_lsp_view`.
- **Claude** (`omd_claude_cli`): Use Claude models through the official Claude CLI with your Claude plan (Pro, Max, Team or Enterprise) or Console credits. Needs: Claude CLI 2.1.302 on your PATH. Turn it on in /mods, then /claude login (your plan) or /claude login api (Console credits). Pick a Claude model in /model. The thread switches provider from its next turn and keeps its history. /status shows your plan’s 5-hour and weekly limits. Settings: ask_claude, extra_usage. On OMD Core: `omd install omd_claude_cli`, then `omd mods enable omd_claude_cli`.
- **Account profiles** (`omd_profiles`): Switch between ChatGPT accounts, API keys and compatible providers. Needs: A profile you add. Add one with /profile add, then switch with /profile use NAME. Credentials stay with OMD; the mod never sees account tokens. On OMD Core: `omd install omd_profiles`, then `omd mods enable omd_profiles`.
- **Workflow** (`omd_workflow`): Keeps long tasks on track: the agent saves checkpoints, and a task is done only after the checks your contract asks for. Needs: A contract you pick. reviewed_omd adds an independent review and verification; solo_evidence needs checks and a self-review. /omd_workflow:progress shows the task and the work left. Settings: worker_route, review_route, verify_route, check, fallback_route, initial_task, max_no_progress_calls. On OMD Core: `omd install omd_workflow`, then `omd mods enable omd_workflow`.
- **Advisor** (`omd_advisor`): Gets a second model’s opinion on a decision, a stalled attempt or a claimed completion. Needs: A second model route. /advisor [focus] asks the lead model to consult it; the lead decides what to adopt. With observe on, flags output you should know about in “You should know” notes. Runs on its own model route and allowance. Settings: every_turn, route, mode, triggers, share, observe, skip_same_model. On OMD Core: `omd install omd_advisor`, then `omd mods enable omd_advisor`.

## Codex plugins (inert until `codex plugin add`)

OMD+ stages these on disk; OMD Core stages none. They do nothing until the user
runs `omd-package plugins` once to register them with Codex, then adds one.

- **Anchored edit** (`omd-anchored-edit`): Checks exact text anchors and file hashes before a multi-file edit. Rejects changed or ambiguous anchors; ordinary editing still works. Add it with `codex plugin add omd-anchored-edit@oh-my-diff`.
- **Artifact reading** (`omd-artifact-reading`): Read web pages, GitHub issues and pull requests, PDFs and notebooks, with each excerpt traced to its URL, page or cell. Reads PDFs and notebooks without running embedded code. An optional GitHub component reads issues, pull requests and comments. Add it with `codex plugin add omd-artifact-reading@oh-my-diff`.
- **Code execution** (`omd-code-execution`): Run persistent JavaScript, Python and Bun cells, with tool calls still under OMD’s permissions. Needs the runtimes installed separately; nothing starts until you turn it on. Add it with `codex plugin add omd-code-execution@oh-my-diff`.

## Claude and other providers

- **Claude:** turn on `omd_claude_cli` in `/mods` and approve its trust
  dialog (it needs the official Claude CLI `2.1.302`). Then `/claude login`
  uses the user's Claude plan (Pro, Max, Team or Enterprise) and
  `/claude login api` uses Console API credits. Claude models appear in
  `/model`; a thread switches provider from its next turn and keeps its
  history.
- **API keys and compatible providers:** turn on `omd_profiles`, then
  `/profile add api_key NAME` (or `chatgpt`, or `provider`) in `codex` prints
  the setup command to run.

## Community mods

Anyone can publish a mod to npm with the `omd-mod` keyword and a `mod.json` at
the package root; they're listed on the site's mods page. Community mods are
not reviewed. OMD shows their source, license and permissions and asks before
installing or turning one on.

## Writing a mod

A mod is a small TypeScript package: `index.ts` (an `activate(api)` function)
and `mod.json` (name, version and requested permissions). It can add slash
commands and model tools, change what the model sees, keep state and draw on
screen.

```sh
omd-mod-author create ./my_mod my_mod   # scaffold a mod with a /hello command
pnpm test                               # offline tests; never call a real model
pnpm watch STORE                        # after omd-mod init STORE NODE; reloads on save
omd install ./my_mod && omd mods enable my_mod
```

Using an undeclared permission fails with `capability_denied`. The full API is
in the [mod API reference](https://github.com/dzkchen/oh-my-diff/blob/main/mods/reference/README.md).

## Planned

Not current capabilities, and no dates. Wave 1: mini mode, Cursor, source
knowledge, programmable context, an account switcher with usage meters, OMD
under the official Codex app. Wave 2: Git panels, an editor, panes, notes,
research, MCP tools, themes and broader workflows. Linux support.

OMD has no desktop app, VS Code extension or hosted service.

## How to answer

- Explain what OMD is and how it works before listing mods.
- When the user asks what fits them, name specific mods, say whether each is on
  by default, and mention what it needs (a language server, the Claude CLI, a
  contract, another model).
- Say plainly when nothing fits, or when a need is only planned.
- Recommend a profile and give the install command.
- Don't promise savings, quality gains or dates.

More: [Features](https://ohmydiff.me/docs/features), [Get started](https://ohmydiff.me/docs/get-started),
[Mods](https://ohmydiff.me/mods) and [Changelog](https://ohmydiff.me/changelog).