Cerebro: an Electron launcher built around plugins and a background process

The problem Cerebro solves, and who it is actually for

Cerebro is a launcher: a window you summon with a keyboard shortcut, type into, and get results from. The README describes the intended audience indirectly, through the plugin list. Core plugins cover web search, launching applications by name, navigating the file system with previews, a calculator, and a smart converter that understands inputs like `15$`, `150 рублей в евро` and `100 eur in gbp`. That set is aimed at people who already work from the keyboard and want one entry point instead of a browser tab, a file manager and a calculator app.

The second audience is plugin authors. The repository links to create-cerebro-plugin for plugin development and to an external awesome-cerebro list for discovery, which tells you the project expects third parties to supply most of the interesting behavior. If you are evaluating Cerebro as a finished product, you are evaluating the core plugins plus whatever the community has written. The README does not enumerate that second set; it points at the awesome list instead.

Two renderer processes, and why that shapes the plugin model

The contributing section is the most informative part of the repository. Cerebro is an Electron app with a main process and a renderer process, and the project adds a third file: `app/main.development.js` as the main process, `app/main/main.js` as the main renderer, and `app/background/background.js` as a secondary renderer. The README states the reason plainly: keeping the main renderer responsive and avoiding a blocked UI during long tasks.

The mechanism is message passing. When a long task is needed, the app sends a message to the background process, which runs it asynchronously and sends a message back when it finishes. Plugins use this path: their `initializeAsync` method executes in the background process. That is a real architectural constraint, not a detail. A plugin whose initialization does blocking I/O will not freeze the launcher window, but it also cannot touch the UI directly during that phase, because it is not running in the renderer that owns the UI.

Everything is bundled and transpiled with Webpack and Babel, and the build process is managed by electron-builder. That combination explains the packaging scripts in package.json: `build-main` targets `webpack.config.electron.js`, `build-renderer` targets `webpack.config.production.js`, and `build` runs both in parallel.

Installing Cerebro and running a first search

The README's first instruction is to download the latest version from the releases page. If there is no installer for your OS, it directs you to build from source. On Linux it adds a step: grant execution permission to the file you downloaded.

sudo chmod +x <path to the executable>

After that, an AppImage is started by running it directly, and a deb package is installed with dpkg.

dpkg -i <path to the executable>

The README notes that some machines need elevated privileges for these commands. Once installed, the default shortcut is `ctrl+space` to show the window. You can change it by clicking the icon in the menu bar and selecting "Preferences...".

The first useful thing to try is the plugin manager, which is itself a search query. Type this into the search bar to manage and install plugins:

plugins <plugin-name>

From there, the core plugins are already present. Type an application name to launch it, a path such as `~/Dropbox/passport.pdf` to navigate the file system with previews, or an expression like `100 eur in gbp` to convert. Results can be copied with `ctrl+c`, selected directly with `ctrl+1...9`, or walked with vim-like keys via `ctrl+[hjkl]`, with `ctrl+o` to select. Themes are switched by opening the window and typing `Cerebro Settings`; the README states that Light and Dark ship out of the box.

Building from source, and the node version trap

The build path is short but has a known failure mode the README documents. Prerequisites are Node.js (>= 16) and yarn. Clone, enter the directory, install dependencies, then run the dev script.

git clone https://github.com/cerebroapp/cerebro.git cerebro
cd cerebro
yarn
yarn run dev

The README warns that `yarn run dev` requires a node version >=16.x. Two errors are called out. The first is `AssertionError: Current node version is not supported for development` during the npm postinstall step, which the README says means you must check the node and npm versions in the `devEngines` section of package.json and install the right ones. The second is `Uncaught Error: Module version mismatch`, caused by native extensions built against a node version different from the one bundled with Electron; the prescribed fix is `yarn --force`.

If you want a distributable rather than a dev run, the packaging script is `yarn package`, which package.json defines as the build followed by electron-builder. Note the README's remark that CI uses `yarn build` instead, because a separate action packages and publishes the executables. Those are two different code paths, and only one of them is what produces the released binaries.

