pi-zoxide

A zoxide-powered /z command for Pi. It uses zoxide's database and ranking, records successful destinations, and forks the current Pi session into the target directory so the conversation is preserved.

Pi loads TypeScript extensions directly, so this package intentionally publishes its source instead of creating a compiled build.

Requirements

• Node.js 20 or newer
• The zoxide executable on Pi's PATH
• Pi
• For development: Nix with flakes enabled and devenv

Install zoxide before installing this extension. For example:

# Nix
nix profile install nixpkgs#zoxide

# Homebrew
brew install zoxide

# Cargo
cargo install zoxide --locked

See the official zoxide installation guide for other platforms. Shell initialization is not required by the extension, though it lets terminal navigation share and train the same zoxide database.

Install

Install from the Git repository, then restart Pi or run /reload:

pi install git:ssh.hayshin.dev/agents/pi-zoxide.git

Pi packages execute with the user's full system permissions. Review extensions before installing them. This extension invokes the external zoxide executable and reads and creates Pi session files to preserve conversation context across directory changes.

Usage

/z [keywords-or-path]

Examples:

/z
/z ..
/z ~/dev/my-project
/z agents api

With no arguments, /z goes to your home directory. Existing paths are used directly; all other arguments are passed to zoxide as search keywords. There are no extension-specific subcommands or options.

Development

Enter the reproducible environment and install dependencies:

devenv shell
pnpm install

The environment includes zoxide. Launch Pi with the source entry point for interactive testing:

pnpm run dev

For package-style local installation instead:

pi install ./

Run formatting, linting, type checking, and tests through Vite+:

pnpm run check
pnpm run lint
pnpm run fmt
pnpm run test
pnpm run test:watch
pnpm run test:coverage

Coverage reports are written to coverage/. Validate the exact npm package contents without publishing:

pnpm run pack:check

Only src/, README.md, LICENSE, and package metadata are published. Pi's core packages are peer dependencies, with matching development dependencies for local checks.

Publishing

After updating the version, run the full checks and publish to the configured npm registry:

pnpm run check
pnpm run test:coverage
pnpm run pack:check
pnpm publish

The package is configured for public scoped publication. Consumers can then install it with:

pi install npm:@hayshin/pi-zoxide

Credits and license

The session-switching implementation is based on @firstpick/pi-extension-cd, originally created by Firstpick and distributed under the MIT License. See LICENSE for the project and attribution notices.