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/matryer/xbar 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.

GO — Healthy across all four use cases

• 14 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 69% of recent commits

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

What it runs against: a local clone of matryer/xbar — 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 matryer/xbar | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 636 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "app/main.go" \\
  && ok "app/main.go" \\
  || miss "missing critical file: app/main.go"
test -f "app/app.go" \\
  && ok "app/app.go" \\
  || miss "missing critical file: app/app.go"
test -f "app/menu_parser.go" \\
  && ok "app/menu_parser.go" \\
  || miss "missing critical file: app/menu_parser.go"
test -f "app/plugins_service.go" \\
  && ok "app/plugins_service.go" \\
  || miss "missing critical file: app/plugins_service.go"
test -f "app/frontend/src/App.svelte" \\
  && ok "app/frontend/src/App.svelte" \\
  || miss "missing critical file: app/frontend/src/App.svelte"

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

xbar is a complete rewrite of BitBar that lets you display output from any script or program directly in macOS's menu bar. Built in Go with a Wails.app (Go + HTML/CSS/JS) frontend, it executes user plugins on a schedule and renders their output as menu items. The core capability is running arbitrary scripts (shell, Python, Go, etc.) and formatting their text output into interactive menu bar widgets. Monorepo structure: app/ directory contains the main Go backend (app.go, command_service.go, categories_service.go), Objective-C bridging code, and embedded frontend. app/frontend/ is a standalone Svelte SPA (single-page app) built with Rollup, compiled into the Go binary via Wails. Plugin execution and menu rendering happen server-side in Go; UI state lives in Svelte components (App.svelte, InstalledPluginView.svelte, PluginView.svelte).

macOS power users and developers who want to create lightweight menu bar utilities without building a full native app. Contributors are plugin authors (shell/Python scripters), desktop Go developers, and Svelte frontend contributors. Plugin users browse and install from xbarapp.com's plugin repository.

Production-ready but actively evolved. The project is a complete rewrite of the original BitBar (hence 'reboot'), uses Go 1.x and Wails framework, has CI/CD via GitHub Actions (.github/workflows/deploy-xbarappcom.yaml), and requires macOS Catalina (10.15+). Development is ongoing with clear plugin system architecture, but code is not heavily tested (few _test.go files visible in the main listing).

Low-to-medium risk. Single original author (matryer) with co-contributor (leaanthony from Wails), but active community. Dependencies are stable (Wails, Svelte 3.x, Rollup 2.x). The codebase lacks extensive unit tests (only categories_service_test.go visible), and frontend rebuild via Rollup is required for app packaging. Plugin ecosystem depends on external repo (xbar-plugins), which is separate from the main app maintenance.

Cannot determine from file listing alone, but the codebase shows active Svelte component development (multiple .svelte files for plugin discovery UI) and recent bundler configuration (rollup.config.js using Tailwind CSS 3.3.1, PostCSS 8.4.21). CI is configured for xbarapp.com deployment. No open PRs or issue count visible in provided data.

git clone https://github.com/matryer/xbar.git
cd xbar/app
# Ensure Go 1.x and Node.js 14+ installed
cd frontend && npm install && npm run build
cd .. && go build -o xbar ./cmd
./xbar

Or for frontend development: cd app/frontend && npm run dev (uses Rollup watch mode).

Daily commands:

cd app/frontend
npm run dev          # Watch mode, rebuilds on change
# In another terminal:
cd app && go run ./cmd ./dev  # Run Go backend in dev mode

Or build release: ./app/build.sh (uses build/darwin/Info.plist.src for macOS app metadata).

• app/main.go — Entry point for the entire xbar application; initializes the Wails runtime and orchestrates startup of all services
• app/app.go — Core application struct and business logic; implements all RPC methods exposed to the frontend and manages the plugin/menu execution lifecycle
• app/menu_parser.go — Parses plugin script output into menu items; critical for interpreting plugin return values and supporting xbar syntax
• app/plugins_service.go — Manages plugin discovery, installation, refresh scheduling, and execution; the backbone of plugin management
• app/frontend/src/App.svelte — Top-level Svelte component routing all UI pages; defines the user-facing interface and navigation structure
• app/wails.json — Wails framework configuration; defines build settings, frontend asset paths, and app metadata

