If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/albertlauncher/albert shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Solo project — review before adopting

• Last commit 5w ago
• Other licensed
• CI configured
• Tests present
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live albertlauncher/albert repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/albertlauncher/albert.

What it runs against: a local clone of albertlauncher/albert — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in albertlauncher/albert | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 67 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of albertlauncher/albert. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/albertlauncher/albert.git
#   cd albert
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of albertlauncher/albert and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "albertlauncher/albert(\\.git)?\\b" \\
  && ok "origin remote is albertlauncher/albert" \\
  || miss "origin remote is not albertlauncher/albert (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 67 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~37d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/albertlauncher/albert"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Albert is a plugin-based, desktop-agnostic C++/Qt keyboard launcher that provides fast command execution and application searching across Linux, macOS, and other Unix-like systems. It combines a lightweight core (written in C++ with Qt) with a modular plugin architecture to enable extensible search handlers, custom query processors, and frontend rendering, making it a flexible alternative to Spotlight (macOS) or Ulauncher (Linux). Monolithic application with layered architecture: include/albert/ contains public plugin interfaces (extension.h, generatorqueryhandler.h, globalqueryhandler.h, frontend.h); core application logic in unlisted src/ directory; CMake-based build system (CMakeLists.txt + cmake/ macros for platform-specific bundling); dist/ contains packaging for Flatpak, macOS bundles, and XDG desktop entries.

Linux/macOS desktop power users and developers who want a fast, keyboard-driven application launcher with custom extensions; plugin developers building search indexers, terminal integrations, or custom frontends; contributors to open-source desktop infrastructure.

Production-ready and actively maintained: tagged releases visible in GitHub, Docker CI pipeline present (.github/workflows/ci.yml), multi-distribution support (Arch, Fedora, Ubuntu Dockerfiles), community presence (Telegram + Discord), and OBS package building integration. Recent activity evident from CHANGELOG.md and Flatpak packaging (dist/flatpak/org.albertlauncher.Albert.yml). Verdict: stable, actively developed, suitable for production use.

Single primary maintainer (manuelschneid3r) based on OBS and git history patterns creates succession risk. Plugin-based architecture means third-party extensions can break with core updates (no semantic versioning visible in CMakeLists.txt). Desktop environment coupling (X11/Wayland/macOS handling) introduces platform-specific bugs. Qt dependency version constraints not visible in snippet, but major Qt version upgrades historically cause breaking changes.

Active maintenance with Docker-based CI (ubuntu.Dockerfile, arch.Dockerfile, fedora.Dockerfile suggest multi-distro testing), Flatpak packaging refinement (dist/flatpak/), and pre-commit hooks (.pre-commit-config.yaml indicates code quality tooling). CHANGELOG.md and git workflows suggest regular releases. No breaking API changes visible in the include/ headers, indicating stable plugin interface.

git clone https://github.com/albertlauncher/albert.git && cd albert && mkdir build && cd build && cmake .. && make && ./albert (or see dist/ Dockerfiles for containerized build examples: docker build -f .docker/ubuntu.Dockerfile .)

Daily commands: cmake .. && make && ./albert (see .docker/ for OS-specific build: Ubuntu: apt install cmake qt5-default libqt5sql5 libqt5concurrent5; Arch: pacman -S cmake qt5-base)

• include/albert/extension.h: Base interface for all plugins; understanding this is mandatory for plugin development
• include/albert/generatorqueryhandler.h: Synchronous query handler interface; most common extension point for search backends
• include/albert/asyncgeneratorqueryhandler.h: Async query handler for blocking operations (network, I/O) without freezing UI
• CMakeLists.txt: Root build configuration; defines dependencies, targets, and platform-specific rules
• cmake/albert-macros.cmake: CMake helper macros for plugin creation and platform-specific bundling
• .github/workflows/ci.yml: CI pipeline definition; shows test, build, and packaging steps for each platform
• dist/xdg/albert.desktop: Desktop entry metadata; defines how Albert integrates into Linux desktop environments

Plugin development: extend include/albert/extension.h and one of generatorqueryhandler.h / asyncgeneratorqueryhandler.h / globalqueryhandler.h; Frontend changes: implement frontend.h interface; Core query logic: modify unlisted src/ files (not visible in snippet, but inferred from handlers); Packaging: edit .docker/, dist/, cmake/; Tests: likely in unlisted tests/ or src/test directories.

