ppicker
Press a hotkey, type a few letters, hit Enter: the project opens in your editor. No typing paths, no dozens of hotkeys, no remembering which editor goes with which project.
ppicker is a ~1 MB program that starts instantly. It was built as a popup for tiling window managers (i3, sway) but works in any terminal, and through rofi, wofi, fuzzel or fzf if you prefer those.
- Fuzzy search over project names and paths, with tag filters
- Opens the project in the editor you used last time, per project
- Shows the git branch and when you last opened each project
- Linux is the main target; macOS and Windows build and pass the tests in CI
Quick start
1. Install. The command it gives you is pp.
pipx install ppicker # or: uv tool install ppicker
cargo install ppicker # alternative
2. Tell it about your projects.
pp scan ~/code # adds every git repository directly inside ~/code
pp add ~/work/shop # or add one by hand ("pp add ." for the current directory)
3. Open the picker.
pp
4. Bind it to a key so it pops up when you need it. See i3 / sway.
How it works
Find a project
Start typing. ppicker matches against the project name and its path, so shop or work/sh
both find ~/work/shop. The list narrows as you type, the best match is on top, and the matched
letters are highlighted. Projects you opened recently come first when the search box is empty.
The right-hand panel shows what you are about to open: the path, the current git branch, which
editor will be used, when you last opened it, and its tags. Press Tab to filter by a tag
(work, personal, ...) and Shift-Tab to go back.
Open it
Press Enter. The project opens in its editor and ppicker closes. The editor is started in the project's folder and keeps running on its own, so closing the terminal does not close it.
The first time you open a project, it uses your default editor, the first one in your config (see Editors). After that it uses whichever editor you opened it with last.
Open it with a different editor
Press → (right arrow) instead of Enter to choose an editor for this one.
Pick one with the arrow keys and Enter, or press its number (1-9). The project opens, and
ppicker remembers your choice for next time.
It remembers
Whichever editor you open a project with becomes that project's editor. The list shows it next to each name, and Enter uses it.
So you can keep a Python service in PyCharm, your dotfiles in vim and everything else in VS Code, and never think about it again. Just press Enter.
Change the editor without opening the project
Press Ctrl-e to step the selected project to the next editor in your list. It is saved at once and a note at the bottom tells you what changed. After the last editor it wraps back to your default.
Use rofi, wofi or fuzzel instead
If you already have a launcher you like, use it for the picking:
pp menu
It lists your projects, you choose one, and it opens in the remembered editor. Add --ask to get
a second step where you choose the editor:
pp menu --ask
For other launchers, pass the command to use: pp menu --cmd "fuzzel --dmenu" (or wofi --dmenu,
fzf). {prompt} in the command is replaced by the step name.
Keys
| Key | What it does |
|---|---|
| type | search by name or path |
↑ ↓ (or Ctrl-p Ctrl-n) |
move through the list |
Enter |
open the project in its editor |
→ |
open with a different editor |
1-9 |
in the editor list, open with that editor |
Ctrl-e |
switch the project's editor without opening it |
Tab / Shift-Tab |
next / previous tag filter |
Ctrl-u |
clear the search |
← or Esc |
back from the editor list; Esc in the main list quits |
Editors
List the editors you use in the config file (run pp paths to see where it is). The first one is
the default for projects you have not opened yet:
ides = ["code", "pycharm", "vim"]
scan_dirs = ["/home/me/code"] # used by `pp scan` when you give no folder
An editor is just a command. ppicker runs <command> . inside the project folder, for example
code . or pycharm .. Anything that opens a folder works, including idea, zed, subl,
nvim (see the note below for terminal editors) or code -n.
Terminal editors such as vim or nvim need a terminal to run in. Use a command that starts one, for example
ides = ["code", "alacritty -e nvim"].
Commands
Everything the picker does is also available from the command line:
pp # open the picker
pp open myproj # open a project without the picker
pp open myproj pycharm # open with a specific editor (and remember it)
pp editor myproj # show which editor a project uses
pp editor myproj pycharm # set it without opening
pp editor myproj --reset # forget it, back to the default editor
pp add . --ide pycharm # register the current folder and set its editor
pp add . --name api -t work # custom name, add a tag (repeat -t for more)
pp scan ~/code -t work # add every git repository in a folder
pp list # show projects with their editors
pp rm myproj # remove from the list (files are untouched)
pp menu [--ask] # pick through rofi or another launcher
pp paths # where the config and project list are stored
pp rm only forgets the project; it never deletes anything on disk.
i3 / sway
Open the picker in a small centred floating window on a hotkey. Add to ~/.config/i3/config:
bindsym $mod+p exec --no-startup-id alacritty --class pp-popup,pp-popup -e pp
for_window [class="pp-popup"] floating enable, resize set 960 520, move position center
(In sway, use app_id="pp-popup" and alacritty --class pp-popup or foot --app-id pp-popup.)
Prefer rofi? One line is enough:
bindsym $mod+p exec --no-startup-id pp menu
Where your data lives
Two small text files you can read and edit; pp paths prints the exact locations.
config.toml: your settings (editors, scan folders).projects.toml: your projects, their tags, last-opened time and remembered editor.
Moving from code-compass
ppicker replaces the old Qt-based code-compass package. See docs/MIGRATION.md
for what changed and how to bring your projects over:
pipx install ppicker
pipx run code-compass==0.2.0 migrate
Development
cargo test # unit tests
cargo clippy --all-targets -- -D warnings
A Linux end-to-end test that drives the real program inside i3 and rofi, and produces the screenshots above, is described in e2e/README.md.
Metadata
Release files for ppicker 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ppicker-0.1.0.tar.gz | 205.9 kB | With provenance | Details for ppicker-0.1.0.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| ppicker-0.1.0-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details for ppicker-0.1.0-py3-none-win_amd64.whl |
| ppicker-0.1.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details for ppicker-0.1.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
| ppicker-0.1.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details for ppicker-0.1.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
| ppicker-0.1.0-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details for ppicker-0.1.0-py3-none-macosx_11_0_arm64.whl |
| ppicker-0.1.0-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details for ppicker-0.1.0-py3-none-macosx_10_12_x86_64.whl |
Total release size: 3.0 MB
Release files / ppicker-0.1.0.tar.gz
| Download URL | ppicker-0.1.0.tar.gz |
|---|---|
| Size | 205.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0c437b4fbe9e6df18ef8bf865252caedc2ee28a16dfe1b4fc9e1aa5352ce3fef
|
|
BLAKE2b-256 checksum How to use checksums |
0d1ad4a60d667417ae25a4862fa11048800c8f00ef4d073b16f408f29637d109
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / ppicker-0.1.0-py3-none-win_amd64.whl
| Download URL | ppicker-0.1.0-py3-none-win_amd64.whl |
|---|---|
| Size | 508.5 kB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
0548886e630709f810a6ee1543488cf1ccc3155e7080cfa9bffa9e63958eb247
|
|
BLAKE2b-256 checksum How to use checksums |
41a2e22adb63f480c8d6b3ea503b61e282dfac10fad95c24d230b27dd84cb65f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / ppicker-0.1.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | ppicker-0.1.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 608.4 kB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
fdf929c402889319368b8cb15873677cf09df6ee63d7fa88ffe941ca9d244d62
|
|
BLAKE2b-256 checksum How to use checksums |
67e193cdec990de6c7d52b643686e020119d30d779c660aab81a5b1fd8145fa5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / ppicker-0.1.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | ppicker-0.1.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 600.7 kB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
5c0233763e273c91817f13935d2c3c7d9091a49fce1df25c384366fcb3ce0ec8
|
|
BLAKE2b-256 checksum How to use checksums |
8b7a1ee7dd302d6fab500656b46826db1cff91344facc2ed00ef11c624ad2e01
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / ppicker-0.1.0-py3-none-macosx_11_0_arm64.whl
| Download URL | ppicker-0.1.0-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 543.9 kB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
94d78d4f88b2550ae0f82506442e514094e12f648c48290e8a6803af07232fb3
|
|
BLAKE2b-256 checksum How to use checksums |
6d112b748b1b9b27b19e62ad6973d16858fd782005dab38497c6a64c9d6d9d44
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / ppicker-0.1.0-py3-none-macosx_10_12_x86_64.whl
| Download URL | ppicker-0.1.0-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 562.9 kB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
6df22755439e1235907d5ebfaf17d0ae1cd797e54ce594b71c34337c3b97fb4e
|
|
BLAKE2b-256 checksum How to use checksums |
95f484cc2868af4a91cc27cad2bf5930667140d54b9410ff1f955cb87bfe5830
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logSecurity for ppicker 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 6 files in this release have been uploaded with provenance metadata.
Attestation for ppicker-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.