OpenMods

Mods for open-source harnesses. A mod changes a harness's own source code: a new command, a different layout, a game to play while it works. OpenMods builds the harness with the mods you pick and puts that build on your PATH, while your stock install stays as it is.

Supported: OpenCode, Codex CLI and fx, on macOS and Linux.

Install

curl -fsSL https://openmods.dev/install.sh | sh

This needs git, curl and tar. OpenMods keeps its files in ~/.openmods: the program, the mods list (a clone of this repository, pulled by list, info, install and update, which never changes the program), and the Bun the CLI runs on. Only openmods update, or running the installer again, updates OpenMods itself, and only to a release (a vX.Y.Z tag), never to code merged since; update says from which version to which. Outside that folder, it adds a PATH line, marked # openmods, to your shell's startup file so ~/.openmods/bin comes first; for bash on Linux, also to the file a login shell reads. In ~/.openmods/bin it puts a small launcher for each harness you have, which runs your stock one until you install a mod.

Use

openmods list                                              # what is published
openmods info shouryamaanjain/space-invaders               # what a mod changes, file by file
openmods install shouryamaanjain/space-invaders --codex    # build it into Codex, and switch to that build
codex                                                      # the modded build

openmods off                                               # back to your stock build
openmods on                                                # and to the modded one
openmods status                                            # which one runs right now
openmods update                                            # move to newer releases and mod updates
openmods uninstall shouryamaanjain/space-invaders --codex

A mod is named <owner>/<mod> and can support several harnesses; add --opencode or --codex to pick one, or the CLI asks. You can install several mods on one harness. If two of them change the same lines, the CLI refuses before it builds and names the lines.

Every command is documented at openmods.dev/cli and in openmods help <command>.

Building

Mods are built from source on your machine, nothing is prebuilt. A progress line shows each step and how long it has run, and the time left once it can tell. Later builds reuse what they can.

• OpenCode needs nothing more: the CLI fetches the exact Bun version each release pins. The first build takes a minute or two, and OpenMods keeps about 2 GB of OpenCode's source and packages in ~/.openmods so later builds are quick.
• Codex CLI is a large Rust project: the first build takes 15 to 45 minutes depending on the machine (about 20 on a 4-core Linux machine, 30 to 40 on a small Mac), later ones far less, and it keeps a few GB of build cache. Its Rust crates download to Cargo's usual ~/.cargo. It needs Rust, a C compiler and Python 3.11+, plus pkg-config and the libcap and OpenSSL headers on Linux. If any are missing, the CLI says which, with one command that installs them all when your package manager has them. OpenMods builds Codex with less optimization than its official releases, which roughly halves the build time.
• fx is a Zig program: a couple of minutes, and up to about 3 GB of memory while it compiles. The CLI fetches the exact Zig version each release pins, from Zig's community mirrors or ziglang.org, checks it against the sha256 in ziglang.org's download index, and keeps it in ~/.openmods/toolchains; on Linux, unpacking it needs xz. Zig's build cache goes in ~/.openmods/cache/zig. On Linux it is built as fx's own releases are, as a static binary.

Updates

When you start codex or opencode at a terminal, the launcher starts your build at once and, in the background, refreshes the mods list. That look never updates OpenMods or your build; it may refresh its own launchers, and it stops a mod removed from OpenMods. The next time you start it, it tells you what it found: a newer release every mod you have switched on supports, or a fix for one of your mods, with the question "Update now?"; or a newer release some mods hold back, said once. A no is final for that offer, and nothing is rebuilt without a yes. openmods update does the same any time, and OPENMODS_NO_CHECK=1 turns the background look off. Every openmods command you run, other than asking for help, also gets the current list of mods removed from OpenMods, so a removed mod stops running.

A build's version names what went into it: codex --version prints something like 0.157.0+space-invaders-1.

How it works

A mod is a series of git patches against a tagged release of a harness:

mods/<owner>/<mod>/
  mod.json              name, description, license
  README.md             what it does, and a Permissions section
  opencode/
    support.json        the releases it supports
    v2.0.18/0001-….patch
  codex/
    support.json
    rust-v0.157.0/0001-….patch

openmods install clones the harness, checks out a release every one of your mods supports, applies the patches with git am -3, and builds it with the harness's own build commands and the toolchain that release pins. The result goes in ~/.openmods/harnesses/<id>/builds, and ~/.openmods/bin/<binary> is a small launcher that runs it, or your stock build after openmods off.

