Create Plugin

Build an oh-my-claude statusline plugin — from idea to working output in one pass.

Workflow

Clarify the plugin's purpose — ask what it should display, when to hide, and any config the user wants. See PATTERNS.md for data fields and common patterns.
Choose plugin type — JS plugin (default, in-process, fast) or script plugin (any language, runs as subprocess). Use JS unless the user specifies a language or the task needs external tools. See PATTERNS.md.

Scaffold the plugin — run

omc create <name>

(or

omc create <name> --script --lang=python|bash

). This creates the directory structure at

~/.claude/oh-my-claude/plugins/<name>/

Implement render logic — edit the generated
```
plugin.js
```
(or
```
plugin
```
script). Follow the contract in PATTERNS.md. Always use optional chaining. Always return null when data is missing.
Set default config — add any configurable values to
```
meta.defaultConfig
```
(JS) or
```
plugin.json
```
(script). Use concrete defaults, not empty strings.
Test the plugin — run
```
omc test <name>
```
. Verify it returns
```
{ text, style }
```
with mock data and returns
```
null
```
with empty data.
Wire it up — run
```
omc add <name>
```
(with
```
--line N
```
and
```
--left
```
if needed). Run
```
omc show
```
to verify placement.
Verify end-to-end — run
```
omc doctor
```
to confirm no errors. Run
```
omc show
```
to see the live preview.

Before delivering, verify ALL:

```
meta.name
```
matches the directory name
```
meta.description
```
is a single clear sentence
```
render()
```
uses optional chaining for every data access (
```
data?.field?.subfield
```
)
```
render()
```
returns
```
null
```
when required data is missing (never crashes)
```
omc test <name>
```
succeeds — shows text with mock data, returns null with empty data
```
omc doctor
```
reports no errors for this plugin
Shell commands (if any) use
```
cachedExec
```
from
```
src/cache.js
```
, never raw
```
execSync
```
Config keys have sensible defaults in
```
defaultConfig
```
(no empty strings or nulls for required values)
Plugin text is short — fits in a statusline segment (under ~30 chars typical)
```
omc show
```
confirms the plugin appears where the user wants it

Hard rules. Never violate these.

Never crash the statusline. Every data access uses optional chaining. Every render returns
```
{ text, style }
```
or
```
null
```
. No exceptions, no throws. A plugin that crashes breaks the entire statusbar for the user.
Null means hide. Return
```
null
```
when data is unavailable. Never return empty strings, placeholder text, or fallback values that clutter the bar.
Cache all shell commands. Use
```
cachedExec(key, command, ttlMs)
```
from
```
src/cache.js
```
. Raw
```
execSync
```
in render blocks the entire statusline pipeline.
Test before wiring. Always run
```
omc test <name>
```
before
```
omc add <name>
```
. A broken plugin silently disappears — testing catches errors the statusline would swallow.
Keep text short. Statusline segments share a single terminal line. Aim for under 30 characters. Use abbreviations, symbols, and rounding (e.g.
```
42%
```
not
```
42.53%
```
,
```
$2.41
```
not
```
$2.4100
```
).
Config has real defaults. Every key in
```
defaultConfig
```
must have a usable value. Users override config — they don't fill in required blanks.
Match name to directory.
```
meta.name
```
must exactly match the plugin directory name. Mismatches cause the plugin to silently not load.

File	Contents
PATTERNS.md	Data fields, plugin templates, cachedExec usage, script plugin format, style tokens, common patterns