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/vicinaehq/vicinae 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 — Single-maintainer risk — review before adopting

• Last commit 1d ago
• 11 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 82% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{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 vicinaehq/vicinae repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/vicinaehq/vicinae.

What it runs against: a local clone of vicinaehq/vicinae — 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 vicinaehq/vicinae | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of vicinaehq/vicinae. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/vicinaehq/vicinae.git
#   cd vicinae
#
# 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 vicinaehq/vicinae and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 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 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/vicinaehq/vicinae"
  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).

Vicinae is a high-performance native desktop launcher written in C++ with Qt/QML frontend that provides keyboard-first access to apps, files, clipboard history, and system actions. It's extensible via a TypeScript/React SDK with a Raycast-compatible API, allowing reuse of existing Raycast extensions on Linux/macOS/Windows with minimal modification. Hybrid native + web architecture: core launcher engine in C++/Qt (CMakeLists.txt, source in src/), QML UI layer for rendering (QML files), TypeScript extension SDK (packages/api or similar in dependencies). Extensions are bundled TypeScript projects that communicate via extension API. Extra configurations in extra/config.jsonc and extra/extension-boilerplate/ provide templates.

Developers and power users who want fast, keyboard-driven desktop shortcuts and custom automation. Extension developers familiar with Raycast or React/TypeScript who want to build search-focused plugins for Vicinae or port existing Raycast extensions.

Actively developed with pre-release maturity (pre-v1.0 as stated in README breaking changes section). Strong CI/CD setup (6 GitHub workflows including build, release, Nix support, and API deployment). Main languages are C++ (3.8M LOC) and QML (388K LOC), indicating substantial native implementation. Breaking changes expected until v1.0.

Pre-v1.0 status means breaking changes between releases (explicitly acknowledged in README). Depends on multiple C++ libraries (Qt6, Keychain, LayerShell, KF6) and TypeScript ecosystem, increasing maintenance surface. Single primary author evident from repository structure. No test directory visible in top 60 files, suggesting limited automated test coverage.

Active releases with GitHub workflows for AppImage builds, API reference deployment (api-release.yml), and Nix packaging. Extension API is stabilizing with compatibility modes (dmenu, Raycast). Recent work visible in format.yaml and .qmlformat.ini suggests UI code refactoring and standardization.

git clone https://github.com/vicinaehq/vicinae.git && cd vicinae && cmake -B build && cmake --build build. Or using Nix: nix flake show followed by nix develop (based on default.nix and .envrc).

Daily commands: cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build && ./build/vicinae. For development: make dev (Makefile present). For extensions: vici develop (custom CLI tool, likely in bin/vici).

• CMakeLists.txt: Root build configuration; defines all dependencies, Qt6/KF6 integration, and extension API compilation.
• cmake/ExtensionApi.cmake: Configures TypeScript extension SDK build and embedding; critical for understanding extension lifecycle.
• extra/extension-boilerplate: Template and reference implementation for creating new extensions; shows expected structure and dependencies.
• extra/schemas/extension.json: JSON schema for extension manifests; defines all valid extension configuration fields and capabilities.
• .clangd: C++ language server configuration; essential for IDE setup and code navigation in native backend.
• default.nix: Reproducible development environment; defines exact versions of all dependencies for Nix users.
• extra/config.jsonc: Default launcher configuration example; shows all built-in modules (calculator, clipboard, emoji, etc.) and their setup.

Core launcher: src/core/ (inferred, C++ logic). UI: src/ui/ or qml/ directory (QML components). Extensions: extra/extension-boilerplate/ provides template; study @vicinae/api in dependencies. Settings/config: extra/config.jsonc. Add new commands by extending extension manifests following extra/schemas/extension.json schema.

