https://github.com/alceal/pj
Project launcher CLI with fuzzy matching
https://github.com/alceal/pj
cli fuzzy-finder productivity rust terminal
Last synced: 4 months ago
JSON representation
Project launcher CLI with fuzzy matching
- Host: GitHub
- URL: https://github.com/alceal/pj
- Owner: alceal
- License: mit
- Created: 2025-12-26T19:29:16.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-03-08T13:09:06.000Z (4 months ago)
- Last Synced: 2026-03-08T14:51:14.061Z (4 months ago)
- Topics: cli, fuzzy-finder, productivity, rust, terminal
- Language: Rust
- Size: 118 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# 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
- **Multiplexer Support**: Automatically opens vim/nvim in a split pane when running inside tmux or cmux
- **Git Integration**: Prompt to initialize git repositories when adding projects
- **GitHub Integration**: Optionally create GitHub remotes via the gh CLI
## Installation
### Homebrew
```bash
brew install alceal/tap/pj
```
### Cargo
```bash
cargo install pj-cli
```
### From Source
```bash
git clone https://github.com/alceal/pj
cd pj
cargo install --path .
```
## Quick Start
Run the interactive setup wizard:
```bash
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:
```bash
cd ~/projects/my-app
pj -a -t work,rust
```
Select and open a project:
```bash
pj
```
## Commands
| Command | Description |
|---------|-------------|
| `pj` | Open interactive project selector |
| `pj ` | Filter projects by terms (auto-selects if single match) |
| `pj --init` | Run the setup wizard |
| `pj --config` | Interactive configuration editor |
| `pj --list` | Display all tracked projects with status |
| `pj -a` / `pj --add` | Add current directory as a project |
| `pj --rm` | Remove projects interactively |
| `pj --rm-missing` | Remove all projects with missing paths |
### Options
| Option | Description |
|--------|-------------|
| `-t, --tags ` | Add tags to project(s) or filter when adding |
| `--rm-tags ` | Remove tags from project(s) |
| `-e, --editor ` | Override the configured editor |
| `--no-editor` | Skip opening editor (just cd if enabled) |
| `--cd` / `--no-cd` | Override directory change behavior |
### Examples
```bash
# 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`:
```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:
```bash
# 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.