How Developers Can Extend Albert with Custom Functionality

Updated

Albert supports three extension paths: native C++/Qt plugins, embedded Python modules, and CGI-based extensions in any language. The right choice depends on whether you need deep system integration, fast iteration, or language freedom. Albert's plugin-based architecture is explicitly designed so plugins can serve as either frontends or functional extensions, and the project ships APIs it describes as simple and easy to learn, plus utilities intended to accomplish common tasks with minimal code.

Choose your extension route

Route Best for What you write Trade-off to expect
Native plugin (C++/Qt) Tight integration with Albert's core and UI, performance-sensitive work A plugin against Albert's plugin API Most powerful, but requires C++/Qt familiarity and a build step
Embedded Python module Quick functional extensions, prototyping, logic-heavy tasks A Python module loaded by Albert Faster to iterate; depends on Albert's embedded Python support
CGI approach Reusing existing scripts or services, or working in a language other than C++/Python Any executable that follows the CGI request/response convention Language-agnostic, but adds a process boundary per invocation

A practical rule: start with Python if your extension is mostly logic and you want to iterate quickly; move to a native plugin if you need to shape Albert's interface or react at launcher speed; use CGI when the functionality already exists as a script or must be written in another language.

What "extension" means in Albert

Albert is a keyboard launcher written in C++/Qt, and its plugin system is the mechanism that lets it be either "your go-to app launcher or a full-blown system command palette." That framing matters for developers: an extension is not limited to adding search results. Plugins can create frontends (changing how Albert presents itself) or functional extensions (adding new actions and query handling). Decide which of the two you are building before choosing a route, because frontend work generally pushes you toward the native plugin API.

Start from the official developer surface

The project site is the entry point for API details, utilities, and contribution standards. The site states that Albert offers APIs "designed to be simple and easy to learn" and "a set of powerful utilities" to accomplish common tasks with minimal code — so the intended workflow is to lean on those utilities rather than reimplement plumbing.

A concrete way to begin, for example when you want a custom command that acts on the currently selected item:

  1. Define the trigger. Decide what the user types or what context (selected file, clipboard, active window) your extension responds to.
  2. Pick the route using the table above, based on whether you need UI control, speed, or another language.
  3. Implement against the documented API, using Albert's provided utilities for common operations instead of writing them yourself.
  4. Verify inside the launcher. Trigger your extension from Albert's query bar and confirm both the expected result and the behavior when nothing matches — the failure path is where most first extensions break.
  5. Check it against the bundled plugin standards. Albert describes its included plugins as peer-reviewed, actively maintained, and free of duplicates or broken code; matching that bar is the practical target if you intend to distribute your extension.

Use the bundled plugins as reference implementations

Albert ships "a curated collection of peer-reviewed, actively maintained plugins," described as working out of the box with no searching, no duplicates, and no broken code. For a developer, these are the most reliable worked examples of the API in use: read a bundled plugin that resembles your goal — a simple query handler, or one that surfaces system information — before writing your own. This is faster than starting from a blank file, and it keeps your code aligned with the conventions the project actually maintains.

Common sticking points

  • Choosing too heavy a route. Writing a native C++ plugin for logic that a Python module could handle adds build complexity for no benefit.
  • Ignoring the frontend/functional distinction. If your goal is to change how results are displayed, a CGI script will not get you there; that is plugin-API territory.
  • Skipping the utilities. The site emphasizes minimal code via provided utilities; hand-rolling common tasks tends to produce extensions that drift from project conventions.
  • Not testing the empty-result case. A launcher extension is judged as much by what it does when it has nothing to offer as when it succeeds.

Bottom line

Extend Albert by picking the lightest route that meets your need: Python for logic, native plugins for UI and performance, CGI for language freedom or reuse. Build on the documented APIs and utilities, model your code on the maintained bundled plugins, and test the no-match path before shipping.