@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 (two-column layout on wide terminals)
• 🖼️ Custom banner — bring your own ASCII art via banner.txt
• ⏱️ Auto-dismiss — countdown, keypress, or agent activity
• 🎨 Catppuccin Mocha — full palette, all colors by name

📦 Install

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

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

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

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

After installing, just start pi — 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:

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

Search order (first found wins):

1. Explicit bannerFile path from config
2. ~/.pi/agent/pi-welcome-screen/banner.txt
3. ./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:

~/.pi/welcome-screen.config.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/welcome-screen.config.json
2. ~/.pi/config/welcome-screen.json
3. ./welcome-screen.config.json (project root)

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

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 on the right side when the terminal is ≥ 100 chars wide, or below the banner on narrower terminals.

Option	Type	Default	Description
showInfoPanel	boolean	true	Show the info panel
showVersion	boolean	true	Show Pi version
showModel	boolean	true	Show model name & provider
showTips	boolean	true	Show keyboard tips
showLoaded	boolean	true	Show loaded counts (extensions, skills, etc.)
showResources	boolean	true	Show detailed resource listings
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

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": "~/.pi/agent/pi-welcome-screen/banner.txt",
    "animationStyle": "rainbow",
    "animationColor": "green"
}

🤝 Compatibility

pi-powerline-footer — if you use pi-powerline-footer, disable its welcome screen to avoid conflicts:

{
    "powerline": { "welcome": false }
}

🛠️ Development

No build step — Pi loads TypeScript directly via jiti.

# Test locally
pi -e .

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

📁 Project Structure

src/
├── index.ts           # Entry point — Pi extension factory
├── WelcomeOverlay.ts  # Overlay component with two-column 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

📄 License

MIT © Code Sook