Qt version constraints likely in CMakeLists.txt (not shown in snippet) — building on Qt6 may break; X11/Wayland compatibility depends on runtime environment and may require XCB or Wayland libraries; plugin ABI is tied to Qt version, so plugins built against Qt5.15 won't load in Qt6; macOS requires code signing and notarization for distribution (see dist/macos/); Flatpak sandboxing may block plugins from accessing certain system resources without explicit permissions in org.albertlauncher.Albert.yml.

• Plugin Architecture / Interface Segregation — Albert's extensibility relies entirely on well-designed plugin interfaces (extension.h, generatorqueryhandler.h); understanding how to extend without modifying core is critical for contributors and plugin authors
• Asynchronous Query Handling / Non-blocking I/O — asyncgeneratorqueryhandler.h prevents launcher UI freezes during network/disk queries; essential for responsive launcher design and understanding why the async variant exists
• Desktop Entry Specification (.desktop files) — desktopentryparser.h handles Linux desktop integration; understanding .desktop files is critical for cross-desktop compatibility and plugin discovery
• Cross-Platform Qt Application Development — Albert targets Linux, macOS, and Unix via Qt; understanding Qt's platform abstraction (QDesktopServices, QSystemTrayIcon, etc.) is essential for native integration
• CMake Build System & Target Management — CMakeLists.txt + cmake/ subdirectory handle multi-platform builds, plugin linking, and bundling (especially macOS .app generation); required knowledge for build system modifications
• Keyboard Event Interception & Global Shortcuts — Albert's core function is intercepting global hotkeys (typically Alt+Space or Cmd+Space); this likely uses X11/Wayland APIs on Linux or NSEvent on macOS, not visible in headers but fundamental to launcher operation
• Icon Abstraction & Caching — icon.h abstracts icon loading to avoid redundant disk/resource lookups; understanding lazy-loading and caching patterns prevents performance regressions in search result rendering

• davatorium/rofi — Similar lightweight window/launcher switcher for X11; alternative in the same desktop automation space
• anarcat/albert-plugins — Community plugin repository; shows real-world extensions and use cases for Albert's plugin architecture
• SwiftLaunchBar/Quicksearch — macOS-native launcher; shares similar keybinding-driven UX but shows platform-specific launcher design patterns
• Qt-Creator/Qt-Creator — Uses similar CMake + Qt5 plugin architecture and cross-platform C++ patterns that Albert borrows

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for plugin loader and metadata parsing

The repo has extensive plugin infrastructure (include/albert/pluginloader.h, pluginmetadata.h, plugininstance.h, pluginprovider.h) but no visible test files in the repo structure. Plugin loading is critical for Albert's functionality. Adding unit tests would catch regressions in plugin discovery, validation, and initialization across different platforms.

• [ ] Create tests/unit/plugin/ directory structure
• [ ] Write tests for PluginLoader class covering plugin discovery and loading scenarios
• [ ] Write tests for PluginMetadata parsing (especially .desktop file parsing via desktopentryparser.h)
• [ ] Write tests for PluginInstance lifecycle and dependency resolution
• [ ] Integrate tests into CMakeLists.txt and CI workflow (.github/workflows/ci.yml)

Add query handler interface tests covering all handler types

Albert has multiple query handler types (GeneratorQueryHandler, AsyncGeneratorQueryHandler, IndexQueryHandler, FallbackHandler, GlobalQueryHandler) in include/albert/. These are core to Albert's plugin system but lack visible test coverage. Adding comprehensive tests would ensure handlers behave correctly across sync/async contexts and different match scenarios.

• [ ] Create tests/unit/queryhandlers/ directory
• [ ] Write test fixtures for each QueryHandler type (generator, async generator, index, fallback, global)
• [ ] Test handler registration, query execution, and result matching
• [ ] Test QueryContext and QueryExecution interaction with handlers
• [ ] Add tests to CMakeLists.txt and verify in CI pipeline

Add platform-specific integration tests for desktop entry and icon resolution

The repo includes DesktopEntryParser and Icon handling (include/albert/desktopentryparser.h, icon.h) which are platform-specific and critical for Linux desktop integration. The docker files (.docker/) suggest multi-platform testing capability. Adding integration tests would catch breakage across Ubuntu, Fedora, and Arch before release.

• [ ] Create tests/integration/desktop/ directory
• [ ] Write tests parsing .desktop files from dist/xdg/albert.desktop and common system locations
• [ ] Write icon resolution tests covering theme lookups and fallbacks
• [ ] Create docker-based test scripts in .docker/ for each distribution
• [ ] Add integration test stage to .github/workflows/ci.yml to run in docker containers

• Add unit tests for desktopentryparser.h: the desktop entry parser (used for .desktop file scanning) has no visible test coverage in the file list; create test cases in a new tests/desktopentryparser_test.cpp for edge cases (malformed entries, special characters in keys).
• Document the plugin interface versioning scheme: include/albert/extension.h lacks clear documentation on backward compatibility; add a PLUGIN_API_VERSION constant and update CONTRIBUTING.md with migration guide for plugins across Albert versions.
• Create a minimal example plugin template: dist/ lacks a reference plugin implementation; add dist/example-plugin/ with CMakeLists.txt, a simple query handler extending asyncgeneratorqueryhandler.h, and README showing how contributors can scaffold new plugins.

The Albert launcher codebase shows moderate security posture with several areas requiring attention. The primary concerns revolve around the plugin loading system, URL handling, desktop entry parsing, and network operations. While no hardcoded secrets or obvious injection vulnerabilities were identified in the file structure, the dynamic plugin system and desktop entry parsing are potential attack vectors. The codebase would benefit from implementing explicit security controls for plugin validation, URL sanitization, and network security. Regular security audits of the plugin ecosystem and dependency updates are recommended. The project's use of GitHub Actions CI/CD is positive, but no visible security scanning tools (SAST/DAST) are evident in the workflow configuration.

• Medium · Potential Plugin Loading Security Risk — include/albert/pluginloader.h, plugins/. The codebase includes a plugin system (pluginloader.h, extensionplugin.h) that dynamically loads plugins. Without explicit security validations, this could allow loading of malicious plugins if plugin directories are writable by untrusted users or if plugin signatures are not verified. Fix: Implement plugin signature verification, restrict plugin directory permissions (read-only for non-root users), validate plugin metadata before loading, and document plugin security requirements.
• Medium · URL Handler Implementation Security Concerns — include/albert/urlhandler.h. The urlhandler.h suggests URL handling capabilities. Improper URL validation or sanitization could lead to injection attacks, open redirects, or execution of unintended protocols (e.g., file://, about:, javascript://). Fix: Implement strict URL validation using allowlists for protocols, sanitize all URL inputs, use safe URL parsing libraries, and avoid shell execution of URLs.
• Medium · Desktop Entry Parser Potential Vulnerability — include/albert/desktopentryparser.h. The desktopentryparser.h component parses .desktop files which may contain arbitrary commands. If the parser doesn't properly sanitize or validate desktop entry files, it could be exploited to execute arbitrary code. Fix: Implement strict validation of .desktop file syntax, sanitize Exec fields, use safe command execution (avoid shell interpretation), and validate file sources before parsing.
• Medium · Network Utility Without Visible TLS Validation — include/albert/networkutil.h, include/albert/oauth.h. The presence of networkutil.h and oauth.h suggests network operations. The file structure doesn't clearly indicate TLS/SSL certificate validation, certificate pinning, or secure credential handling. Fix: Ensure proper TLS validation is implemented, use certificate pinning for sensitive connections, validate all SSL/TLS certificates, store OAuth tokens securely (not in plaintext), and use secure storage mechanisms.
• Low · Logging May Expose Sensitive Information — include/albert/logging.h. The logging.h header suggests logging functionality. Without proper controls, sensitive information (API keys, OAuth tokens, user queries) could be logged and exposed. Fix: Implement log filtering to exclude sensitive data, use secure logging levels, store logs with restricted access, and document what should never be logged.
• Low · Download Functionality Security — include/albert/download.h. The download.h module could potentially download content without proper validation, leading to MITM attacks or malicious file downloads if not properly secured. Fix: Validate downloaded file signatures/checksums, implement secure download paths, use HTTPS exclusively, implement size limits, and validate file types after download.
• Low · Notification System Potential XSS — include/albert/notification.h, include/albert/messagebox.h. The notification.h and messagebox.h components may display user-generated or plugin-generated content. If not properly escaped, this could lead to injection vulnerabilities. Fix: Escape all HTML/formatting content in notifications, use safe text rendering, implement content validation, and avoid executing scripts in notification content.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.