Skip to content

alexandreprates/cbar

BranchesTags

Repository files navigation

cbar icon

cbar

License: GPL-3.0-only Rust COSMIC

cbar is a COSMIC panel applet for Pop!_OS that runs local scripts and turns their output into live panel text and interactive popup actions.

It is designed for small, scriptable workflows that belong in the desktop panel:

  • show status from local commands or web APIs
  • open links and tools from a lightweight popup
  • run shell actions without building a full desktop app
  • refresh each plugin on its own interval
  • keep plugin behavior transparent and easy to inspect

cbar is built around COSMIC and libcosmic applet behavior.

Screenshots

cbar plugin popup with timer actions

cbar settings popup with local plugins cbar plugin catalog popup

Quick Install on Pop!_OS

For most users, install the latest prebuilt release without compiling from source:

curl -fsSL https://raw.githubusercontent.com/alexandreprates/cbar/main/scripts/install-latest.sh | bash

The installer downloads the latest GitHub release and installs:

  • ~/.local/bin/cbar
  • ~/.local/share/applications/io.github.alexprates.CBar.desktop
  • icons under ~/.local/share/icons/hicolor/scalable/apps/
  • showcase plugins under ~/.config/cbar/plugins/

The applet and its plugins run as your current user. Review local plugins before enabling actions that run shell commands.

After Installing

The desktop entry is installed with COSMIC applet metadata:

  • X-CosmicApplet=true
  • X-CosmicHoverPopup=Auto

If cbar does not appear in COSMIC applet pickers right away, log out and back in or restart the COSMIC panel/session.

You can also start the applet binary directly for a quick smoke test:

~/.local/bin/cbar

Uninstall

If you installed through the release installer, clone the repository and run the uninstall script:

git clone https://github.com/alexandreprates/cbar.git
cd cbar
./scripts/uninstall-local.sh

The uninstall script removes the local binary, desktop entry, icons, and metainfo files from ~/.local. It does not remove your plugin directory under ~/.config/cbar/plugins.

Troubleshooting

  • If ~/.local/bin/cbar does not exist, rerun the installer and check for download errors.
  • If COSMIC does not list the applet, log out and back in or restart the panel/session.
  • If a plugin action does not work, inspect the plugin script under ~/.config/cbar/plugins; catalog plugins are local scripts executed as your user.
  • If you want to reinstall from scratch, run ./scripts/uninstall-local.sh from a repository checkout and then run the quick install command again.

Status

cbar is currently ready for early adopters and community feedback.

It supports:

  • a working libcosmic panel applet
  • plugin discovery from a local directory
  • periodic plugin execution based on filename intervals
  • per-plugin parallel refresh with in-flight protection
  • popup menu actions for links, shell commands, refreshes, and terminal tasks
  • local installation for testing in a COSMIC session

The implementation is intentionally focused on practical COSMIC integration.

Features

  • COSMIC panel applet built with libcosmic
  • text-based panel label composed from plugin output
  • popup menu generated from plugin stdout
  • per-plugin refresh scheduling
  • per-plugin parallel refresh with per-plugin in-flight protection
  • local plugin execution with support for shell actions, URLs, and terminal actions
  • plugin catalog browsing, installation, and removal from the applet settings
  • local install script for user-level testing

Plugin Output Format

Plugins write plain text to stdout. The first visible line becomes panel text, and lines after --- become popup entries.

Supported item syntax:

  • first line as panel title
  • --- to separate panel output from popup items
  • -- for submenu depth, rendered as indentation in the popup
  • href=...
  • shell=... / bash=...
  • param1=..., param2=..., ...
  • refresh=true
  • terminal=true
  • dropdown=false
  • alternate=true
  • disabled=true
  • trim=true|false

Notes:

  • alternate=true is adapted for COSMIC by rendering an explicit [alt] entry in the popup. Modifier-key alternate entries do not map directly to this applet UI.
  • nested menu items are currently rendered as indented entries, not true nested popup submenus.

Inspiration

The plugin output format is inspired by xbar, while the applet itself is designed specifically for COSMIC.

Plugin Directory

cbar resolves the plugin directory in this order:

  1. CBAR_PLUGIN_DIR
  2. ./plugins when running from the repository
  3. ~/.config/cbar/plugins

Showcase plugins are included under plugins/ to demonstrate panel output, popup structure, actions, environment configuration, refresh behavior, and dynamic status rows.

Plugin Environment

cbar loads optional plugin environment variables from:

~/.config/cbar/env

The file uses simple KEY=value assignments. Values from this file are added to plugin refreshes and popup actions, overriding the inherited process environment for matching keys.

CBAR_SSH_HOSTS="server,user@host"
CBAR_PING_HOST="1.1.1.1"
CBAR_SERVICE_UNITS="docker,user:pipewire"

Missing env files are ignored. Lines starting with # are comments.

Showcase and catalog plugins that expose configurable CBAR_* values include an Edit cbar env popup action. The action creates ~/.config/cbar/env when needed and opens it with COSMIC's editor, falling back to the desktop opener when cosmic-edit is unavailable.

Plugin Catalog

The applet settings include a plugin catalog view backed by the public cbar-plugins repository.

Catalog installation downloads the selected plugin script into the active plugin directory, validates the published SHA-256 checksum, marks the file executable, records the installed catalog version under ~/.config/cbar/catalog-installations.json, and reloads the plugin list. Installed catalog plugins can also be removed from the same catalog view. Catalog plugins are local scripts and run as the current user.

