Crossbar

Universal Plugin System for Taskbar/Menu Bar - Write Once, Run Everywhere

Crossbar is a revolutionary cross-platform plugin system inspired by BitBar (macOS) and Argos (Linux), bringing the power of scriptable status bar widgets to all platforms - desktop and mobile.

-- cpu.10s.lua — Works on ALL platforms (Linux, macOS, Windows, Android, iOS)
local cpu = crossbar.cpu()
local color = cpu >= 80 and 'red' or cpu >= 60 and 'yellow' or 'green'

print('⚡ ' .. math.floor(cpu + 0.5) .. '% | color=' .. color)
print('---')
print('Usage: ' .. string.format('%.1f%%', cpu))
print('Platform: ' .. crossbar.platform())
print('Refresh | refresh=true')

✨ Features

🚀 Core Capabilities

• 🌍 True Cross-Platform: One plugin, five target platforms (Linux, macOS, Windows, Android, iOS)
• 🌙 Lua-First Plugins: 25 sample plugins in Lua run on all platforms via embedded interpreter. Also supports Bash, Python, Node.js, Dart, Go, Rust, YAML
• ⚡ Hot Reload: Automatic plugin detection and reload (<1s)
• 🎨 Adaptive Rendering: Same plugin renders as tray icon, notification, or widget
• 🔒 Secure Storage: Passwords stored in system Keychain/KeyStore
• 🌐 76+ CLI Commands: Unified API for system info, network, media, clipboard, QR codes, and more

🎯 Revolutionary Advantages Over BitBar/Argos

Feature	BitBar/Argos	Crossbar
Platforms	macOS/Linux only	Linux + Windows + macOS + Android + iOS
Output Formats	Text only	Text + JSON + Structured Data
UI Targets	Menu bar only	Tray + Notifications + Widgets + Menu bar
CLI API	None (scripts call system commands)	76+ unified commands (crossbar cpu)
Configuration	Manual scripting	Declarative JSON with auto-generated UI
Mobile Support	❌ None	✅ Widgets + Persistent Notifications (Android) + Home/Lock Screen Widgets (iOS)
Controls	Read-only	Bidirectional (volume, media, system)
Hot Reload	Manual refresh	Automatic file watching

📱 Platform-Specific Features

Desktop (Linux/macOS/Windows)

• System tray integration with custom icons
• Menu bar dropdown with unlimited items
• Window management and theming
• Tray Display Mode (Settings → System Tray):
  • Unified: Single tray icon with menu for all plugins (default)
  • Separate: One tray icon per plugin (Linux only)
  • Smart Overflow: Shows all plugins as separate icons until count exceeds threshold, then switches to Unified.
  • Smart Collapse: Shows first N plugins as separate icons, others in Unified menu.

Mobile (Android/iOS)

• Home screen widgets (1x1, 2x2, 4x4 layouts)
• Persistent notifications (Android foreground service)
• Lock screen widgets (iOS)

🚀 Quick Start

Installation

1. One-Line Install

Linux / macOS:

curl -fsSL install.cat/verseles/crossbar | sh

Windows (PowerShell):

irm install.cat/verseles/crossbar?format=ps1 | iex

Android:

Download the latest APK directly: crossbar-android-arm64.apk

On Linux this installs Crossbar to ~/.local/share/crossbar with a symlink at ~/.local/bin/crossbar.
On macOS this installs Crossbar.app to ~/Applications/Crossbar.app and creates ~/.local/bin/crossbar.
On Windows this installs Crossbar to %LOCALAPPDATA%\Crossbar and adds this path to user PATH.

2. Download Pre-built Binaries

Download the latest release from GitHub Releases:

• Linux: crossbar-linux-x64.tar.gz
• macOS: crossbar-macos-arm64.tar.gz
• Windows: crossbar-windows-x64.zip
• Android: crossbar-android-arm64.apk

Linux manual install:

mkdir -p ~/.local/share/crossbar
tar -xzf crossbar-linux-x64.tar.gz -C ~/.local/share/crossbar
ln -sf ~/.local/share/crossbar/crossbar ~/.local/bin/crossbar

