pj

A fast, terminal-based project launcher with fuzzy matching. Quickly navigate between projects, organize them with tags, and launch your editor with a single command.

Features

• Fuzzy Matching: Interactive TUI with real-time filtering powered by skim
• Frecency Ranking: Smart ordering based on frequency and recency of access
• Hierarchical Tags: Organize projects with nested tags (e.g., work/backend)
• Shell Integration: Automatic directory changing for bash, zsh, fish, and sh
• Editor Integration: Launch your preferred editor when selecting a project
• Git Integration: Prompt to initialize git repositories when adding projects
• GitHub Integration: Optionally create GitHub remotes via the gh CLI

Installation

Homebrew

brew install alceal/tap/pj

Cargo

cargo install pj-cli

From Source

git clone https://github.com/alceal/pj
cd pj
cargo install --path .

Quick Start

Run the interactive setup wizard:

pj --init

This will configure your shell, editor, and preferences. The wizard detects your shell automatically and installs the necessary shell function for directory changing.

Add your first project:

cd ~/projects/my-app
pj -a -t work,rust

Select and open a project:

pj

Commands

Options

Examples

# Add project with multiple tags
pj -a -t work/backend,rust,api

# Filter projects by name (auto-selects if single match)
pj rust
pj my-project

# Open project with a different editor
pj -e zed

# List all tracked projects
pj --list

# Remove all projects with missing paths
pj --rm-missing

# Edit configuration interactively
pj --config

Configuration

Configuration is stored in ~/.pj/config.toml:

editor = "code"           # Editor command to launch
cd_on_select = true       # Change directory when selecting a project
git_init_on_add = true    # Prompt to initialize git when adding a project
gh_create_on_add = false  # Create GitHub remote when adding (requires gh CLI)

Project data is stored in ~/.pj/projects.json.

Shell Integration

When cd_on_select is enabled, pj installs a shell function that wraps the binary to enable directory changing. The setup wizard handles this automatically for:

• Bash: Added to ~/.bashrc
• Zsh: Added to ~/.zshrc
• Fish: Added to ~/.config/fish/config.fish
• POSIX sh: Added to ~/.profile

Tag Hierarchy

Tags support hierarchical organization using / as a separator:

# Add with hierarchical tags
pj -a -t work/frontend/dashboard

# Filter by tag in selection
pj work           # Fuzzy matches against path and tags
pj work/frontend  # More specific filter

License

This project is licensed under the MIT License. See the LICENSE.txt file for details.