Pre-v1.0 API instability: extension manifests and @vicinae/api may change between releases—check CHANGELOG before upgrading. CMake requires specific KF6 and Qt6 versions (see cmake/KF6.cmake, cmake/Utils.cmake); missing or mismatched versions cause silent build failures. TypeScript extension build uses custom 'vici' CLI tool (referenced in package.json scripts) which must be installed separately. QML formatting enforced via .qmlformat.ini; running make format will rewrite unformatted QML without warning. Wayland support conditional (cmake/Wayland.cmake); X11-only systems may have feature gaps.

• Raycast Extension API Compatibility Layer — Vicinae's core differentiator is reusing Raycast extensions via API emulation; understanding how type signatures and lifecycle hooks map between platforms is essential for porting extensions.
• Qt/QML Declarative UI with C++ Backend — Vicinae splits rendering (QML) from logic (C++), a pattern crucial for understanding how launcher state flows from backend to UI and vice versa.
• TypeScript-to-Binary Extension Bundling — Extensions are compiled TypeScript bundles embedded in the launcher; understanding Figura/Glaze cmake modules reveals how JS gets packaged as native assets.
• Wayland Protocol Support (XDG Layer Shell) — Vicinae uses qt-wayland and LayerShell for modern Linux display servers; critical for window management and input handling on Wayland vs X11.
• Nix Flakes for Reproducible Builds — default.nix and flake setup enable pin-able dependency versions; learning Nix conventions helps contributors understand the build environment and CI setup.
• CMark Markdown Embedding — cmake/CMark.cmake suggests documentation or help text is compiled into the binary; affects how launcher help/docs are versioned and deployed.
• Global Clipboard Manager State Persistence — Clipboard history module (visible in features) requires efficient querying and persistence; understanding its cache/index strategy informs performance optimization.

• raycast/extensions — Official Raycast extension store; Vicinae aims for API compatibility to reuse these plugins directly.
• davatorium/rofi — Alternative Linux launcher (dmenu-inspired); Vicinae explicitly supports dmenu compatibility mode for cross-launcher portability.
• vicinaehq/extensions — Official Vicinae extension repository; primary source for curated third-party launcher extensions and themes.
• NixOS/nixpkgs — Vicinae is packaged in nixpkgs; nix flake and default.nix enable Nix-based deployment and reproducible builds.
• albertlauncher/albert — Cross-platform application launcher (Qt-based like Vicinae); alternative for understanding native Qt launcher architecture.

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 extension schema validation tests for package.json

The repo has an extension.json schema (referenced in extra/extension-boilerplate/assets/package.json) but no visible test suite validating that extensions conform to it. New contributors could add Jest/Vitest tests that validate the schema against the boilerplate and sample extensions, catching malformed metadata early.

• [ ] Create tests/extension-schema.test.ts to validate extension.json against the schema at extra/schemas/extension.json
• [ ] Test the boilerplate config at extra/extension-boilerplate/assets/package.json against the schema
• [ ] Add CI step in .github/workflows/build.yaml or new .github/workflows/extension-validation.yaml to run schema tests on PRs
• [ ] Document in CONTRIBUTING.md that extension changes must pass schema validation

Add CMake integration tests for extension build process

CMakeLists.txt orchestrates the build but there are no visible tests for cmake/ExtensionApi.cmake and cmake/Figura.cmake which appear to handle extension compilation. New contributors could add tests verifying extensions build correctly with the vici build command.

• [ ] Create tests/cmake/extension-build.test.sh to validate the extension build pipeline referenced in cmake/ExtensionApi.cmake
• [ ] Test that the boilerplate extension builds successfully with sample configurations
• [ ] Add test execution to .github/workflows/build.yaml after the CMake configuration step
• [ ] Document expected build outputs in CONTRIBUTING.md

Implement GitHub Actions workflow for extension linting and formatting

The repo has .github/workflows/format.yaml for the main codebase but no automated linting for extensions themselves. The boilerplate has 'lint': 'vici lint' in package.json scripts but no CI enforces this. New contributors could create a workflow that validates all contributed extensions.