The config file, and the warning around it

Cerebro stores settings in a JSON file whose location depends on the OS. On Windows it is `%APPDATA%/Cerebro/config.json`; on Linux, `$XDG_CONFIG_HOME/Cerebro/config.json` or `~/.config/Cerebro/config.json`; on macOS, `~/Library/Application Support/Cerebro/config.json`.

The README attaches a warning to this file: a bad configuration can break Cerebro, and if you are not sure what you are doing, do not edit it directly. That is an unusually blunt statement for a project's own documentation, and it should be read as a design limitation. There is no documented schema for config.json, no validation step described, and no stated recovery path if you corrupt it. The Preferences UI exists precisely so you do not have to touch the file. If you are scripting configuration changes across machines, this is the weakest part of the project to build on.

Where Cerebro is the wrong tool

The clearest failure mode is platform coverage. The README's usage section opens by telling you to download from releases, then immediately concedes that there may be no installer for your OS and sends you to the build instructions. A launcher that you must compile yourself is not a launcher most people will install.

The second limitation is the plugin ecosystem as a dependency. Cerebro's core plugins are modest: search, app launch, file navigation, calculator, converter. Anything beyond that lives in third-party plugins, and the README does not describe plugin compatibility guarantees, a plugin API version, or what happens when a plugin is built against a different Cerebro release. If your workflow depends on a specific plugin, you are depending on a repository the README does not control.

The third is the release cadence visible in the data. The most recent listed release is v0.11.0 from 2023-02-09, and package.json still reports version 0.11.0. The repository's last push is 2026-10-30, so work continues, but shipped versioned releases have not moved in a long time. If your adoption criteria include a recent tagged release with changelog notes, Cerebro does not meet them on the evidence here.

How Cerebro differs from a system-native launcher

The obvious alternative is the launcher your operating system already ships, such as Spotlight on macOS or the application menu search on Windows and GNOME. The difference is not speed or polish; it is extensibility and where the code runs.

A system launcher is closed to you. You get the search sources the vendor chose, and adding a new one means writing a separate tool that the launcher happens to index. Cerebro inverts that. Its plugin system is the product, plugins are JavaScript, and the project publishes a separate create-cerebro-plugin repository so you can author one. The trade-off is everything that comes with a JavaScript runtime: an Electron bundle, node version requirements, native module rebuilds, and the `yarn --force` workaround when those modules mismatch.

So the comparison is not "which finds files faster". It is whether you want a launcher you can modify. If you never intend to write or install a plugin, a system launcher gives you the same core capabilities with no build step and no node version to manage.

Licence, maintenance and upgrade cost

Cerebro is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. That is permissive and carries no copyleft obligation on your own code. This is a description of the licence text, not legal advice; if you are redistributing a modified build, have your own counsel read the LICENSE file in the repository root.

The maintenance picture is mixed and worth stating precisely. The repository is not archived, and its last push was on 2026-10-30, so the codebase is receiving changes. But the newest release listed is v0.11.0 from 2023-02-09, and package.json declares that same version. That gap between commits and tagged releases is the real upgrade cost: if you build from `master`, you are tracking unreleased code, and the README's release process requires manually updating the version in both `package.json` and `app/package.json` before publishing a GitHub release whose tag carries a `v` prefix. Nothing in the repository describes a migration guide between versions, so an upgrade means reading commits rather than release notes.

Editorial conclusion

Adopt Cerebro if you want a keyboard launcher you can extend in JavaScript and you are comfortable reading the repository to fill in what the README omits. Do not adopt it if you need a documented plugin API surface, a stated support policy, or installers guaranteed for every OS, since the README itself points you to build instructions when no installer exists for yours. Before committing, verify two things: that a release binary exists for your platform on the releases page, and that the node version on your machine satisfies the devEngines range in package.json, because the postinstall step fails with an assertion error when it does not.

Frequently asked questions

Official sources

1. cerebroapp/cerebro on GitHub
2. License: MIT
3. Project website
4. README
5. Releases