pi-main-menu

A small Pi package that replaces the startup header with a configurable welcome screen. It gives Pi a personal front door: greetings, a block-art logo, project/model context, and a lightweight customization menu.

Install

pi install npm:pi-main-menu

Pi discovers the package through its pi manifest and loads the extension automatically. The package is also tagged with pi-package so it can appear in the Pi package gallery.

Commands

• /welcome or /main-menu — open the customization menu
• Ctrl+Shift+M — open the same menu
• /welcome reload — reload the configuration
• /welcome rotate — pick a new random greeting immediately
• /welcome preview — show the header as a floating overlay (any key dismisses)
• /welcome artcolor [color] — style the art in real time: opens a color picker, or set a color directly (e.g. /welcome artcolor accent); tab-completes colors
• /welcome builtin — restore Pi's built-in header for the current session
• /welcome reset — remove a selected config file

Configuration

The extension reads these files, with project values taking precedence:

• ~/.pi/agent/main-menu.json
• .pi/main-menu.json

Example:

{
  "greetings": [
    "Welcome back.",
    "What are we making today?"
  ],
  "art": [
    "█████████████████████       ",
    "█████████████████████       ",
    "█████████████████████       ",
    "█████████████████████       ",
    "████████      ███████       ",
    "████████      ███████       ",
    "████████      ███████       ",
    "██████████████       ███████",
    "██████████████       ███████",
    "██████████████       ███████",
    "██████████████       ███████",
    "████████             ███████",
    "████████             ███████",
    "████████             ███████"
  ],
  "showArt": true,
  "artColor": "accent",
  "subtitle": "a small coding cockpit",
  "prompt": "Type a prompt or /welcome to customize",
  "hints": [
    "/welcome customize  ·  Ctrl+Shift+M menu"
  ],
  "showHints": true,
  "showContext": true,
  "showModel": true,
  "showClock": false
}

art may also be a single multiline string or an artFile path relative to the config file. Set showArt to false to hide the art block. Clearing art in the interactive editor sets it to false automatically.

artColor tints the art block with a theme color: accent, text, muted, dim, success, error, warning, border, borderMuted, borderAccent, toolTitle, or mdHeading. Unknown values are ignored with a warning.

Greeting, subtitle, prompt, and hint strings support these placeholders:

Placeholder	Value
{project}	Project directory name
{cwd}	Full working directory path
{model}	provider/model-id of the active model
{modelName}	Friendly display name of the model
{session}	Current session name (or untitled)
{pi}	Pi version
{time}	Current time (locale format, e.g. 14:41 or 04:41 PM)
{date}	Current date (e.g. Fri, Aug 15)

Live header

The header is not a static snapshot — it updates while pi runs:

• {time} (and the context-line clock, when showClock is on) ticks once per minute
• the model line follows /model switches
• {session} updates when you rename the session with /name
• theme changes re-render immediately

Hide Pi's loaded resource list

Pi's native quietStartup setting hides the [Context], [Skills], and [Extensions] sections while keeping this custom header visible:

{
  "quietStartup": true
}

Put that in .pi/settings.json for one project or ~/.pi/agent/settings.json globally. The /welcome menu can toggle this setting.

The menu also toggles the project name, model, and clock lines independently (showContext, showModel, showClock).

License

MIT