OpenMods never changes a harness's code: a modded build is the release plus your mods, and --version shows the release as stock does. Where a modded build and your stock one would get in each other's way, the launcher passes the harness's own switches when it starts it, for a single run, never in your config. For Codex: --no-daemon, so modded Codex does not share stock Codex's background server and every mod, deep changes to tools included, runs in the modded session; codex agents, --remote, app-server, remote-control and queue, which use or set up that shared server, start your stock Codex, so the server is always stock's; so do codex update and the session commands archive, unarchive and delete (when OpenMods can tell that it was set up from a modded build, because it carries an older OpenMods version stamp or is a copy of your current modded build, openmods status and update say so and give Codex's own command to reset it); -c check_for_update_on_startup=false, since Codex's own update notice would update stock, not the modded build; and -c feedback.enabled=false, so /feedback does not send logs from a build OpenAI did not ship. For OpenCode, the launcher turns off OpenCode's self-update, and the build uses its own channel, which gives it its own sessions and background server. When your stock OpenCode is the very release your mods are built on (the launcher reads its version from its program, never running it), the two share your session history: modded OpenCode opens stock's database (OPENCODE_DISABLE_CHANNEL_DB=1) and runs with --standalone, a private server of its own, so stock's background service always runs stock code and never picks up a modded session's turns; opencode service, pair, mcp, plugin and debug, which use that service, start your stock OpenCode. Mods that change OpenCode's database tables or migrations keep their own sessions, and so does a modded build next to a stock OpenCode of another release, so neither leaves data the other cannot read. Sessions made while they were apart stay on each side. For fx: FX_AUTO_UPGRADE=0, since fx otherwise replaces its own program with the newest stock release; fx upgrade, which does that whatever the setting, starts your stock fx; and only a program that is Vercel's fx counts as your stock fx, not the unrelated fx JSON viewer that has the same name. Stock and modded fx share everything in ~/.fx (settings, logins, sessions, skills) and the background process that runs fx's shell commands: whichever fx starts it serves both while it runs, and fx has no switch to keep them apart, so a mod that changes how fx runs commands can serve your stock fx's commands too, and the other way around. Report problems with a modded build to OpenMods or the mod's author, not the upstream project, after checking whether they also happen with .

When a harness publishes a release, a scheduled job applies and typechecks every mod against it. Mods that still apply and typecheck get a version for the new release automatically. For a mod that no longer does, the job opens an issue for its maintainers with the error. If the release changed how the harness builds, the mods wait until a maintainer has built it.

Patches rather than forks: a patch series is small enough to read and review, and it names the release it applies to. It also stacks with other mods, where two forks can't be combined.

Making a mod

git clone https://github.com/anomalyco/opencode && cd opencode
git checkout v2.0.18                      # a release, not the default branch
# change anything, and commit
openmods dev                              # `opencode` now runs this clone from source
openmods install .                        # build it as users will get it
openmods pack . --name my-mod --registry ../openmods    # into your fork of this repo

Then open a pull request. CONTRIBUTING.md walks through it, including Codex and what review checks.

If you write mods with a coding agent, give it the openmods skill (skills/openmods): the workflow, where each harness keeps its commands, panels, keys and tools, how to test a mod, and how to publish and update it. It works in Claude Code, Codex, OpenCode and fx:

npx skills add shouryamaanjain/openmods --skill openmods -g

Or copy skills/openmods into ~/.agents/skills/ (Codex, OpenCode and fx read it there) and link it into ~/.claude/skills/ for Claude Code.

Security

A mod is code that runs with your permissions, like anything you build from source. Read it before you install it: openmods info lists every file a mod touches, each mod's page on openmods.dev shows the diff, and its README has a Permissions section saying what it does with the network, files, commands and the agent's instructions. Because your machine builds from the release plus those patches, what you read is what you run. SECURITY.md explains how mods are reviewed and how to report a problem.

Uninstalling OpenMods

Delete ~/.openmods and the # openmods lines in your shell's startup files. Your stock harnesses were never changed.

Development

bun install
bun run typecheck && bun run validate && bun run test
bun run site                              # build openmods.dev into site/

License

MIT. Each mod has its own license in its mod.json, and each harness keeps its upstream license.