Vicinae: a native command palette with three extension paths

Ten built-in roles behind one keypress, and two of them undocumented

Out of the box Vicinae presents itself as app search, clipboard history, a text expander for snippets, file search, a browser tab switcher, an emoji picker, a calculator, a window and workspace switcher, a font browser, and a volume controller. Seven of those link out to their own page under docs.vicinae.com, covering clipboard, snippets, file search, the browser extension, emoji, calculator, and window management. The font browser and the volume controller are named as plain text with no link at all, so nothing in the repository points you at how either one is configured. That asymmetry is a fair signal when you are evaluating the palette: if font selection or output volume is the feature you actually want, you will be reading the running application rather than any guide.

Three extension paths, one store, and no compatibility floor

React and TypeScript extensions are the primary path and are described as compatible with the Raycast ecosystem, with in-app integration into both the Vicinae store and the Raycast store. Script commands are the second path, compatible with the Raycast feature of the same name and carrying what the project calls special Vicinae additions. The third is dmenu style menu creation, framed as the linux minimalist way, which the README links to docs.vicinae.com/dmenu. What none of the three descriptions tell you is the API version floor. There is no compatibility table, no list of which Raycast API surface the native side implements, and no note about what happens when an extension from the Raycast store imports a component the native side does not ship.

Two cmake lines configure the tree, a third launches it

The Makefile is explicitly limited to UNIX systems and states that on Windows you are expected to use cmake directly and the utility scripts in ./scripts. PRESET_OS is derived from uname -s, so Darwin picks the macos prefix and everything else picks linux, and each preset target appends one of -release, -dev, -preview, or -debug to that name. A development loop is two commands, and the build directory is the plain build/ path set by BUILD_DIR:

cmake --preset $(PRESET_OS)-dev -B $(BUILD_DIR)
cmake --build $(BUILD_DIR)

Launching the result is a third line, and both flags carry weight. --replace and --open are passed to the server:

$(BUILD_DIR)/bin/vicinae server --replace --open

Read that sequence as a source build, not as an install.

host-optimized bakes the compiling CPU into the binary

The host-optimized target skips the presets entirely and runs these two lines:

CXXFLAGS="${CXXFLAGS} -march=native" cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DLTO=ON -B build
cmake --build $(BUILD_DIR)

-march=native tells the compiler to emit instructions for the CPU doing the compiling, and link time optimization is switched on alongside it. The consequence is that the resulting binary runs on the machine that built it and on very little else. Handing it to a colleague with a different CPU, or baking it into a package on a build server, is where it breaks. This target also assumes Ninja is on your path, and it hardcodes build rather than using the $(BUILD_DIR) indirection the rest of the file relies on. For comparison, relwithdebinfo turns on -DBUILD_TESTS=ON, the only place in the visible Makefile where tests are switched on at all.

Translations are generated into src/server/translations, then diffed

Two targets treat the translation files as generated output rather than as hand-edited source. update-translations builds the debug preset and then drives the generator through cmake, writing the extracted strings back into the tree. check-translations depends on that target and then guards the result with a plain diff check:

cmake --preset $(PRESET_OS)-debug
cmake --build --preset $(PRESET_OS)-debug --target update_translations

git diff --exit-code -- src/server/translations

If the generated files drift, git diff exits non-zero and the target fails. The QML side has its own gate, all_qmllint, invoked through the same build directory:

cmake --build $(BUILD_DIR) --target all_qmllint

Formatting rules are versioned in the project rather than left to your editor, with .clang-format, .qmlformat.ini, .clang-tidy, and .clangd all at the root alongside .clang-format-ignore.

Nothing in the repository installs Vicinae on your machine

The README gives no install command to copy. The project's own answer to getting started is that everything you need is at vicinae.com, with Discord offered for questions. So your route to a running launcher is to follow vicinae.com or compile the source yourself with the targets above. On Windows there is no Makefile path at all, which is why the file hands that platform to cmake and the scripts in ./scripts. The top-level layout shows how much of this repository is build environment rather than application: default.nix, flake.nix, flake.lock, nix/, manifest.yaml, vendor/, cmake/, scripts/, src/, extra/, and figura/. FIGURA_CC is defined as build/bin/figura in the Makefile.

Packaging leans on a container image tag and a git-derived TAG

Two variables exist purely to satisfy packaging. APPIMAGE_BUILD_ENV_DIR is ./scripts/runners/appimage/ and APPIMAGE_BUILD_ENV_IMAGE_TAG is vicinae/appimage-build-env, which is a container image reference rather than anything built locally. The Nix files put a second path to the same binary alongside the CMake one, and TAG is computed as $(shell git describe --tags --abbrev=0), so a checkout with no reachable tags yields an empty TAG rather than a hard error. macOS carries its own bundle identity through APPLE_BUNDLE_ID := com.vicinaehq.Vicinae, and on that platform the calculator can be backed by SoulverCore, which the project credits by name.

The checkout cannot answer whether an extension will work

Extension documentation and the feature pages for clipboard, snippets, file search, emoji, calculator, and window management all live at docs.vicinae.com, with the site itself at vicinae.com. The repository carries almost none of it. That means the palette cannot be evaluated from a clone alone: you cannot read the extension API contract without leaving the checkout, and the README states plainly that questions go to Discord instead. Version drift is invisible from the source tree too. The last three releases are v0.29.2 on 2026-10-19, v0.29.1 on 2026-09-30, and v0.29.0 on 2026-09-18, so a checkout of main can be a different thing from what someone running the current release actually has installed.

Editorial conclusion

Vicinae suits someone on Linux or macOS who wants a native palette they can patch, a GPL-3.0 source tree they can build with cmake, and an extension model already compatible with Raycast, and who is willing to read docs.vicinae.com for the extension contract instead of expecting the repository to carry it. It is a poor fit if you plan to ship a binary compiled with -march=native. Before committing, check the three things this repository does not answer: which Raycast API surface the current release implements, how store extensions are versioned against the client, and whether the packaged builds your distribution ships match the tag you are reading about.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes