@codesook/pi-welcome-screen

---

✨ Features

• 🎨 6 animation styles — wave, rainbow, glitch, matrix, typewriter, static
• 📦 Styled overlay box — box-drawing borders with background fill
• 📊 Info panel — model, keyboard tips, loaded resources, recent sessions stacked below the banner
• 🖼️ Custom banner — bring your own ASCII art via banner.txt
• ⏱️ Auto-dismiss — countdown, keypress, or agent activity
• 🖥️ Optional terminal-animation banner — run a local CLI to render a second same-size banner below the built-in/custom banner
• 🎨 Catppuccin Mocha — full palette, all colors by name

📦 Install

# From npm (recommended)
omp install npm:@codesook/pi-welcome-screen

# Try without installing
omp -e npm:@codesook/pi-welcome-screen

# From git
omp install git:github.com/seenark/pi-welcome-screen

# Local development
git clone https://github.com/seenark/pi-welcome-screen.git
omp -e /path/to/pi-welcome-screen

After installing, just start omp — the welcome screen appears automatically on every session.

🖼️ Custom Banner

Replace the built-in ASCII banner with your own art. Create a plain text file:

~/.pi/agent/pi-welcome-screen/banner.txt

 ██████╗ ██████╗ ██████╗ ███████╗    ███████╗ ██████╗  ██████╗ ██╗  ██╗
██╔════╝██╔═══██╗██╔══██╗██╔════╝    ██╔════╝██╔═══██╗██╔═══██╗██║ ██╔╝
██║     ██║   ██║██║  ██║█████╗      ███████╗██║   ██║██║   ██║█████╔╝
██║     ██║   ██║██║  ██║██╔══╝      ╚════██║██║   ██║██║   ██║██╔═██╗
╚██████╗╚██████╔╝██████╔╝███████╗    ███████║╚██████╔╝╚██████╔╝██║  ██╗
 ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝    ╚══════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝

Or point to any file via config:

{
    "bannerFile": "/path/to/my-banner.txt"
}

Search order (first found wins):

1. Explicit bannerFile path from config
2. PI_CODING_AGENT_DIR/pi-welcome-screen/banner.txt when PI_CODING_AGENT_DIR is set
3. ~/.pi/agent/pi-welcome-screen/banner.txt
4. ~/${PI_CONFIG_DIR:-.omp}/agent/pi-welcome-screen/banner.txt
5. ./welcome-screen.banner.txt (project root)

Tip: Keep your banner under ~80 characters wide for best results on all terminals.

⚙️ Configuration

Create a config file — only the fields you want to override are needed:

~/.config/codesook-omp/welcome-screen.json

{
    "mainText": "Your Name",
    "url": "https://yourwebsite.dev",
    "animationStyle": "rainbow",
    "animationColor": "pink",
    "borderStyle": "rounded",
    "countdown": -1,
    "showInfoPanel": true
}

Config file search order (first found wins):

1. PI_CODING_AGENT_DIR/pi-welcome-screen/settings.json when PI_CODING_AGENT_DIR is set
2. ~/.config/codesook-omp/welcome-screen.json
3. ~/.pi/agent/pi-welcome-screen/settings.json (legacy)
4. ~/${PI_CONFIG_DIR:-.omp}/agent/pi-welcome-screen/settings.json (legacy)
5. ~/.pi/welcome-screen.config.json (legacy)
6. ./welcome-screen.config.json (project root)

The ~/.config/codesook-omp/welcome-screen.json path is the recommended location for dotfiles repositories managed with tools like GNU Stow.

All Options

Text & Content

Option	Type	Default	Description
mainText	string	"CodeSook"	Text shown below the banner
url	string	"https://codesook.dev"	URL shown below main text
animationStyle	string	"rainbow"	Animation style (see below)
animationText	string	"Welcome"	Text used for some animations
frameDelayMs	number	80	Milliseconds between animation frames (0–1000)
bannerFile	string	""	Path to custom banner .txt file
terminalBannerCommand	string	""	Shell command for optional second terminal-animation banner; empty disables it
terminalBannerRows	number	6	Visible rows for optional terminal-animation banner
terminalBannerColumns	number	0	Visible columns for optional terminal-animation banner; 0 matches the current banner width
terminalBannerFrameDelayMs	number	33	Minimum milliseconds between terminal-animation banner renders

Layout

Option	Type	Default	Description
paddingTop	number	2	Empty lines above content
paddingBottom	number	2	Empty lines below content
borderStyle	string	"rounded"	Border style: rounded, square, double, minimal
bgFillChar	string	""	Background fill character (e.g. "░"). Empty = no fill
minTerminalWidth	number	80	Hide overlay if terminal is narrower than this
overlayWidth	number	120	Width of the overlay box

Behavior

Option	Type	Default	Description
countdown	number	-1	-1 = wait for keypress, 0 = never dismiss, >0 = seconds
debug	boolean	false	Overlay stays visible forever (never auto-dismisses)
enableScrolling	boolean	true	Allow arrow-key scrolling when content overflows

Colors (Catppuccin Mocha names)

Option	Type	Default	Description
fgColor	string	"lavender"	Main text color
bgColor	string	"base"	Background color
accentColor	string	"blue"	Border / accent color
urlColor	string	"sapphire"	URL text color
animationColor	string	"pink"	Animation / highlighted elements color

Visibility Toggles