macOS manual install:

mkdir -p ~/Applications
tar -xzf crossbar-macos-arm64.tar.gz -C /tmp
mv /tmp/crossbar.app ~/Applications/Crossbar.app
ln -sf ~/Applications/Crossbar.app/Contents/MacOS/crossbar ~/.local/bin/crossbar

Windows manual install (PowerShell):

Expand-Archive .\crossbar-windows-x64.zip -DestinationPath "$env:LOCALAPPDATA\Crossbar" -Force
[Environment]::SetEnvironmentVariable("Path", "$([Environment]::GetEnvironmentVariable('Path','User'));$env:LOCALAPPDATA\Crossbar", "User")

Usage:

crossbar              # Launch (Start in Tray)
crossbar gui          # Launch GUI (Open Window)
crossbar --help       # Show CLI commands
crossbar cpu          # Example CLI usage

3. Build from Source (Contributors)

Prerequisites:

• Flutter 3.38.3+ (Install Flutter)
• Dart 3.10.0+ (comes with Flutter)
• make (optional, for easier build commands)

git clone https://github.com/verseles/crossbar.git
cd crossbar
flutter pub get
make linux   # or make macos, make windows

Your First Plugin

1. Create a plugin file in ~/.crossbar/plugins/ (plugins can be files in the root or inside subdirectories):

-- ~/.crossbar/plugins/hello.10s.lua
print('👋 Hello Crossbar!')
print('---')
print('Platform: ' .. crossbar.platform())
print('Uptime: ' .. crossbar.uptime())
print('Refresh | refresh=true')

2. The plugin will auto-refresh every 10 seconds (from filename *.10s.lua)

Tip: Lua plugins work on all platforms (Linux, macOS, Windows, Android, iOS) without external dependencies. For desktop-only scripts, you can also use .sh, .py, .js, etc.

📖 Documentation

Plugin Types

Crossbar supports multiple plugin types for different use cases:

Type	Extension	Platforms	Use Case
Lua ⭐	.lua	All ✅	Recommended — embedded, fast, sandboxed
YAML	.yaml	All ✅	Simple data display, no code needed
Dart Interpreted	.dart	All ✅	Logic without external packages
Script	.sh, .py, .js	Desktop	Existing scripts, shell commands
Dart Compiled	.dart.exe	Desktop	Full Dart with any package

Quick Examples:

# YAML Plugin - weather.30m.yaml
name: Weather
source:
  type: http
  url: "https://api.example.com/weather"
output:
  text: "🌡️ ${response.temp}°C"

// Dart Plugin - clock.1s.dart
import 'package:crossbar_bridge/crossbar_bridge.dart';

void main() {
  final crossbar = CrossbarBridge();
  print('⏰ ${crossbar.time()}');
}

📖 Detailed Guides:

• Codebase Architecture Guide - Start here for developers!
• Plugin Types Overview
• YAML Plugins
• Dart Plugins
• Writing Portable Plugins
• crossbar_api Package

Plugin Format

Crossbar supports two output formats:

1. BitBar Text Format (Legacy Compatible)

#!/bin/bash
echo "🔋 85%"          # Tray text (first line)
echo "---"             # Separator
echo "Status | color=green"
echo "Details | bash='crossbar battery --json'"

Attributes:

• color=red|blue|#FF0000 - Text color
• bash='command' - Execute on click
• refresh=true - Refresh all plugins on click
• href='https://url' - Open URL on click
• font=Monaco - Custom font
• size=12 - Font size

2. JSON Format (Recommended)

#!/usr/bin/env python3
import json
print(json.dumps({
    "icon": "🔋",
    "text": "85%",
    "tooltip": "Battery Level",
    "color": "#00FF00",
    "menu": [
        {"text": "Show Details", "bash": "crossbar battery --json"},
        {"text": "---"},  # Separator
        {"text": "Settings", "href": "https://settings"}
    ]
}))

CLI API Reference

Crossbar provides 76+ unified commands accessible via crossbar [command].

System Information

