pi-completion

简体中文

Shell completion for the pi coding agent. It adds tab completion for pi commands, options, and arguments in:

• Bash
• Zsh
• PowerShell 7 (pwsh)

pi-completion is a standalone command-line tool. You do not need to install the optional pi extension to use shell completion.

Quick start

Install the command globally, then configure the shell you use:

bun add --global pi-completion

# Choose one:
pi-completion install bash
pi-completion install zsh
pi-completion install pwsh

The installer adds the completion to your shell's startup configuration:

Shell	What is changed
Bash	~/.bashrc
Zsh	A _pi completion file in a writable fpath directory and ~/.zshrc
PowerShell	Your PowerShell profile ($PROFILE)

Restart your shell, or run the reload command printed by the installer. Then try running pi and pressing Tab after a command or option.

Check the installation

Print the installed completion version with:

pi-completion --version

To confirm that your shell can find the command:

command -v pi-completion   # Bash and Zsh
Get-Command pi-completion  # PowerShell

Manual Installation

Use this approach when you manage your own shell configuration or do not want the installer to edit it. Add the matching snippet below to your shell startup file. These examples use bunx, so a global pi-completion installation is not required.

Bash

Add this to ~/.bashrc:

source <(bunx pi-completion bash)

Reload it with source ~/.bashrc.

Zsh

Generate the completion file once, then add the setup to ~/.zshrc:

mkdir -p ~/.zfunc
bunx pi-completion zsh > ~/.zfunc/_pi

# ~/.zshrc
fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

Start a new shell or run source ~/.zshrc.

PowerShell

Add this to your PowerShell profile ($PROFILE):

bunx pi-completion pwsh | Out-String | Invoke-Expression

Create and open the profile if it does not exist:

New-Item -ItemType File -Path $PROFILE -Force
notepad $PROFILE

Open a new PowerShell session after saving it.

To avoid downloading or resolving the package through bunx when a shell starts, install it globally with bun add --global pi-completion and replace bunx pi-completion in these snippets with pi-completion.

Home Manager and read-only shell configuration

If ~/.bashrc or ~/.zshrc is managed by Home Manager or another tool, it may be read-only. In that case, pi-completion install writes any completion file it can and prints the configuration snippet to add to your Home Manager setup.

For example, the Bash setup is equivalent to:

programs.bash.initExtra = ''
  source <(pi-completion bash)
'';

For Zsh, make sure the directory containing _pi is in fpath before running compinit. The installer prints the exact directory and snippet for your machine.

Optional pi extension

The package also includes an optional pi extension. It can remind you when shell completion is not installed and provides the /completion-install command.

Install the CLI first, then register the extension with pi:

bun add --global pi-completion
pi install npm:pi-completion

Inside pi, run:

/completion-install

The extension detects Bash or Zsh and shows the appropriate install command. If your shell cannot be detected, it shows the commands for all supported shells. The extension only provides setup help; the pi-completion install command does the actual installation.

Completion version reminders

When pi starts in interactive TUI mode, the extension compares the loaded completion version with the running pi version. If the completion is older, it warns you to update pi-completion and reinstall the completion. It also warns when the loaded completion targets a newer pi version.

The comparison uses PI_COMPLETION_VERSION, which the completion script sets when your shell loads it. It does not check the package registry for newer releases. If no completion is loaded, the extension shows an installation reminder for up to three pi sessions.

Updating

Completion definitions track the pi CLI version. When pi is updated, update pi-completion as well and reinstall the completion for your shell:

bun add --global pi-completion@latest
pi-completion install bash  # or zsh / pwsh

The installer refuses a completion package that targets a newer pi version than the pi executable it finds. If the versions do not match, update pi or install a matching pi-completion release.

Uninstall

Remove the managed shell-startup block with:

pi-completion uninstall bash
pi-completion uninstall zsh
pi-completion uninstall pwsh

For Bash and PowerShell, the command removes the block from the corresponding profile. For Zsh, remove the _pi file printed by the command and delete the pi-completion block from ~/.zshrc if it is still present.

License

MIT