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.
Workspaces, not just folders
A project does not have to be a folder. You can add a workspace file too, and ppicker opens it the way the editor expects:
pp add ~/work/shop.code-workspace # a VS Code workspace
pp add ~/work/site.sublime-project # a Sublime Text project
pp scan ~/work --workspaces # also pick up workspace files while scanning
A workspace is named after its file (Shop Front) and marked with ◇ in the list; the details
panel says what kind it is.
A .code-workspace file means something only to VS Code, so ppicker offers only editors that can
open it. Enter uses the first VS Code editor in your ides, → lists just those (below, code
only: vim and PyCharm are left out), and Ctrl-e cycles only through them.
If none of your editors can open it, ppicker says which one to add instead of failing silently. A folder and a workspace file are separate entries, so one repository can appear as both.
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 = ["vscode", "pycharm", "zed"]
scan_dirs = ["/home/me/code"] # used by `pp scan` when you give no folder
Each entry is either a name ppicker knows, or a plain command.
Names: the same editor on every system
Editor commands are called different things on different systems: code on Linux, code.cmd on
Windows, codium, a flatpak... A name stands for a list of commands, and ppicker runs the first
one it finds on your PATH. So the same config works everywhere:
| Name | Tries, in order |
|---|---|
vscode |
code, code-insiders, codium, vscodium, the VS Code flatpak |
pycharm |
pycharm, pycharm-professional, pycharm-community, charm, pycharm64, the PyCharm flatpaks |
idea, webstorm, goland, rustrover, clion, phpstorm, rider, rubymine |
the usual launcher name of each (and its 64 variant) |
sublime |
subl, sublime_text, sublime-text |
zed |
zed, zeditor |
cursor, windsurf |
the same name |
If a name is not found you get an error that lists what was tried.
Plain commands
Anything else is run as written, for example code, idea, code -n or alacritty -e nvim.
Put a path with spaces in quotes: "C:\Program Files\Some Editor\editor.exe". ppicker recognises
the well-known commands (code, codium, cursor, subl, pycharm, ...) so it knows which
projects they can open.
Your own command list
If your install is somewhere unusual, or you want a different order, override a name (or define a
new one) in config.toml. The first command that exists is used:
[commands]
vscode = ['C:\Tools\VSCode\bin\code.cmd', "code"] # my install first, then whatever is on PATH
work = ["codium", "code"] # a new name, usable in `ides`
How a project is opened
A folder is opened as <editor> . from inside the folder. A workspace file is opened as
<editor> <file> (see Workspaces). The editor is started detached,
so it keeps running after ppicker exits.
Terminal editors such as vim or nvim need a terminal to run in. Use a command that starts one, for example
ides = ["vscode", "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 add ~/w/shop.code-workspace # add a workspace file instead of a folder
pp scan ~/code -t work # add every git repository in a folder
pp scan ~/code --workspaces # ...and the workspace files in it (one level down)
pp list # show projects with their editors (workspaces marked ◇)
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.
To keep both somewhere else (a portable install, or to try things out without touching your
real list), set PPICKER_HOME to a folder; ppicker then uses config/ and data/ inside it.
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.2.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.2.0.tar.gz | 276.2 kB | With provenance | Details for ppicker-0.2.0.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| ppicker-0.2.0-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details for ppicker-0.2.0-py3-none-win_amd64.whl |
| ppicker-0.2.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.2.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
| ppicker-0.2.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details for ppicker-0.2.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
| ppicker-0.2.0-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details for ppicker-0.2.0-py3-none-macosx_11_0_arm64.whl |
| ppicker-0.2.0-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details for ppicker-0.2.0-py3-none-macosx_10_12_x86_64.whl |
Total release size: 3.2 MB
Release files / ppicker-0.2.0.tar.gz
| Download URL | ppicker-0.2.0.tar.gz |
|---|---|
| Size | 276.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1baa4dd2fe40b2a3329aedf3c6fdbd8e5fe359382dbc4b4135454ddd9e31d40f
|
|
BLAKE2b-256 checksum How to use checksums |
b94bfeb45de1188330d5021d26afd30cf1e6643b435976911c153b953814667c
|
| 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 13, 2026.
Transparency logRelease files / ppicker-0.2.0-py3-none-win_amd64.whl
| Download URL | ppicker-0.2.0-py3-none-win_amd64.whl |
|---|---|
| Size | 527.6 kB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
b67d49ff6668b0f8f22175c0a706b8809b3ef25973e75867db5fdd44d65bb849
|
|
BLAKE2b-256 checksum How to use checksums |
713cec480d8826193a2223cff1ea6cfedc1510db126a9ff4e00b7f27226fadea
|
| 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 13, 2026.
Transparency logRelease files / ppicker-0.2.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | ppicker-0.2.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 628.4 kB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
c54709ccfe5bdcc81ff3848808102138dc4ed5321ba8c28a772d43d67d934c4e
|
|
BLAKE2b-256 checksum How to use checksums |
2d01b73064d27a55c301f426fc10c04f79705a6a7e49fe2a0cc801524b04a67e
|
| 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 13, 2026.
Transparency logRelease files / ppicker-0.2.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | ppicker-0.2.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 619.9 kB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
9452e76396751dc359759fe942ebd462e3a94ba684374aac6dd638ac6a588c35
|
|
BLAKE2b-256 checksum How to use checksums |
9899cfe0f4b59ae2a2ca2329530102ffcea836acf4a6558632a2a046b4e67ae0
|
| 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 13, 2026.
Transparency logRelease files / ppicker-0.2.0-py3-none-macosx_11_0_arm64.whl
| Download URL | ppicker-0.2.0-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 558.2 kB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
825ed79ccfad035176ffd800d5eba586d8b6b734315b98234125fa8adc4a4f17
|
|
BLAKE2b-256 checksum How to use checksums |
255923069657310eb040e7fe6d2c54e995457055dfc4bbf0d79d862feb1887b3
|
| 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 13, 2026.
Transparency logRelease files / ppicker-0.2.0-py3-none-macosx_10_12_x86_64.whl
| Download URL | ppicker-0.2.0-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 578.6 kB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
3c2063e63e03cf69905bcd4e63bcea40dc9f5be36f32bf243e4ba0d1e73e7d08
|
|
BLAKE2b-256 checksum How to use checksums |
90904bb939b5931ff8542b82ce997838146f83e3d13afc82af08eca67dcf2792
|
| 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 13, 2026.
Transparency logSecurity for ppicker 0.2.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.2.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 13, 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.