crossbar cpu                # CPU usage (0-100)
crossbar memory             # Memory usage (e.g., "8.2/16 GB")
crossbar battery            # Battery status
crossbar disk               # Disk usage
crossbar uptime             # System uptime
crossbar hostname           # Machine hostname
crossbar username           # Current user
crossbar kernel             # Kernel version
crossbar arch               # Architecture (x64, arm64)
crossbar os                 # Operating system

Network

crossbar net status         # "online" | "offline" | "wifi"
crossbar net ip             # Local IP address
crossbar net ip --public    # Public IP (via ipify.org)
crossbar net ping google.com # Ping latency
crossbar wifi status        # WiFi status
crossbar wifi ssid          # WiFi network name
crossbar bluetooth status   # "on" | "off"
crossbar vpn status         # VPN status

Device & Hardware

crossbar screen size        # Screen resolution
crossbar screen brightness  # Get brightness
crossbar power sleep        # Suspend system
crossbar wallpaper          # Get current wallpaper path

Audio & Media

crossbar audio volume             # Current volume (0-100)
crossbar audio volume 50          # Set volume
crossbar audio mute               # Toggle mute
crossbar media playing --json     # Current media info
crossbar media play               # Resume playback
crossbar media pause
crossbar media next
crossbar media prev

Clipboard

crossbar clipboard                # Get clipboard text
crossbar clipboard "text"         # Copy to clipboard

File Operations

crossbar file exists /path/file
crossbar file read /path/file
crossbar file size /path/file
crossbar dir list /path/dir

Time & Utilities

crossbar time [12h|24h]
crossbar date
crossbar uuid                     # Generate UUID
crossbar random [min] [max]
crossbar hash "text"
crossbar base64 encode "text"
crossbar base64 decode "dGV4dA=="
crossbar exec "command"           # Execute shell command
crossbar notify "Title" "Msg"     # Send notification
crossbar open url "https://..."   # Open URL
crossbar open file "/path/..."    # Open file

See full API: original_plan_specs.md

Plugin Configuration

Plugins can declare their configuration needs:

// ~/.crossbar/plugins/weather.30m.py.schema.json
{
  "name": "Weather Plugin",
  "description": "Shows current weather",
  "version": "1.0.0",
  "settings": [
    {
      "key": "API_KEY",
      "type": "password",
      "label": "OpenWeather API Key",
      "required": true
    },
    {
      "key": "LOCATION",
      "type": "text",
      "label": "City Name",
      "default": "São Paulo"
    },
    {
      "key": "UNITS",
      "type": "select",
      "label": "Temperature Units",
      "options": [
        { "value": "metric", "label": "Celsius" },
        { "value": "imperial", "label": "Fahrenheit" }
      ],
      "default": "metric"
    },
    {
      "key": "ALERT_AT",
      "type": "datetime",
      "label": "Alert datetime",
      "default": "2026-12-31T23:59:59+00:00"
    }
  ]
}

Crossbar automatically generates a configuration dialog with proper UI controls. Tipos com suporte direto na UI hoje: text, password, number, select, checkbox, color, file, path, url, textarea, slider, date, time, datetime.

Environment Variables

Every plugin receives these variables:

CROSSBAR_OS=linux              # Platform (linux/macos/windows/android/ios)
CROSSBAR_DARK_MODE=true        # System theme
CROSSBAR_VERSION=1.0.0         # Crossbar version
CROSSBAR_PLUGIN_ID=cpu.10s.sh  # Plugin filename

# User configs (from .schema.json)
WEATHER_API_KEY=abc123         # Passwords from Keychain
WEATHER_LOCATION=São Paulo
WEATHER_UNITS=metric

Detailed Documentation

For comprehensive documentation, see:

• API Reference - Complete CLI command documentation (~75 commands)
• Plugin Development Guide - Lua-first development guide with multi-language support
• Configuration Schema - Field types and validation reference
• Security Policy - Vulnerability reporting and security considerations

📦 Example Plugins

Crossbar includes 25 Lua sample plugins that run on all platforms via the embedded Lua interpreter:

System Monitoring

• cpu.10s.lua - CPU usage with color coding
• memory.10s.lua - RAM usage visualization
• battery.2s.lua - Battery status with dynamic icons
• disk.5m.lua - Disk space monitor
• uptime.1m.lua - System uptime
• system-info.1m.lua - Comprehensive system info
• process-monitor.10s.lua - Top CPU processes

Time & Clocks

• clock.1s.lua - Current time display
• time.1s.lua - Time with day phase icon
• emoji-clock.1m.lua - Time as emoji clock faces
• world-clock.1m.lua - Multi-timezone clocks
• countdown.1s.lua - Event countdown timer
• pomodoro.1s.lua - Pomodoro technique timer

Network & Web

• weather.30m.lua - Weather from OpenWeatherMap API
• ip-info.1h.lua - Public IP and geolocation
• site-check.1m.lua - Website uptime checker
• network.30s.lua - Network interface status

Development

• git-status.30s.lua - Git repository status
• npm-downloads.1h.lua - NPM package stats
• github-notifications.5m.lua - GitHub notification count
• spotify.5s.lua - Now playing on Spotify
• ssh-connections.30s.lua - Active SSH connections

Productivity & Fun

• todo.1m.lua - Simple todo list
• quotes.1h.lua - Random inspirational quotes
• bitcoin.5m.lua - BTC price from CoinGecko

Note: Users can still write plugins in Bash, Python, Node.js, Dart, Go, Rust, or YAML. Lua is the recommended default for cross-platform compatibility.

🏗️ Architecture

crossbar/
├── lib/
│   ├── core/                   # Core plugin system (Flutter)
│   │   ├── plugin_manager.dart       # Discovery & lifecycle
│   │   ├── script_runner.dart        # Execution engine
│   │   ├── output_parser.dart        # BitBar/JSON parser
│   │   └── api/                      # CLI commands
│   ├── models/                 # Data models
│   ├── services/               # Background services
│   │   ├── scheduler_service.dart    # Auto-refresh triggers
│   │   ├── refresh_service.dart      # Unified refresh engine
│   │   ├── tray_service.dart         # System tray
│   │   ├── hot_reload_service.dart   # File watcher
│   │   ├── marketplace_service.dart  # Plugin discovery
│   │   ├── logger_service.dart       # Rotating logs
│   │   ├── ipc_server.dart           # Inter-process communication
│   │   ├── notification_service.dart # Cross-platform notifications
│   │   ├── settings_service.dart     # User settings management
│   │   └── widget_service.dart       # Home screen widget updates
│   ├── ui/                     # User interface
│   └── l10n/                   # 10 languages
├── packages/                   # Monorepo packages
│   ├── crossbar_core/                # Pure Dart shared APIs & models
│   │   └── lib/src/
│   │       ├── core/                 # Shared core utilities
│   │       ├── models/               # Plugin, Config models
│   │       └── api/                  # System, Network, Media APIs
│   └── crossbar_cli/                 # Pure Dart CLI package
│       ├── bin/crossbar.dart         # CLI entry point
│       └── lib/src/
│           ├── core/                 # CLI-specific plugin manager
│           └── commands/             # 76+ CLI command handlers
├── plugins/                    # Example plugins
├── test/                       # 116 tests (>90% coverage)
└── .github/workflows/          # CI/CD pipelines

🧪 Testing

# Run all tests
flutter test

# Run with coverage
flutter test --coverage
genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html

# Analyze code
flutter analyze

Current stats:

• 676 tests passing (individual test cases)
• 40.7% code coverage (Target: 60%)
• 0 analysis errors

🔧 Development

Project Structure

• Core: Plugin discovery, execution, parsing
• Services: Background tasks, system integration
• UI: Flutter Material Design 3 interface
• CLI: Dart-based command-line API

Key Technologies

• Flutter 3.35+ - Cross-platform framework
• Dart 3.10+ - Type-safe language
• tray_manager - System tray integration
• dio - HTTP client for API calls
• flutter_local_notifications - Push notifications
• home_widget - Home screen widgets
• flutter_secure_storage - Keychain integration