Option	Type	Default	Description
showBanner	boolean	true	Show the ASCII art banner
showMainText	boolean	true	Show the main text line
showUrl	boolean	true	Show the URL line
showCountdown	boolean	true	Show countdown / "press any key" hint
showPadding	boolean	true	Show top/bottom padding
showBorder	boolean	true	Show the border box

Info Panel

The info panel appears below the banner on all terminal widths.

Option	Type	Default	Description
showInfoPanel	boolean	true	Show the info panel
showVersion	boolean	true	Show OMP/Pi CLI version
showModel	boolean	true	Show model name & provider
showTips	boolean	true	Show keyboard tips
showLoaded	boolean	true	Show loaded counts (context files, extensions, prompts, themes)
showResources	boolean	true	Show detailed resource listings (context files, extensions, prompts, themes)
showSessions	boolean	true	Show recent sessions
infoPanelSections	string[]	["version","model","tips","loaded","resources","sessions"]	Section order
modelName	string	""	Override model name (auto-detected if empty)
providerName	string	""	Override provider name (auto-detected if empty)
logoChar	string	"π"	Character used for the logo

terminalBannerCommand is executed by the local shell. Keep it in user-controlled config only; do not feed untrusted input into it. Terminal banner output is captured through Bun.Terminal when available, with a Python stdlib PTY bridge fallback for Node/Pi runtimes. The parser preserves SGR foreground/background colors and publishes frames at the configured cadence so clear/redraw animations do not expose partial frames.

Animation Styles

Style	Description
wave	Letters shift with a sinusoidal wave effect
rainbow	Each line cycles through the Catppuccin spectrum
glitch	Random glitch artifacts appear on lines
matrix	Text is revealed from left to right (Matrix-style)
typewriter	Characters appear one-by-one
static	No animation — banner shown in full color

Border Styles

Style	Corners	Sides
rounded	╭ ╮ ╰ ╯	│ ─
square	┌ ┐ └ ┘	│ ─
double	╔ ╗ ╚ ╝	║ ═
minimal	+ + + +	│ ─

Color Palette (Catppuccin Mocha)

All color options accept these names:

Name	Hex	Preview	Name	Hex	Preview
base	#1e1e2e	🟣	lavender	#b4befe	💜
mantle	#181825	⬛	blue	#89b4fa	💙
crust	#11111b	⬛	sapphire	#74c7ec	🩵
surface0	#313244	🔘	sky	#89dceb	🩵
surface1	#45475a	🔘	teal	#94e2d5	🩵
surface2	#585b70	🔘	green	#a6e3a1	💚
overlay0	#6c7086	🔘	yellow	#f9e2af	💛
overlay1	#7f849c	🔘	peach	#fab387	🧡
overlay2	#9399b2	🔘	maroon	#eba0ac	🩷
subtext0	#a6adc8	🔘	red	#f38ba8	❤️
subtext1	#bac2de	🔘	mauve	#cba6f7	💜
text	#cdd6f4	⬜	pink	#f5c2e7	🩷
			flamingo	#f2cdcd	🩷
			rosewater	#f5e0dc	🩷

🎮 Commands

Command	Description
/welcome-dismiss	Manually dismiss the welcome overlay
/welcome-reload	Reload config and reshow the overlay

🧩 Example Configs

Minimal — just change the name

{
    "mainText": "acme-corp"
}

Dark cyberpunk theme

{
    "mainText": "NEON::CORP",
    "url": "https://neon.corp",
    "animationStyle": "glitch",
    "animationColor": "red",
    "fgColor": "red",
    "urlColor": "mauve",
    "borderStyle": "double",
    "bgFillChar": "░"
}

Clean & minimal — no animation, no border

{
    "mainText": "my-project",
    "url": "https://github.com/me/my-project",
    "animationStyle": "static",
    "animationColor": "blue",
    "showBorder": false,
    "showInfoPanel": false,
    "paddingTop": 1,
    "paddingBottom": 0,
    "countdown": 3
}

Custom banner with your brand

{
    "mainText": "My Brand",
    "url": "https://mybrand.io",
    "bannerFile": "~/.omp/agent/pi-welcome-screen/banner.txt",
    "animationStyle": "rainbow",
    "animationColor": "green"
}

Terminal animation CLI banner

{
    "terminalBannerCommand": "ascii-animation run",
    "terminalBannerRows": 8,
    "terminalBannerColumns": 100,
    "terminalBannerFrameDelayMs": 33
}

🛠️ Development

No build step — Oh-My-Pi loads TypeScript directly via jiti.

# Test locally
omp -e .

# Install from local path
omp install /path/to/pi-welcome-screen

📁 Project Structure

src/
├── index.ts           # Entry point — Oh-My-Pi extension factory
├── WelcomeOverlay.ts  # Overlay component with stacked layout
├── config.ts          # Defaults, Catppuccin palette, config loading
├── animations.ts      # ASCII banner data + frame builders per style
├── renderer.ts        # ANSI escape codes, color mapping, centering
├── info-panel.ts      # Loaded counts, recent sessions discovery
└── types.ts           # Config interface, animation & border types

Release

This package is published automatically when a Git tag is pushed.

Example:

git checkout main
git pull

git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

The GitHub Actions workflow reads the tag name, sets the package version inside CI, builds the package, and publishes it to npm.

The tag is the source of truth for the published npm version.

📄 License

MIT © Code Sook