🚀 pi-starship — Build Pi's Footer with Starship-style TOML

Build a customizable Pi footer with Starship-style TOML, native Pi modules, conditional formats, palettes, and responsive multiline layout. The extension parses and renders the footer itself, so it does not need the starship executable or a shell prompt.

Different package: The unscoped npm package pi-starship delegates to the Starship binary. This package is @narumitw/pi-starship and renders Pi-specific modules natively.

✨ Features

• Starts with a readable built-in footer and offers Starship presets plus a Pi-native Minimal preset.
• Supports root and module formats, conditional groups, $all, styles, palettes, and width-aware $fill alignment.
• Selects provider, model, and thinking styles from exact runtime values with ordered module rules.
• Provides Pi, model, usage, Git, pull request, package, language, environment, deployment, cloud, and execution modules.
• Wraps native multiline layouts to terminal width instead of truncating them.
• Keeps rendering pure while refreshing filesystem, process, and network-derived data through bounded caches.
• Uses /starship for presets, preview, configuration health, searchable module details, customization, and recovery.
• Bundles the authoritative configuration skill and references for editing pi-starship.toml or answering setup questions.
• Loads a generated split runtime to reduce Pi package startup work.

📦 Install

pi install npm:@narumitw/pi-starship

Try the published package without installing it permanently:

pi -e npm:@narumitw/pi-starship

Build the generated runtime and try the local package from this repository:

npm --workspace @narumitw/pi-starship run build
pi -e ./packages/pi-starship

The package declares dist/index.ts, so build an unbuilt local checkout before Pi loads the package directory. Install only from sources you trust because Pi extensions and skills run with Pi's permissions. Do not enable this with @narumitw/pi-statusline: both own Pi's footer, and Pi does not arbitrate that conflict.

🚀 Quick start

Start Pi with the extension to use the built-in footer without creating a settings file. Run /starship to inspect the footer, choose a preset, or customize the configuration.

The bundled configuration skill is manual-only and is not available for automatic model invocation. Run /skill:configuring-pi-starship before asking Pi to explain or edit pi-starship.toml:

/skill:configuring-pi-starship explain the aws module
/skill:configuring-pi-starship enable the directory and git_branch modules

The skill loads the relevant reference and validates file edits. It does not cover general TOML, shell Starship configuration, extension source development, or unrelated footer work.

💬 Commands

Command	Purpose
/starship	Customize the footer, preview presets, inspect modules, or restore built-in configuration; RPC shows help.
/starship settings	Edit, preview, and confirm TOML; RPC shows the file path.
/starship status	Show the configuration source, path, and diagnostics.
/starship help	Show command and configuration help.

All routes support TUI and RPC with the exceptions above and reject unknown or trailing arguments. Print and JSON modes produce no command output; the footer runs only in TUI mode. Preset selection, module inspection, and recovery are menu-only, not extra subcommands. Restoring built-in configuration requires an existing settings document to replace; see Settings.

⚙️ Settings

The package bundles the configuring-pi-starship skill as the authoritative configuration guide for users and agents. Invoke /skill:configuring-pi-starship before asking Pi how to configure the footer or edit pi-starship.toml. The skill answers from its references and consults the bundled source only when the public documentation does not cover a question.

Read the references directly when preferred:

• Configuration and format — settings schema, validation and fallback behavior, presets, examples, format grammar, styles, palettes, and display thresholds.
• Complete module catalog — exact variables, default formats, symbols, enabled state, style fields, display defaults, option types, ranges, and enum values.
• Module behavior — reachability, exact detection defaults, command gates, output semantics, aliases, truncation, and module-specific behavior.
• Runtime and security — network and command execution, local metadata, cloud and deployment context, fill layout, refresh behavior, and limitations.

The only configuration source remains <getAgentDir()>/pi-starship.toml. A minimal custom document can select and style only the modules it needs:

format = "$model$directory$git_branch"

[model]
style = "bold blue"

Provider, model, and thinking modules also accept ordered exact-match style_rules; see Configuration and format. Use /starship for interactive configuration, preview, diagnostics, presets, and recovery. Manual file edits load at the next session_start, including /reload.

🔒 Security and privacy

Some opt-in modules read local development, deployment, cloud, host, or user metadata, run bounded local commands, or query GitHub through gh. Review Runtime and security before enabling them.

🚧 Limitations

pi-starship is Starship-inspired rather than fully compatible with shell Starship. The complete supported and intentionally omitted behavior is documented in Runtime and security.

➕ Adding a module

Create src/modules/<name>.ts with its format variables, defaults, and runtime value resolver, then register it in display order in src/modules/catalog.ts. Configuration names, validation variables, defaults, and $all ordering are derived from that catalog. Add the module to the built-in root format only when it should be visible by default, then document and test its user-facing values. Keep extension_status last in the catalog so arbitrary third-party statuses follow native module output.

🗂️ Package layout

packages/pi-starship/
├── src/                               # Modules, formats, presets, and runtime collectors
│   ├── index.ts                       # Thin Pi entrypoint
│   └── pi-starship.ts                 # Footer lifecycle and cached refresh
├── dist/                              # Generated Jiti runtime
├── scripts/build-runtime.mjs          # Runtime builder
├── skills/configuring-pi-starship/    # Authoritative configuration skill and references
└── test/                              # Behavior and lifecycle coverage

The generated runtime is built from src/index.ts and does not import back into src.

🔎 Keywords

Pi Coding Agent, Starship statusline, Starship TOML, terminal footer, native statusline, configuration editing, agent skill, GitHub pull request, prompt cache, cache hit rate, Pi extension

📄 License

MIT. See LICENSE. Starship attribution and its ISC license are included in NOTICES.md.