omp-startup

A customizable welcome/startup dashboard for Oh My Pi (omp) and upstream Pi — the startup.nvim / snacks.dashboard of coding agents.

Core contract: inert until configured. With no dashboard.json anywhere, both hosts behave exactly as without this plugin. Once you configure anything, only what you configured changes — every other element keeps its native look, because the defaults replicate omp's built-in welcome box. The plugin never writes harness settings.

Install

From npm (recommended — both hosts ship native installers):

omp plugin install omp-startup      # Oh My Pi, user-level (~/.omp/plugins)
pi install npm:omp-startup          # upstream Pi, user-level; add -l for project-local

Rerun the same command to update to the latest published version. omp plugin uninstall omp-startup / pi remove omp-startup removes it.

A scoped mirror is also published to GitHub Packages as @zhulinchng/omp-startup on every release (installing from that registry requires an npm token with read:packages).

Manual alternative from a source checkout:

# symlink tracks your checkout:
ln -s /path/to/omp-startup ~/.omp/agent/extensions/omp-startup   # omp, user-level
ln -s /path/to/omp-startup ~/.pi/agent/extensions/omp-startup    # Pi, user-level

Configure by dropping a JSON file:

{ "greeting": "Ahoy, {user}!", "info": ["{model} · {provider}", "{branch} | {dir}"] }

Layer	File
Project	<cwd>/.omp/dashboard.json or <cwd>/.pi/dashboard.json (first that exists)
User	~/.config/dashboard/config.json

Every option with its default value — copy what you need; keys you omit always keep these values:

{
  "layout": "box",
  "title": "{app} v{version}",
  "width": 100,
  "logo": "pi",
  "gradient": true,
  "greeting": "Welcome back!",
  "left": ["greeting", "blank", "logo", "blank", "info"],
  "right": ["shortcuts", "sessions"],
  "info": ["{model}", "{provider}"],
  "shortcuts": [
    { "key": "#", "label": "for prompt actions" },
    { "key": "/", "label": "for commands" },
    { "key": "!", "label": "to run bash" },
    { "key": "$", "label": "to run python" }
  ],
  "sessions": 4,
  "quote": [],
  "dismiss": true,
  "command": "dashboard",
  "replaceNativeWelcome": true
}

/dashboard toggles it at any time. On first submitted prompt it hides ("dismiss": true). Full option list, tokens, recipes, troubleshooting: docs/USAGE.md.

Host behavior

Host	Route	Native welcome
omp	quiet takeover + widget above the editor	by default the plugin owns startup.quiet across launches so only the dashboard renders at startup; disabling takeover (or deleting the config) restores the previous value at the next launch; "replaceNativeWelcome": false leaves the native welcome untouched and makes the dashboard manual-only
Pi	header replacement in place	by default the dashboard swaps the native header component and scrolls away like it (dismiss restores); false keeps the native chrome untouched

Routing is decided at runtime by probing whether setHeader actually works — no version sniffing; if either host changes, the plugin adapts.

Documentation

• docs/USAGE.md — install paths, full config reference, token table, recipes per layout, host behavior matrix, troubleshooting.
• docs/ARCHITECTURE.md — module map, capability probe design, lifecycle state machine, renderer pipeline, compatibility notes, and the live-host verification log.
• docs/PUBLISHING.md — release checklist for maintainers (version bump, prepublish gate, npm publish) and the deployment matrix for consumers.

Development

npm install         # dev-only tooling
npm run typecheck   # strict tsc --noEmit (src + scripts + tests)
npm run smoke       # 53 host-free render/probe/token/seam assertions
npm test            # 199-assertion suite on node:test

Zero runtime dependencies; hosts load the TypeScript sources as-is.