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/glzr-io/zebar 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 — Mixed signals — read the receipts

• Last commit 5w ago
• 19 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 73% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

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

What it runs against: a local clone of glzr-io/zebar — 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 glzr-io/zebar | 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 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 68 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "glzr-io/zebar(\\.git)?\\b" \\
  && ok "origin remote is glzr-io/zebar" \\
  || miss "origin remote is not glzr-io/zebar (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"

# 4. Critical files exist
test -f "packages/client-api/src/index.ts" \\
  && ok "packages/client-api/src/index.ts" \\
  || miss "missing critical file: packages/client-api/src/index.ts"
test -f "packages/client-api/src/providers/create-provider.ts" \\
  && ok "packages/client-api/src/providers/create-provider.ts" \\
  || miss "missing critical file: packages/client-api/src/providers/create-provider.ts"
test -f "packages/client-api/src/config/widget-config.ts" \\
  && ok "packages/client-api/src/config/widget-config.ts" \\
  || miss "missing critical file: packages/client-api/src/config/widget-config.ts"
test -f "packages/client-api/src/desktop/widgets.ts" \\
  && ok "packages/client-api/src/desktop/widgets.ts" \\
  || miss "missing critical file: packages/client-api/src/desktop/widgets.ts"
test -f "packages/client-api/src/config/widget-pack.ts" \\
  && ok "packages/client-api/src/config/widget-pack.ts" \\
  || miss "missing critical file: packages/client-api/src/config/widget-pack.ts"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 68 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~38d)"
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/glzr-io/zebar"
  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).

Zebar is a cross-platform desktop widget framework that uses native webviews to render customizable taskbars, desktop widgets, and popups written in HTML/CSS/TypeScript. It runs on Windows, macOS, and Linux, with a widget marketplace for distribution and a local development workflow using zpack.json manifests stored in ~/.glzr/zebar/. Monorepo structure: packages/desktop contains the main Rust application (webview host + system tray + marketplace client), crates/ holds reusable Rust libraries (komorebi-util for window management, shell-util for shell integration, systray-util for tray icon handling). TypeScript lives in packages/client-api and user widget packs. Desktop app is the Tauri-like orchestrator, widgets are loaded as HTML+JS bundles.

Desktop customization enthusiasts and developers who want to build lightweight, native-backed widgets without Electron's overhead. Contributors range from Rust systems programmers (working on packages/desktop and crates) to TypeScript/web developers creating widget packs in the marketplace.

Actively developed with a release pipeline (GitHub Actions: build.yaml, release.yaml, publish-crate.yaml) and marketplace distribution (MARKETPLACE.md). The workspace spans 335k lines of Rust and 186k lines of TypeScript, suggesting substantial maturity. CI/CD is configured but public metrics (stars, issue count) are not visible from this metadata—likely production-ready but assess adoption via the Discord community.

Dependency risk is moderate: heavy Windows API bindings (windows = 0.58 with extensive features), Tokio async runtime, and serde ecosystem create a complex surface. Single-maintainer risk appears present (glzr-io org structure suggests small core team). Breaking changes could occur during marketplace ecosystem growth; local widget packs are isolated but marketplace downloads live in %AppData%/zebar/downloads/ and must be manually copied to ~/.glzr/zebar/ to avoid override risk.

The repo shows active development with CI/CD pipelines for building, linting, and releasing. GitHub Actions workflows (build.yaml, release.yaml) indicate continuous deployment. The codebase includes marketplace infrastructure (MARKETPLACE.md) and a scaffold system for creating new widget packs ('My widgets' tab generation). Recent work appears focused on Windows integration (extensive windows-core/windows feature flags) and cross-platform stability.

git clone https://github.com/glzr-io/zebar.git
cd zebar
npm install
cargo build --release

Refer to CONTRIBUTING.md for platform-specific build steps and Node.js version (see .nvmrc). For widget development, use the Zebar GUI to create packs in ~/.glzr/zebar/ or scaffold via 'Create new pack'.

Daily commands: Dev build: cargo build (debug) or cargo build --release (optimized). Start Zebar desktop app via packages/desktop. Widget development: scaffold a pack in ~/.glzr/zebar/<pack-name>/, edit zpack.json, run template-specific build (e.g., pnpm build for Node.js templates). Tray icon launches GUI; GUI provides marketplace and widget management.