• app.go (App struct) (Go, Wails RPC) — Central orchestrator; routes all frontend RPC calls to appropriate services; manages app lifecycle
  • Failure mode: If App panics, entire Wails runtime crashes and app exits; frontend loses connection
• plugins_service.go (Go file system, goroutines for scheduling) — Discovers plugins in configured directories, schedules refresh intervals, manages plugin state, tracks plugin metadata
  • Failure mode: If plugin scan fails,

Add a new RPC endpoint callable from the frontend

1. Define a new exported method on the App struct in app/app.go with signature func (a *App) MethodName(args) (result, error) (app/app.go)
2. Call the new method from frontend using the RPC bridge: import { backend } from './backend'; backend.app.MethodName(args) (app/frontend/src/backend/index.js)
3. Create a Svelte store or component to manage the call state and display results (app/frontend/src/rpc.svelte)

Add a new plugin configuration variable to the UI

1. Plugin variables are parsed from script headers; update app/menu_parser.go to recognize new variable syntax (app/menu_parser.go)
2. Add a Svelte component in app/frontend/src/elements/VariableInput.svelte to render the variable input UI (app/frontend/src/elements/VariableInput.svelte)
3. Update app/frontend/src/elements/Variables.svelte to include the new input component in the variables list (app/frontend/src/elements/Variables.svelte)

Add a new plugin lifecycle hook or refresh behavior

1. Implement plugin execution and scheduling logic in app/plugins_service.go; add new methods for custom refresh intervals (app/plugins_service.go)
2. Update app/command_service.go if new execution modes (e.g., background tasks) are needed (app/command_service.go)
3. Expose the new behavior via a new RPC method in app/app.go for frontend control (app/app.go)

• Go backend — Cross-platform subprocess execution, file system operations, and low-latency menu updates; statically compiled binary
• Wails.app framework — Bridges Go backend and HTML/CSS/JS frontend for native macOS app without native SDK requirement; manages IPC and app lifecycle
• Svelte frontend — Lightweight reactive UI framework; small bundle size critical for menu bar app startup performance
• Rollup bundler — Efficient tree-shaking and code splitting for frontend assets; minimal output size for fast app load

• Plugin scripts executed as external processes via shell

  • Why: Enables plugins in any language (bash, Python, JavaScript, etc.) without sandboxing the app; maximizes ecosystem flexibility
  • Consequence: Security risk if untrusted plugins are installed; requires user to review plugin code before installation

• Menu parsing happens synchronously after script execution

  • Why: Keeps menu updates consistent with script output; simpler mental model for plugin developers
  • Consequence: Long-running scripts block UI updates; plugins should use background tasks with periodic short-running refresh scripts

• All plugin state stored in filesystem (plugin directory, settings file)

  • Why: No database dependency; portable and user-controllable; easy to backup and version control
  • Consequence: Concurrent file access could cause race conditions; no transactions or ACID guarantees

• Frontend Svelte app bundled into Go binary at build time

  • Why: Single distributable artifact; no runtime dependency on separate web server
  • Consequence: Frontend changes require full app rebuild; cannot hot-reload frontend in production

• Linux or Windows support (macOS-only menu bar integration)
• Plugin sandboxing or permission model (plugins have full user privileges)
• Real-time bidirectional plugin communication (one-way script → menu output)
• Plugin marketplace or automatic updates (manual download/install or GitHub releases)

1. Frontend must be built before Go binary runs: app/frontend/npm run build outputs dist/bundle.js, which is embedded via //go:embed in the Go code. Running go build without building frontend first will fail or use stale UI. 2. Plugin discovery assumes macOS paths: code references ~/Library/Application Support/xbar/plugins; Linux/Windows paths are untested. 3. Rollup config uses sirv-cli for dev server: app/frontend/start:dev runs on 0.0.0.0:5000 but the Go backend may not proxy requests correctly; direct Rollup --dev watch is safer. 4. Wails version pinned to @1.3.10: some Wails 2.x features may not work; check wails.app/docs/v1 not v2. 5. Build requires Xcode/codesign: app/build.sh calls Objective-C compiler and app-sign tools; must run on macOS with Xcode.