• [ ] Create .github/workflows/extension-lint.yaml that runs on PRs modifying files under extra/extension-boilerplate/ or docs/extensions/
• [ ] Configure the workflow to run 'npm run lint' and 'npm run format --check' for extensions
• [ ] Add a check that validates biome configuration matches .biomejs/biome settings across extensions
• [ ] Add workflow status badge to CONTRIBUTING.md extension guidelines

• Add TypeScript tests for extension SDK (@vicinae/api): no test/ directory visible in extension-boilerplate; create Jest setup and tests for core API methods (search, actions, preferences) as validation harness.
• Document command palette / fallback command syntax: README mentions 'fallback commands' and 'dmenu compatibility mode' but extra/config.jsonc lacks inline examples; add commented examples for each built-in module.
• Improve error messages in extension validation: cmake/ExtensionApi.cmake likely has silent failures when extension.json is malformed; add JSON schema validation step with human-readable diagnostics.

The Vicinae extension boilerplate demonstrates reasonable security practices with a focus on modern tooling (Biome, TypeScript) and schema validation. However, there are opportunities for improvement: (1) Dependency version pinning could be more explicit for reproducible builds, (2) the placeholder-based configuration requires careful handling to prevent injection, and (3) the GitHub schema reference should be hardened to prevent MITM attacks. No critical vulnerabilities were identified in the visible configuration. The codebase follows good practices by using a schema for extension validation and providing a TypeScript-based SDK. Ensure that runtime extension loading mechanisms validate and sandbox extension code appropriately.

• Medium · Outdated Biome Dependency — extra/extension-boilerplate/package.json. The extension boilerplate specifies @biomejs/biome version 2.3.2 as a fixed dependency. This may not receive security updates automatically. Biome is a linting and formatting tool that could potentially be exploited if vulnerabilities are discovered. Fix: Consider using a caret (^) or tilde (~) version specifier to allow for automatic security updates: '@biomejs/biome': '^2.3.2' or regularly audit and update dependencies.
• Medium · Unversioned TypeScript Dependency — extra/extension-boilerplate/package.json. TypeScript is specified with a caret version (^5.9.2), which allows for minor and patch updates. While this enables security patches, TypeScript itself is typically not a security risk vector. However, ensure compatibility with the build pipeline. Fix: Monitor TypeScript releases for any security-related updates and test extensions after updates.
• Low · Extension API Version Binding — extra/extension-boilerplate/package.json. The @vicinae/api dependency is set to '%VICINAE_VERSION%' as a placeholder. This suggests the actual version is injected at build/template time. If the version resolution mechanism is insecure or misconfigured, extensions could load incompatible or malicious API versions. Fix: Ensure the version injection mechanism validates and uses only trusted sources. Implement integrity checks (e.g., SRI hashes) for the API package.
• Low · Schema Reference Over HTTPS — extra/extension-boilerplate/package.json. The package.json schema references a URL on GitHub: 'https://raw.githubusercontent.com/vicinaehq/vicinae/refs/heads/main/extra/schemas/extension.json'. If this reference is not cached or validated locally, it could be vulnerable to MITM attacks or schema manipulation. Fix: Cache the schema locally, verify its integrity with a hash, or use a pinned commit/release reference instead of 'main' branch.
• Low · Placeholder Substitution in Config — extra/extension-boilerplate/package.json. The package.json boilerplate uses placeholder tokens (%NAME%, %TITLE%, %DESCRIPTION%, %AUTHOR%, %COMMAND_LIST%, %VICINAE_VERSION%) that are substituted at generation time. If the substitution mechanism is not properly validated, it could introduce injection vulnerabilities. Fix: Ensure placeholder substitution is performed using a safe templating engine with proper escaping. Validate all user inputs before substitution.
• Low · Missing Security Headers in Workflow Configuration — .github/workflows/. The GitHub Actions workflows (.github/workflows/) are not fully visible, but as a launcher that handles user input and extensions, ensure CI/CD pipelines sign artifacts and verify integrity of released binaries. Fix: Implement code signing for releases, enable branch protection, require PR reviews, and use GitHub's OpenID Connect for trusted deployments.

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.