• packages/client-api/src/index.ts — Main entry point for the client API; exposes all public interfaces for widget configuration, providers, and desktop controls.
• packages/client-api/src/providers/create-provider.ts — Core provider factory pattern; understanding this is essential for adding new data providers (audio, battery, CPU, etc.).
• packages/client-api/src/config/widget-config.ts — Widget configuration schema and validation; defines how users declare and customize widgets.
• packages/client-api/src/desktop/widgets.ts — Widget lifecycle management and rendering; handles creation, updates, and destruction of widget instances.
• packages/client-api/src/config/widget-pack.ts — Widget pack loading and distribution; manages how widget bundles are discovered and loaded into Zebar.
• Cargo.toml — Workspace configuration for Rust crates; critical for understanding the desktop backend dependencies and build toolchain.
• .github/workflows/release.yaml — Release pipeline for multi-platform builds; essential for understanding how Windows, macOS, and Linux artifacts are generated.

• Widget Configuration Engine — Parse, validate, and apply user widget configs (YAML/JSON); discover

Add a New System Data Provider

1. Create provider type definitions in a new folder under providers/ (packages/client-api/src/providers/[provider-name]/[provider-name]-provider-types.ts)
2. Create the provider factory function that extends the base provider (packages/client-api/src/providers/[provider-name]/create-[provider-name]-provider.ts)
3. Export the provider from the providers index (packages/client-api/src/providers/index.ts)
4. Register the provider in the provider group factory for availability to widgets (packages/client-api/src/providers/create-provider-group.ts)

Add a New Configuration Option to Widgets

1. Update the widget config type definition to include new property (packages/client-api/src/config/widget-config.ts)
2. Update the JSON schema validator to validate the new property (packages/client-api/src/config/config-schemas.ts)
3. Handle the new property in the widget creation or update logic (packages/client-api/src/desktop/widgets.ts)

Add a New Shell Utility Command

1. Add shell command wrapper function to handle execution (crates/shell-util/src/shell.rs)
2. Export from the shell-util library root (crates/shell-util/src/lib.rs)
3. Call the utility from client-api desktop module as needed (packages/client-api/src/desktop/shell.ts)

Add a New Desktop Command (System Control)

1. Define new command type in desktop commands (packages/client-api/src/desktop/desktop-commands.ts)
2. Implement the command logic using platform-specific APIs (packages/client-api/src/desktop/desktop-commands.ts)
3. Expose via the public desktop API exported from index (packages/client-api/src/desktop/index.ts)

• Rust + Tauri — Cross-platform desktop app development with minimal memory footprint; native system integration (tray, window events, inter-process communication) for Windows/macOS/Linux
• TypeScript + Node.js — Frontend configuration and widget API; enables rapid iteration on widget marketplace and user-facing config schemas without recompiling backend
• Tokio async runtime — Efficiently manages concurrent polling of multiple system providers (CPU, battery, audio, keyboard) without thread explosion
• Windows crate (v0.58) — Direct Windows API bindings for audio endpoints, media controls, process diagnostics, and system information on Windows
• Serde + serde_json — Type-safe serialization of widget configs and provider data; validates user config against JSON schemas

• Rust backend + TypeScript frontend split

  • Why: Separate concerns: system integration (Rust) vs. user-facing UI/config (TypeScript)
  • Consequence: Requires IPC/RPC bridge; adds build complexity but enables faster iteration on widget marketplace and type-safe config validation

• Polling-based data providers instead of event-driven

  • Why: Simpler implementation; consistent update intervals; easier to reason about performance
  • Consequence: Slight latency in detecting system changes; fixed CPU cost per provider; must tune poll intervals per provider type

• Widget config file-based discovery vs. database

  • Why: Lower overhead; portability; git-friendly; users can easily version and share configs
  • Consequence: No real-time config hot-reload without restart; harder to implement fine-grained permissions or caching strategies

• Marketplace distribution via npm/GitHub releases

  • Why: Leverage existing ecosystem; reduces need for custom backend infrastructure; widgets are essentially npm packages
  • Consequence: Widgets must be pre-built; limits dynamic runtime plugins; increases distribution latency (requires publish cycle)

• Does not provide authentication or multi-user account management
• Not a general-purpose window manager (integrates with existing WMs like GlazeWM/Komorebi, does not replace them)
• Does not support real-time collaborative widget editing
• Does not include widget visual designer; users must write config files
• Not intended for headless/server environments (desktop-only)

