Pi Vitals

A customizable powerline-style footer for the pi coding agent. This extension provides a rich, informative status bar at the bottom of the terminal showing model info, git status, token usage, and more.

Features

• Customizable segments: Choose which info to display on the left and right sides
• Smart git paths: Shows [repo_name]/relative/path inside git repos, with correct handling for worktrees
• Git integration: Shows current branch and working tree status (staged, unstaged, untracked)
• Extension status passthrough: Displays status from other pi extensions (e.g., thinking-steps) that would otherwise be hidden when pi-vitals replaces the built-in footer
• Token tracking: Display input/output/total tokens and cache read/write
• Context awareness: Shows context window usage percentage
• Thinking level: Visual indicator of model reasoning level
• Nerd Font support: Automatic detection with ASCII fallbacks
• Live updates: Git status refreshes after every assistant message

Installation

Install from npm using pi:

pi install npm:pi-vitals

Or copy the extension files to your pi extensions directory manually:

# Copy to global extensions directory
cp -r . ~/.pi/agent/extensions/pi-vitals

# Or use directly for testing
pi -e ./index.ts

Configuration

Create ~/.pi/agent/powerline.json to customize the footer:

{
  "leftSegments": [
    "pi",
    "separator",
    "model",
    "thinking",
    "ext_status",
    "separator",
    "path",
    "git",
    "separator",
    "token_total",
    "token_in",
    "token_out",
    "cache_read",
    "cache_write"
  ],
  "rightSegments": [
    "separator",
    "context_pct"
  ],
  "icons": {
    "pi": "π",
    "model": "◈",
    "thinking": "🧠",
    "folder": "📁",
    "repo": "📦",
    "git": "⎇",
    "tokens": "⊛",
    "input": "↑",
    "output": "↓",
    "cacheRead": "↙",
    "cacheWrite": "↗",
    "contextPct": "◫",
    "separator": "|"
  },
  "colors": {
    "pi": "accent",
    "model": "#d787af",
    "path": "#00afaf",
    "git": "success",
    "gitDirty": "warning",
    "gitClean": "success",
    "thinking": "muted",
    "context": "dim",
    "contextWarn": "warning",
    "contextError": "error",
    "cost": "text",
    "tokens": "muted",
    "separator": "dim"
  },
  "segmentOptions": {
    "path": {
      "mode": "basename"
    },
    "git": {
      "showBranch": true,
      "showStaged": true,
      "showUnstaged": true,
      "showUntracked": true
    },
    "context_pct": {
      "showAutoIcon": false
    }
  }
}

Available Segments

Segment	Description
pi	Pi logo/icon
model	Current model name
thinking	Thinking/reasoning level indicator
ext_status	Status text from other pi extensions (e.g., thinking-steps)
path	Current working directory
git	Git branch and status
token_in	Input tokens
token_out	Output tokens
token_total	Total tokens (input + output + cache)
cache_read	Cache read tokens
cache_write	Cache write tokens
cost	Estimated cost
context_pct	Context window usage percentage
context_total	Total context window size
separator	Visual separator icon
text:...	Custom text segment (e.g., text:⚡)

Smart Path Display

The path segment adapts based on whether you're inside a git repo:

• Not in a git repo: Shows the full current path
• In a git repo: Shows [repo_name]/relative/path with the repo icon
• In a worktree: Same format — uses the bare repo name, so plexus/main shows as [plexus] instead of redundantly showing main main

Extension Status Passthrough

When pi-vitals replaces the built-in footer, status text from other extensions (set via ctx.ui.setStatus()) would normally be hidden. The ext_status segment reads these statuses from pi's footer data provider and displays them inline. For example, the thinking-steps plugin's "thinking: summary" status appears automatically.

Git Status Indicators

The git segment shows:

• Branch name with icon
• *N - Unstaged changes (warning color)
• +N - Staged changes (success color)
• ?N - Untracked files (muted color)

Colors indicate clean (green) vs dirty (yellow) working tree.

Git status is refreshed after every assistant message and when file-changing tools are used.

Commands

• /footer reload - Reload configuration from disk
• /footer debug - Show current configuration

Path Modes

The path segment supports three modes:

• basename - Just the directory name, or [repo_name]/relative/path inside a git repo (default)
• abbreviated - Shortened path with ~ for home
• full - Full path

Icons

The extension automatically detects Nerd Font support (via TERM_PROGRAM or GHOSTTY_RESOURCES_DIR) and uses appropriate icons. You can force Nerd Fonts with:

export POWERLINE_NERD_FONTS=1

Or disable with:

export POWERLINE_NERD_FONTS=0