• Wails Framework — xbar is built entirely on Wails (Go + HTML/CSS/JS desktop apps); understanding its runtime bindings, embedding, and dev mode is essential for backend/frontend integration.
• Plugin Execution & Output Parsing — Core xbar feature: running arbitrary scripts (shell, Python, etc.) on a schedule and parsing text output into menu items. command_service.go handles this; requires understanding subprocess I/O and line-based text format.
• Menu Bar Integration (NSStatusBar) — xbar renders into macOS menu bar via Objective-C NSStatusBar APIs; the Wails app wraps this. Knowing how NSStatusBar works explains why xbar is macOS-only.
• Go Embedding (//go:embed) — Frontend Svelte bundle (app/frontend/dist/bundle.js) is embedded into the Go binary at compile time; no separate assets folder at runtime. Build order matters.
• Svelte Reactive Declarations & Stores — Frontend uses Svelte's $: reactive blocks and component state (e.g., PluginView.svelte manages install state); understanding reactivity is needed for UI changes.
• Hash-based Routing — Frontend uses svelte-hash-router for client-side navigation (#/plugins, #/preferences); no server-side routing. State is not persisted across page reloads.
• Rollup Module Bundling & Code Splitting — Frontend build process uses Rollup to bundle Svelte, PostCSS, and JS into dist/bundle.js; understanding Rollup plugins (svelte, postcss, terser) is needed for build troubleshooting.

• matryer/bitbar — Original BitBar project (predecessor); xbar is a ground-up rewrite of this, shares plugin format and use case
• matryer/xbar-plugins — Official plugin repository referenced in README; users install plugins from here, separate from the main app repo
• wailsapp/wails — Go + HTML/CSS/JS framework that xbar is built on; essential for understanding the app architecture and build process
• leaanthony/wails — Author Lea Anthony's Wails project (co-maintainer); used as the Go/web framework for xbar's cross-platform UI
• sveltejs/svelte — Frontend framework used for xbar's UI components (App.svelte, PluginView.svelte, etc.); helps understand reactive bindings and component structure

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 menu_parser.go core parsing logic

menu_parser.go is a critical component that parses script output into menu structures, but menu_parser_test.go appears minimal based on the file listing. Adding comprehensive tests for edge cases (empty output, malformed menu items, special characters, performance with large menus) would improve reliability and catch regressions early. This is core to xbar's functionality.

• [ ] Review existing menu_parser_test.go and identify uncovered code paths
• [ ] Add test cases for empty/null inputs, special menu item formats, and Unicode handling
• [ ] Add benchmark tests in menu_parser_test.go for large menu parsing (1000+ items)
• [ ] Document test coverage in app/README.md with current coverage % and target

Add integration tests for command_service.go with real script execution

command_service.go handles executing user scripts and retrieving their output—a critical security and stability surface. No test file is listed for it. Integration tests should verify script execution, timeout handling, error propagation, and environment variable passing to prevent regressions that could cause menu bar hangs or security issues.

• [ ] Create command_service_test.go with test fixtures (simple shell scripts in testdata/)
• [ ] Add tests for: successful execution, timeout scenarios, script not found, permission denied
• [ ] Test environment variable passing and cleanup after execution
• [ ] Add test for concurrent script execution to catch race conditions

Add Svelte component tests for app/frontend/src/elements and pages

The frontend has multiple Svelte components (PluginView.svelte, InstalledPluginView.svelte, PluginsList.svelte, etc.) with no visible test files, yet they handle user interaction and data display. Adding Jest/Vitest tests would ensure UI stability across refactors. Start with the most complex components that handle plugin data rendering.

• [ ] Add Vitest and @testing-library/svelte to frontend/package.json devDependencies
• [ ] Create frontend/src/tests/ directory with test files for PluginView.svelte and PluginsList.svelte
• [ ] Test component rendering with mock plugin data, user interactions (clicks, form inputs), and error states
• [ ] Update frontend/package.json with 'test' script and add GitHub Actions workflow to run tests on PR

• Add unit tests for categories_service.go: currently only categories_service_test.go exists but is likely minimal. Write tests for plugin discovery, duplicate handling, and category filtering.: Critical service lacks test coverage; improves reliability of plugin discovery.
• Add missing dark/light mode toggle to Svelte UI: dialog/ folder contains info/warning/question icons in both dark and light variants, but frontend doesn't switch themes. Add a theme toggle in App.svelte and persist via localStorage.: Assets exist but UI doesn't use them; straightforward Svelte state + CSS class toggle.
• Document the plugin output format and menu syntax: README mentions plugins produce 'script output' but doesn't link to bitbar/plugin format spec. Add docs/PLUGIN_OUTPUT.md explaining line format, separators, icons, fonts, colors.: Plugin authors must reverse-engineer the format; official docs would unblock plugin contributions.

• High · Outdated and Vulnerable Dependencies — app/package.json. Multiple npm dependencies have known vulnerabilities or are significantly outdated. Notable issues: highlight.js >=10.4.1 (allows vulnerable versions), rollup-plugin-terser is unmaintained, svelte-preprocess@4.6.1 is outdated, and several @rollup plugins use older versions. Fix: Update all dependencies to their latest versions, particularly: highlight.js to >=11.8.0, svelte to ^4.x, and replace rollup-plugin-terser with @rollup/plugin-terser. Run 'npm audit' and address all reported vulnerabilities.
• High · Missing Security Headers Configuration — app/frontend/package.json, app/wails.json. No evidence of security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) configured in the Wails application. The dev server started with '--host 0.0.0.0' exposes services to all network interfaces without security boundaries. Fix: Configure security headers in the Wails backend. Add CSP, X-Frame-Options: DENY, X-Content-Type-Options: nosniff. Restrict '--host' binding to localhost (127.0.0.1) for development.
• Medium · Potential XSS via Menu Parser Output — app/menu_parser.go, app/frontend/src/PluginView.svelte, app/frontend/src/InstalledPluginView.svelte. The menu_parser.go processes script output that gets rendered in the frontend. Without proper sanitization, malicious scripts could execute arbitrary commands that render unsanitized HTML in the Svelte frontend (e.g., PluginView.svelte, InstalledPluginView.svelte). Fix: Implement strict output sanitization in the menu parser. Use HTML escaping for all user-controlled content rendered from plugins. In Svelte, avoid {@html} directives and use text content binding instead. Validate and sanitize plugin output server-side.
• Medium · Insecure Dev Server Configuration — app/package.json (start:dev script). The 'start:dev' script binds to 0.0.0.0:3000 with '--dev' flag enabled. This exposes the development server to the entire network with potentially reduced security checks and hot-reload functionality that could be exploited. Fix: Change host binding from 0.0.0.0 to 127.0.0.1 for development. Only expose to 0.0.0.0 in production if absolutely necessary with proper firewall rules and authentication.
• Medium · No CORS/Origin Validation Visible — app/incoming_urls.go, app/frontend/src/backend/index.js, app/frontend/src/rpc.svelte. No evidence of CORS validation or origin checking in the incoming_urls.go and RPC communication. The app handles incoming URLs and backend communication without visible security validation. Fix: Implement strict CORS policies. Validate origin headers. Use CSRF tokens for state-changing operations. Implement proper authentication for RPC calls from the frontend.
• Medium · Plugin Execution Without Sandboxing — app/command_service.go, app/plugins_service.go. The application executes arbitrary scripts/programs from plugins (as described in README and command_service.go). No visible sandboxing or permission controls restrict what these plugins can access on the system. Fix: Implement plugin sandboxing using OS-level restrictions (e.g., macOS entitlements, capability sets). Add explicit permission models requiring user approval for sensitive operations. Document security risks to users.
• Low · Missing Content Security Policy — app/frontend/public/index.html. No CSP meta tags or headers visible in the HTML frontend (public/index.html) to prevent inline script execution and restrict resource loading. Fix: Add comprehensive Content Security Policy headers and meta tags restricting script-src, style-src, img-src, and other directives to trusted sources only.
• Low · Sensitive Information in Public Directory — undefined. Build outputs and public assets stored in app/build/ and app/frontend/public/ should be reviewed to ensure no sensitive configuration Fix: undefined

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.