main

pi-shell-completions

Adds native shell completions to pi’s ! and !! bash mode commands.

Installation

pi install npm:pi-shell-completions

Or for local development, place in ~/.pi/agent/extensions/shell-completions/

How it works

When you type !git checkout in pi’s prompt, this extension queries your shell’s completion system and shows suggestions.

Shell support

Shell How it works Quality
Fish Native complete -C command ⭐⭐⭐ Excellent - all completions work
Bash Sources bash-completion scripts ⭐⭐ Good - if bash-completion is installed
Zsh Fallback script for common tools ⭐ Basic - see limitations

Fish’s completion system is designed to be queried programmatically via complete -C "command ". This means:

  • All your fish completions work automatically
  • Git branches, docker containers, ssh hosts, npm scripts — everything
  • Descriptions are included
  • Fast (10-30ms)

Even if fish isn’t your primary shell, installing it gives you great completions in pi.

Bash

Bash-completion can be queried by setting up COMP_* environment variables and calling completion functions. This extension:

  • Sources completion scripts from standard locations (/opt/homebrew/etc/bash_completion.d/, /usr/share/bash-completion/completions/, etc.)
  • Calls the registered completion function for each command
  • Works if you have bash-completion installed

Zsh (limited)

Zsh’s completion system is tightly coupled to its line editor (ZLE) and cannot be easily queried programmatically. The zpty pseudo-terminal approach is complex and unreliable.

Current limitations:

  • Does NOT use your full zsh completion config
  • Only handles common tools: git, ssh, make, npm/yarn/pnpm, docker
  • Falls back to file completion for other commands

Recommendation: If you use zsh and want good completions in pi, install fish as a secondary shell. The extension will automatically prefer fish when available.

Shell priority

  1. Your $SHELL (if fish/zsh/bash)
  2. Fish (if available) — even if not your primary shell
  3. Zsh
  4. Bash

Requirements

  • One of: fish, zsh, or bash
  • For bash: bash-completion package installed
  • For best experience: fish

License

MIT