✨ 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:

{
    "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/agent/pi-welcome-screen/settings.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/agent/pi-welcome-screen/settings.json
2. ~/.pi/welcome-screen.config.json (legacy)
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 (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 |

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"
}

🛠️ 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