omp-matrix-welcome

A Matrix-style start screen for Oh My Pi (omp). It draws full-width digital rain with a block banner and an info panel showing the omp version, the selected model and provider, the working directory, and your recent sessions.

                              ████  ██  ██      ██   ██ ██   ██      ██████  ██████
                             ██  ██ ██  ██      ███ ███  ██ ██       ██   ██   ██
                             ██  ██ ██████ ████ ███████   ███   ████ ██   ██   ██
                             ██  ██ ██  ██ ████ ██ █ ██    ██   ████ ██████    ██
                             ██  ██ ██  ██      ██   ██    ██        ██        ██
                              ████  ██  ██      ██   ██    ██        ██      ██████

                         OMP      17.2.12
                         MODEL    Claude Opus 5  ·  anthropic
                         CWD      ~/code/oh-my-pi
                         RECENT   oh-my-pi  (12m ago)
                                  portfolio-site  (3h ago)
                                  scratch  (2d ago)

                                press any key to continue   8

The rain flows around the panel instead of through it, so the text stays readable. Each column has its own speed and trail length, trails fade from a white head through five shades of green, and banner cells occasionally flicker into a rain glyph.

The screen dismisses itself when the countdown runs out, and immediately on any keypress, when you submit input, or when the agent starts responding.

Requirements

omp 17 or newer. There is no build step and no dependencies: omp loads the TypeScript directly.

Install

From npm:

omp plugin install omp-matrix-welcome

From this repository, which does not require an npm publish:

omp plugin install github:p1x3l4rtd3v/omp-matrix-welcome

Both routes register the package under ~/.omp/plugins and load the entry declared by package.json#omp.extensions. Add --scope project to install into the current project rather than your user profile.

Restart omp afterwards. Extension modules are wired during session startup, so /reload-plugins will not pick up a newly installed extension.

To check the install:

omp plugin list
omp plugin doctor

To remove it:

omp plugin uninstall omp-matrix-welcome

Local development

Point the installer at a working copy instead of a published version:

git clone https://github.com/p1x3l4rtd3v/omp-matrix-welcome.git
omp plugin install ./omp-matrix-welcome

A local path is treated as omp plugin link, so your edits apply on the next omp start without reinstalling.

Turn off the built-in welcome screen

omp only builds its own welcome component when startup.quiet is off. Turn it on and this screen is the only one that renders:

/settings  ->  Interaction  ->  Startup & Updates  ->  Quiet Startup: on

The same setting can live in ~/.omp/agent/config.yml as startup.quiet: true, though the /settings route is safer because omp writes that file itself.

Configuration

Settings live in a JSON file outside the package, so upgrades never overwrite them. The first file found wins:

1. <project>/.omp/matrix-welcome.json
2. ~/.omp/agent/matrix-welcome.json

If PI_CODING_AGENT_DIR is set, or omp runs under --profile, the second path follows that agent directory instead.

Every key is optional. A missing, malformed, or out-of-range value falls back to its default and is reported by /matrix-config, so a typo never breaks startup.

{
  "countdown": 5,
  "charset": "ascii",
  "density": 0.7,
  "bannerText": "MATRIX"
}

Key	Default	Accepted	Meaning
countdown	8	0 to 600	Seconds before auto-dismiss. 0 waits for a keypress.
frameDelayMs	70	16 to 1000	Milliseconds between frames. Lower is faster rain.
height	"full"	"full" or 8 and up	Rows used. "full" fills the terminal.
charset	"katakana"	"katakana", "ascii"	Rain glyphs. Use "ascii" if katakana render double-width.
maxSessions	4	0 to 20	Recent sessions to list. 0 hides the list.
bannerFlicker	0.012	0 to 1	Chance per frame that a banner cell flickers into a glyph.
density	0.9	0 to 1	Fraction of columns carrying a drop.
bannerText	"OH-MY-PI"	1 to 16 chars	Banner text, folded to upper case. A to Z, 0 to 9, space and - . ! ? : ; , ' " ( ) [ ] { } / \ | + = * # @ & % $ _ < > ~ ^ are supported; anything else is skipped and reported by /matrix-config.

Colours are 24-bit ANSI escapes in the C object in index.ts. They are not configurable from the JSON file.

Commands

Command	Effect
/matrix	Replay the welcome screen, reloading the config file first
/matrix-config	Show the config file in use, the effective values, and any warnings

/matrix-config is the fastest way to find out why a setting seems to be ignored. It prints the exact path it read and one warning per field that fell back to its default.

Preview outside omp

npx tsx scripts/preview.ts

This renders the animation straight to your terminal with sample data, reading the same config file the extension uses, so you can tune colours and speed without restarting omp. Press Ctrl+C to quit.

The script lives in scripts/ and guards its side effects behind an entry-point check, so omp never treats it as an extension and importing it does nothing. That guard matters more than it looks: omp's loader imports a candidate module before it decides whether the module exports a valid factory, so a preview script with top-level side effects would take over the terminal and, once its countdown expired, call process.exit on the host session.

Layout behaviour

• Every rendered line is padded to exactly the terminal width, so nothing wraps.
• When the terminal is too narrow for the block banner, or too short for the full panel, it falls back to a single-line banner and drops the session list.
• Below 24 columns it renders nothing rather than producing garbled output.
• Height comes from process.stdout.rows. If the top row looks clipped, set height to a couple of rows below your terminal height.

How it works

• The default export is the extension factory that receives ExtensionAPI.
• The screen mounts through ctx.ui.custom(factory, { overlay: true }), which anchors it bottom-center at full width and gives it keyboard focus.
• Data comes from ctx.model, pi.pi.VERSION, and pi.pi.getRecentSessions(ctx.sessionManager.getSessionDir(), n). Each one is probed defensively, so a change in omp degrades a single field rather than breaking the screen.
• Timers use ctx.setInterval and ctx.clearTimer. Those get the same isolation as handler dispatch, so a throw inside a frame cannot tear down the session, and they are cleared automatically on session_shutdown.
• Host types are described structurally in index.ts, which is why the package needs no dependency on omp's own types.

Files

Path	Purpose
index.ts	Extension factory, rain simulation, and renderer
config.ts	Defaults, config file lookup, and validation
scripts/preview.ts	Standalone preview, inert when imported

Troubleshooting

The screen does not appear. Check that the plugin is enabled with omp plugin list, and that you restarted omp instead of running /reload-plugins. In any non-interactive context, such as --print, RPC mode, or a subagent, ctx.hasUI is false and the screen is skipped deliberately.

Two welcome screens appear. Set startup.quiet: true as described above, and check that no other welcome extension is installed.

Settings appear to be ignored. Run /matrix-config.

Katakana glyphs look too wide or leave gaps. Set "charset": "ascii".

Publishing

npm publish --access public

files ships index.ts, config.ts, scripts/, the README and the licence, which is six files in total. omp plugin install validates the manifest at install time: every entry in omp.extensions must resolve on disk and import to a factory function, and the install is rolled back if it does not.

License

MIT