Adding a New CLI Command

1. Add API method in lib/core/api/:

// lib/core/api/system_api.dart
Future<String> getHostname() async {
  final result = await Process.run('hostname', []);
  return result.stdout.toString().trim();
}

2. Add CLI handler in lib/cli/cli_handler.dart (in the switch statement):

case 'hostname':
  print(Platform.localHostname);

Note: The main executable (crossbar) automatically supports both GUI (no args) and CLI (with args) modes.

3. Add tests in test/unit/core/api/system_api_test.dart

🌐 Internationalization

Crossbar supports 13 languages:

• 🇺🇸 English (en)
• 🇧🇷 Portuguese (pt)
• 🇪🇸 Spanish (es)
• 🇩🇪 German (de)
• 🇫🇷 French (fr)
• 🇨🇳 Chinese (zh)
• 🇯🇵 Japanese (ja)
• 🇰🇷 Korean (ko)
• 🇮🇹 Italian (it)
• 🇷🇺 Russian (ru)
• 🇸🇦 Arabic (ar)
• 🇧🇩 Bengali (bn)
• 🇮🇳 Hindi (hi)

Locale is auto-detected from system settings.

📊 Performance

Metric	Target	Actual
Boot Time (desktop)	<2s	✅ ~1.5s
Memory (idle, 3 plugins)	<150MB	✅ ~120MB
Plugin Execution Overhead	<50ms	✅ ~30ms
Hot Reload	<1s	✅ ~500ms
Binary Size (Linux)	<50MB	✅ 41MB

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Ways to Contribute

• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features
• 📝 Improve documentation
• 🔌 Create and share plugins
• 🌐 Add translations
• 🧪 Write tests

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

This ensures that:

• ✅ You can use, modify, and distribute the software
• ✅ All derivatives must remain open source
• ✅ SaaS deployments must share source code (network copyleft)
• ✅ Community improvements benefit everyone

See LICENSE for full terms.

🙏 Acknowledgments

Inspired by:

• BitBar by Mat Ryer
• Argos by Philipp Emanuel Weidmann

Built with:

• Flutter - Google's UI toolkit
• Dart - Client-optimized language

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email: support@crossbar.dev (coming soon)

🗺️ Roadmap

Full roadmap: See ROADMAP.md for detailed timeline, completed features, and technical debt tracking.

✅ v1.4.0 (Current - 2025)

Mobile Mastery & Configuration Engine

• Configuration Engine: JSON schema support, secure storage (Keychain), and UI generation.
• Mobile Widgets: Native Android (XML) and iOS (WidgetKit) home screen widgets.
• Refresh Engine: Unified behavior across UI, Tray and Background.
• Core: Plugin Manager, Script Runner, Output Parser.
• CLI: 76+ commands.
• Platforms: Linux, macOS, Windows, Android, iOS.

🎯 v1.5.0 (Next)

Advanced Desktop UI & API Completion

• Global Hotkey (Ctrl+Alt+C).
• Tray Overflow Logic (Smart Collapse).
• Window State Persistence.
• New CLI commands: location, qr.

🌟 Visão de Longo Prazo (v2.0.0+)

• 🌐 Plugins remotos (execução server-side).
• 📊 Integração OpenTelemetry e Grafana.
• 🤖 Sugestões de plugins com IA.
• 🔗 Plataforma de integração (webhooks, IFTTT/Zapier).
• 🎮 Editor visual de plugins (no-code).
• 🌍 Extensão de navegador e suporte a smartwatch.

Quer influenciar o roadmap? Vote em funcionalidades nas GitHub Issues ou participe das Discussions!

📜 Changelog

See CHANGELOG.md for the complete version history.

🔒 Security Policy

See SECURITY.md for security policy, vulnerability reporting, and best practices.

🤝 Contributing

See CONTRIBUTING.md for contribution guidelines, development setup, and coding standards.

⭐ Star History

If you find Crossbar useful, please consider giving it a star!

---

Made with ❤️ by the Crossbar Team

Website • GitHub • Twitter