Skip to main content

ppicker

ppicker: every project with the editor it was last opened in

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.

Searching for a project

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.

Choosing an editor

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.

A project remembered with PyCharm

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.

Switching a project's editor with Ctrl-e

Use rofi, wofi or fuzzel instead

If you already have a launcher you like, use it for the picking:

pp menu

Picking a project in rofi

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

Choosing an editor in rofi

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)

Source distribution for ppicker 0.1.0
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)

Table of built distributions (wheels) for ppicker 0.1.0
File Actions
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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Security 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.

Select from 6 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page