When a catalog plugin publishes a newer semantic version, the catalog shows an explicit update action. Updates validate the new checksum before replacing the local script and refuse to overwrite catalog-installed plugins that were modified locally. Existing installs from older cbar releases are backfilled into the local catalog installation manifest when their local checksum still matches the published catalog entry.

By default, cbar loads:

https://raw.githubusercontent.com/alexandreprates/cbar-plugins/main/registry/plugins.json

To test another registry:

CBAR_PLUGIN_REGISTRY_URL="https://example.com/plugins.json" cargo run

Example Plugin

#!/usr/bin/env bash

echo "Workday"
echo "---"
echo "Open dashboard | href=https://example.com"
echo "Run sync | bash=/bin/bash param1=-lc param2='echo syncing...' refresh=true"
echo "Open terminal task | bash=/bin/bash param1=-lc param2='htop' terminal=true"
echo "Hidden helper | dropdown=false"
echo "Disabled item | disabled=true"

Additional examples:

Installing from a GitHub Release

The quick install command is the recommended release path. If you prefer a repository checkout, clone with HTTPS and let the installer resolve the latest published release automatically:

git clone https://github.com/alexandreprates/cbar.git
cd cbar
./scripts/install-from-release.sh

If you already downloaded a release archive, you can still pass it explicitly:

git clone https://github.com/alexandreprates/cbar.git
cd cbar

version="v1.4.4"
archive="cbar-${version}-x86_64-unknown-linux-gnu.tar.gz"

curl -LO "https://github.com/alexandreprates/cbar/releases/download/${version}/${archive}"
./scripts/install-from-release.sh "./${archive}"

The script also accepts the archive path through CBAR_RELEASE_ARCHIVE:

CBAR_RELEASE_ARCHIVE=./cbar-v1.4.4-x86_64-unknown-linux-gnu.tar.gz ./scripts/install-from-release.sh

Without an explicit archive path, scripts/install-from-release.sh first looks for exactly one local cbar-*-x86_64-unknown-linux-gnu.tar.gz file in the repository root. If none is available, it queries the latest GitHub release, resolves the current tag, and downloads the matching versioned archive automatically.

The installer reuses the desktop entry and icons from the repository and installs:

  • ~/.local/bin/cbar
  • ~/.local/share/applications/io.github.alexprates.CBar.desktop
  • icons under ~/.local/share/icons/hicolor/scalable/apps/
  • the overview showcase plugin in ~/.config/cbar/plugins/ if it does not already exist

If you prefer a direct installation from GitHub without cloning the repository first, use the quick install command:

curl -fsSL https://raw.githubusercontent.com/alexandreprates/cbar/main/scripts/install-latest.sh | bash

The remote installer resolves the latest published release automatically, installs the binary and desktop assets under ~/.local, creates ~/.config/cbar/plugins, and copies the showcase plugins that exist for that tagged release.

If the archive is placed in the repository root, the repository installer can autodetect it as well:

./scripts/install-from-release.sh

Development Setup

System dependencies commonly needed for local development on Pop!_OS:

sudo apt update
sudo apt install -y cmake just libexpat1-dev libfontconfig-dev libfreetype-dev libxkbcommon-dev pkgconf curl

Rust is expected to be installed through rustup:

curl https://sh.rustup.rs -sSf | sh
source ~/.cargo/env

Run from source:

source ~/.cargo/env
cargo run

To force a specific plugin directory:

CBAR_PLUGIN_DIR="$PWD/plugins" cargo run

Install a local development build into ~/.local:

./scripts/install-local.sh

Equivalent just targets are available:

just install-local
just uninstall-local

Development

Common commands:

source ~/.cargo/env
cargo fmt
cargo test
cargo clippy --all-targets --all-features -- -D warnings

Or via just:

just test

Project Structure

src/app.rs        COSMIC applet state, messages, popup UI, refresh orchestration
src/plugin.rs     plugin discovery, execution, action dispatch
src/parser.rs     plugin output parsing
data/             desktop entry template and icons
packaging/        Flatpak manifest for local packaging and COSMIC submission prep
scripts/          local install and uninstall scripts
plugins/          showcase plugins for development

Limitations

  • nested popup items are visual indentation only
  • plugin discovery is static after startup
  • no persistent plugin configuration UI yet
  • some visual plugin item parameters are not mapped to COSMIC UI yet

Roadmap

Implemented:

  • plugin catalog browsing, installation, and removal from applet settings
  • plugin directory shortcuts for manual plugin management from applet settings
  • clearer settings menu grouping for installed plugins, directory actions, and general actions
  • support for links, shell actions, terminal actions, refresh-after-action, alternates, hidden rows, disabled rows, and inline images
  • showcase plugins covering menu structure, actions, configuration, dynamic status rows, RAM gauges, and CPU charts
  • local, release-archive, and latest-release install scripts with desktop entry and icon installation
  • prebuilt GitHub release archives for direct installation

Next:

  • add automatic plugin directory watching
  • support more visual plugin item parameters where they fit COSMIC
  • improve popup hierarchy beyond visual indentation
  • add richer persistent configuration for individual plugins

Related Projects

License

GPL-3.0-only

About

Scriptable COSMIC panel applet for local plugins, live panel text, popup actions, and catalog-based plugin discovery.

Resources

Readme

License

View license
Activity

Stars

3 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 10

v1.4.4 Latest
Jun 5, 2026
+ 9 releases

Packages

 
 
 

Contributors

Languages