Add your mod
o-mods is open source, and every mod here started as an idea someone wrote down. You do not need a big plan. A small, useful mod is a good mod. Every change goes through one issue and one review, so the collection stays tidy.
How it works
- Open an issue. Tell us what your mod does and why it helps.
- Send a pull request. Add your mod folder with a README and a demo.
- Get a review. A maintainer reads it, may ask for changes, and then merges it.
The details
o-mods is a registry of mods for Claude Code: panes, sidebars, bands, status lines and hooks that run inside your sessions. New mods and improvements to existing ones are welcome.
How changes get in
- Open an issue first. A mod idea for a new mod, a bug for something broken, or a blank issue for anything else. Agree on the approach there before you write code.
- Fork, branch, and open a pull request that says
Closes #<issue>in its description. A check fails until it does. - CI runs the registry check and builds the site.
- The maintainer reviews it. Nothing reaches
mainwithout that approval; there are no direct pushes.
Ways to help
- Build a new mod. Start with a mod idea issue.
- Improve a mod. Fix a bug, add an option, support another terminal or forge. Keep the mod's existing style.
- Report a bug. Use the bug template and include
claude --version. - Improve the site. The showcase lives in
site/(VitePress).
Add a mod
Create
mods/<mod>/. The folder name is the mod's install name: lowercase, words joined by-.mods/<mod>/ ├── .claude-plugin/plugin.json # name, version, description, author, keywords ├── hooks/ # hooks.json and the hooks module ├── commands/ # slash commands, if any ├── types/ # the mod's state contract ├── tests/ ├── demo.tape, demo.json # the recorded demo (see "Record a demo") ├── preview.gif, preview.mp4 # written by demo/record.sh └── README.mdFill in
plugin.json. The site reads it:json{ "name": "<mod>", "version": "0.1.0", "description": "One sentence: what the user sees and when.", "author": { "name": "<your GitHub username>", "url": "https://github.com/<you>" }, "keywords": ["fun", "statusline"] }authoris how you get credit on the site.keywordsbecome the mod's tags.Add the mod to the
pluginslist in.claude-plugin/marketplace.json:json{ "name": "<mod>", "source": "./mods/<mod>", "description": "<one line>", "category": "fun" }categoryis where the mod shows on the site:fun(toys and personality),status(shows where you stand: limits, CI, usage, role) orworkflow(helps you get work done).Add the mod to
README.md: a cell in the section it fits, with its name linked tomods/<mod>, one or two sentences, and itspreview.gif.While a mod is still in testing, skip steps 3 and 4 and add an empty
mods/<mod>/.unlistedfile instead: the mod stays in the repository but out of the marketplace, the README and the site.Run the checks:
node scripts/check-registry.mjs claude plugin validate . claude plugin validate mods/<mod> claude plugin test mods/<mod>Open a pull request with
Closes #<issue>in its description. CI runs the registry check and builds the site, and the maintainer reviews it.
Commit messages
Commits and pull request titles follow Conventional Commits: type(scope): subject. A check fails a pull request until they do.
- type:
feat(a new mod or feature),fix,docs,style,refactor,perf,test,build,ci,choreorrevert. - scope: optional; the mod's name (
heat), orsite,demo,readme,registry. - subject: lowercase, imperative, no full stop, the whole line 72 characters at most. Add
!before the colon for a breaking change.
feat(heat): add a cooldown option
fix(pr-status): read checks from GitLab merge requests
docs(readme): add the snippets demoWrite the README
Each mod's README.md becomes its page on the site, as is. Follow the shape the existing mods use:
# <mod>and one paragraph on what it does.- A preview right after the first paragraph. A fenced code block that draws what the mod looks like in the terminal (see
mods/heatormods/usage-bar). The site plays the recorded demo on the mod's card and page; this drawing is the fallback until one exists. - Features or how it works, commands, requirements, settings.
## Installwithclaude plugin marketplace add omeerdvrn/o-modsandclaude plugin install <mod>@o-mods.
Links to files inside the mod (hooks/register.tsx) are turned into GitHub links on the site.
Develop a mod
Add your clone as a local marketplace and install from it. Claude Code then reads each mod straight from its folder:
claude plugin marketplace add /path/to/o-mods
claude plugin install <mod>@o-mods --scope userAfter you edit a mod, run /reload-plugins in any open session. To run one mod in one session only, with reload on save:
claude --plugin-dir mods/<mod>The mod API is in early access. Mods need Claude Code 2.1.29x or later.
Record a demo
Every mod shows itself running in the Claude Code CLI: a preview.gif, and a preview.mp4 the site plays. Demos are scripted and recorded against a local mock of the Claude API, so they need no account and cost nothing:
brew install vhs gifsicle ffmpeg
demo/record.sh <mod>Mods that draw pictures also need kitty (brew install --cask kitty).
Add mods/<mod>/demo.tape (what is typed) and mods/<mod>/demo.json (what Claude answers). Copy them from a mod close to yours. demo/README.md covers the format, isolation, fake services, and what to check before you open a pull request.
Preview the site
cd site
npm install
npm run devThe site rebuilds mod pages from mods/*/README.md each time it starts.
Rules
- No secrets, tokens, personal data, or employer or client names in code, tests, READMEs or screenshots. Use
acme,example.comandENG-123in examples. - Mods must not send data off the machine unless that is their purpose and the README says so up front.
- Bundled sounds, images and fonts must be yours or under a license that allows redistribution. Name the source in the README.
- By contributing you agree your work is released under the MIT License.