Penguin

A native, minimal file manager for Linux and BSD. C++20 backend with a Qt 6 / Qt Quick (QML) frontend.

Requirements

• Linux or BSD
• A C++20 compiler
• CMake 3.21+ and a build tool (Ninja recommended)
• Qt 6.4+
• A freedesktop icon theme is recommended (e.g. Papirus) — Penguin falls back to its bundled icons when none is installed.

Building

Nix (recommended)

The repo ships a Nix devshell with the full toolchain and Qt setup:

nix develop
cmake --preset default
cmake --build build -j"$(nproc)"

Manual (CMake)

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"

Running

./build/penguin

The binary reads its configuration from ~/.config/penguin/config.json and writes a minimal default file on first launch. See CONFIG.md for the full reference.

Keyboard shortcuts

Most actions are on the keyboard. Ctrl+T opens a new tab, Ctrl+W closes the current one, Ctrl+L jumps to a folder and Ctrl+Q quits. F1 toggles dark mode and F5 reloads the current directory. Ctrl+1 switches to the icons view and Ctrl+2 to the details view. The icon grid zooms with Ctrl++ (or Ctrl+=) and Ctrl+-, and Ctrl+0 resets it to the default size. Return opens the selected item, and Backspace (or Ctrl+Up) goes up one level.

Right-click in the view for the context menu (new/close tab, view switching, navigation, dark mode, about, quit).

Search

The search pill below the tab bar filters the current directory case-insensitively as you type (file and folder names). Each tab has its own search state. Escape clears the search (or unfocuses it when already empty).

Configuration

Configuration lives in a single user-editable JSON file:

~/.config/penguin/config.json

It covers the icon theme, the default dark mode, and per-key color overrides. See CONFIG.md for the full reference and examples.

Testing

ctest --test-dir build --output-on-failure

Tests run headless (QT_QPA_PLATFORM=offscreen):

• smoke — the app boots and quits cleanly.
• nav (debug builds only) — exercises navigation, history, tab open/close staleness, zoom clamping and search filtering.

A few debug-only environment variables support headless pixel verification. PENGUIN_GRAB saves an offscreen screenshot to the given path before the app quits, and PENGUIN_MODE set to list starts the app in details view. The navigation probe PENGUIN_NAV_REPRO opens /etc and resizes the view, and PENGUIN_ZOOM plus PENGUIN_FILTER pick the zoom level and search filter it uses. The PENGUIN_NAV_REPRO variables only exist in debug builds.