No Electron: native webview host is custom; debug tooling differs from Electron (check .vscode/launch.json). Windows API complexity: extensive windows 0.58 feature flags are tightly coupled; changing them requires recompilation. zpack.json discovery is one-level deep only: ~/.glzr/zebar/pack-name/zpack.json works, but ~/.glzr/zebar/pack-name/subdir/zpack.json is silently ignored. Marketplace vs. local: ~/.glzr/zebar/ is user-editable; %AppData%/zebar/downloads/ is marketplace (copy, don't edit in place). Shell execution context: shell-util requires proper encoding setup (encoding.rs)—shell commands may fail silently if stdout encoding mismatches. Node.js version pinned: .nvmrc exists; widget templates require matching npm/pnpm.

• Native Webview Host — Zebar's core differentiator from Electron: using OS-native webview libraries (WKWebKit on macOS, WebView2 on Windows) instead of bundling Chromium reduces binary size and memory usage
• System Tray Integration (Systray) — Zebar lives in the system tray (crates/systray-util); right-click context menus, auto-start toggling, and icon state management are critical to user experience and require native OS integration
• IPC (Inter-Process Communication) — Rust backend communicates with TypeScript webview frontend via window messages or socket APIs; komorebi-util uses socket-based IPC to talk to external window managers
• Async Runtime (Tokio) — Zebar uses Tokio for concurrent task handling (webview message loops, marketplace downloads, shell command execution); understanding Tokio channels and spawn is essential for backend feature work
• Shell Detection & Execution (shell-util) — Widgets may execute shell commands to fetch data (e.g., system stats); shell-util detects user's shell, handles encoding (UTF-8 vs. legacy), and manages stdout capture without deadlock
• Workspace Dependency Resolution (Cargo workspaces) — This monorepo uses Cargo workspace with resolver = '2' to share dependencies (serde, tokio, windows) across packages/desktop and crates/*; understanding workspace.dependencies prevents version conflicts
• Windows API Feature Flags — windows 0.58 crate requires explicit feature flags (Win32_UI_WindowsAndMessaging, Win32_System_Com, etc.); adding/removing features requires careful coordination to avoid link errors in packages/desktop

• tauri/tauri — Tauri is the predecessor architecture pattern for native webview hosting; Zebar uses similar concepts (Rust backend, web frontend, tray integration) but specialized for widgets rather than apps
• electron/electron — Electron is the heavyweight alternative Zebar avoids; understanding Electron's IPC and preload patterns helps explain why Zebar chose native webviews and komorebi-util for lighter system integration
• glzr-io/glazewm — Sibling project in glzr-io org; GlazeWM is a Windows window manager that Zebar widgets can integrate with via komorebi-util, enabling layout-aware widget placement
• glzr-io/komorebi — Komorebi is the window manager Zebar targets on Windows; komorebi-util crate is a wrapper around its socket API for programmatic window queries in widgets
• vercel/next.js — Common choice for widget pack template scaffolding in marketplace; understanding Next.js routing and build optimization helps contributors create faster widget bundles

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 integration tests for shell-util crate with multiple shell environments

The shell-util crate (crates/shell-util/src) handles command execution across different shells (bash, zsh, powershell, etc.) but there are no visible integration tests. New contributors could add comprehensive tests for encoding.rs, shell.rs, and stdout_reader.rs to ensure cross-platform shell command execution works correctly across Windows/Mac/Linux.

• [ ] Create crates/shell-util/tests/ directory with integration test file
• [ ] Add tests for shell detection and command execution in different environments
• [ ] Add tests for encoding.rs handling of different character encodings
• [ ] Add tests for stdout_reader.rs buffering and streaming behavior
• [ ] Ensure tests run in CI (check .github/workflows/lint-check.yaml or create new test workflow)

Add GitHub Actions workflow for Rust crate benchmarking and performance regression detection

The repo uses Rust workspace with multiple performance-sensitive crates (komorebi-util, shell-util, systray-util) but there's no visible benchmarking workflow. A new contributor could create a benchmark CI workflow that runs on PRs to prevent performance regressions in critical paths like shell command execution or systray operations.

• [ ] Create benchmark binaries in crates/shell-util/benches/ and crates/systray-util/benches/
• [ ] Create .github/workflows/benchmark.yaml that runs 'cargo bench' on pull requests
• [ ] Configure workflow to compare results against main branch and comment on PRs with regressions
• [ ] Document benchmark setup in CONTRIBUTING.md

Add configuration schema validation tests for packages/client-api config schemas

The client-api package has multiple config schema files (config-schemas.ts, widget-config.ts, dock-config.ts, widget-placement.ts, widget-privileges.ts) but no visible tests validating schema correctness, invalid inputs, or edge cases. A new contributor could add comprehensive unit tests ensuring config validation catches malformed configurations early.

• [ ] Create packages/client-api/src/config/tests/ directory
• [ ] Add test file for config-schemas.ts validating valid and invalid widget configurations
• [ ] Add tests for widget-placement.ts with edge cases (overlapping placements, out-of-bounds)
• [ ] Add tests for widget-privileges.ts permission validation logic
• [ ] Integrate tests into package.json scripts and CI pipeline

• Add shell integration tests for shell-util crate: crates/shell-util/src/ lacks dedicated integration tests for bash/zsh/PowerShell detection and execution; add test cases in tests/ directory to cover error cases in encoding.rs and shell.rs
• Document zpack.json schema and validation: No formal JSON schema file or validation docs exist for zpack.json manifest; create docs/zpack-schema.json and update CONTRIBUTING.md with required/optional fields, template field validation
• Add example widget pack showcasing systray-util callbacks: packages/examples/ or packages/desktop/examples/ lacks a runnable widget demonstrating tray icon interactions (right-click menu, run-on-startup toggling); build a minimal React/buildless template example

The Zebar codebase demonstrates a reasonable security posture with proper dependency management and workspace organization. However,

• Medium · Broad Windows API Feature Set — Cargo.toml (workspace.dependencies). The Cargo.toml workspace dependencies include an extensive list of Windows API features (windows = 0.58). While not inherently vulnerable, this large attack surface includes features like Win32_System_Com, Win32_Security, and Win32_UI_WindowsAndMessaging that could be exploited if misused. The presence of Win32_System_Diagnostics_Debug is particularly concerning for a user-facing application. Fix: Audit which Windows features are actually required by the application. Remove unused features to reduce the attack surface. Specifically review the necessity of debugging-related APIs (Win32_System_Diagnostics_Debug) in production code.
• Medium · Unsafe System Command Execution — crates/shell-util/src/shell.rs, crates/shell-util/src/stdout_reader.rs. The presence of 'shell-util' crate with stdout_reader suggests the application executes shell commands. This is a potential vector for command injection attacks if user input is not properly sanitized before being passed to shell commands. Fix: Review shell-util implementation for command injection vulnerabilities. Ensure all user input is properly validated and escaped. Consider using parameterized command execution instead of string concatenation. Implement input allowlisting where possible.
• Medium · Dynamic Widget Loading from User Config — packages/client-api/src/config/widget-config.ts, packages/client-api/src/config/widget-pack.ts. The widget configuration system (packages/client-api/src/config/widget-config.ts, widget-pack.ts) appears to support dynamic loading of widgets. If these configurations can be modified by users or loaded from untrusted sources, this could lead to arbitrary code execution or XSS attacks. Fix: Implement strict validation and sandboxing for dynamically loaded widgets. Use Content Security Policy (CSP) headers. Verify widget signatures if loading from external sources. Implement a widget permission system (noted in widget-privileges.ts) and ensure it's properly enforced.
• Medium · IPC/Provider Communication Security — packages/client-api/src/providers/create-provider.ts, packages/client-api/src/desktop/provider-emit.ts. The application uses a provider system for data (audio, battery, cpu, date, disk, etc.) with potential inter-process communication. The provider-emit.ts and create-provider.ts files suggest bidirectional communication that could be vulnerable to injection attacks if not properly validated. Fix: Implement strict input validation on all provider data. Use message signing/verification for inter-process communication. Sanitize all data before using it in UI contexts. Implement rate limiting on provider updates to prevent DoS.
• Low · Missing Security Headers Configuration — Project root configuration files. No visible security headers configuration (Content-Security-Policy, X-Frame-Options, etc.) in the file structure. This could impact web-based components or if the application serves any web content. Fix: If the application includes any web server components, implement comprehensive security headers. Configure CSP to prevent XSS attacks, X-Frame-Options to prevent clickjacking, and other protective headers.
• Low · Dependency Management Best Practices — Cargo.toml. While the Cargo.toml uses pinned versions (good practice), the workspace uses resolver = '2' which may allow transitive dependency upgrades. Regular security audits are necessary. Fix: Run 'cargo audit' regularly in CI/CD pipeline to detect known vulnerabilities in dependencies. Consider using 'cargo deny' to maintain a deny-list of problematic dependencies. Keep workspace dependencies updated regularly.
• Low · Systray Integration Security — crates/systray-util/src/tray_spy.rs. The systray-util crate (crates/systray-util/src/tray_spy.rs) suggests monitoring of system tray. This requires elevated privileges and could be a target for privilege escalation if not properly secured. Fix: Ensure systray operations only request necessary permissions. Implement strict access controls. Validate all data received from systray operations. Consider principle of least privilege for any privileged operations.

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.