Argos

<h1 align="center">Argos</h1> <h3 align="center">Create GNOME Shell extensions in seconds</h3> <br>

Most GNOME Shell extensions do one thing: Add a button with a dropdown menu to the panel, displaying information and exposing functionality. Even in its simplest form, creating such an extension is a nontrivial task involving a poorly documented and ever-changing JavaScript API.

Argos lets you write GNOME Shell extensions in a language that every Linux user is already intimately familiar with: Bash scripts.

More precisely, Argos is a GNOME Shell extension that turns executables' standard output into panel dropdown menus. It is inspired by, and fully compatible with, the BitBar app for macOS. Argos supports many BitBar plugins without modifications, giving you access to a large library of well-tested scripts in addition to being able to write your own.

Key features

• 100% API compatible with BitBar 1.9.2: All BitBar plugins that run on Linux (i.e. do not contain macOS-specific code) work with Argos (else it's a bug).
• Beyond BitBar: Argos can do everything that BitBar can do, but also some things that BitBar can't do (yet). See the documentation for details.
• Sophisticated asynchronous execution engine: No matter how long your scripts take to run, Argos will schedule them intelligently and prevent blocking.
• Unicode support: Just print your text to stdout. It will be rendered the way you expect.
• Optimized for minimum resource consumption: Even with multiple plugins refreshing every second, Argos typically uses less than 1% of the CPU.
• Fully documented.

Installation

Manually using git (all recent GNOME shell versions)

Clone the repository:

 git clone https://github.com/p-e-w/argos

Check out the code matching your GNOME shell version:

• GNOME 45 and newer: nothing to be done (just use the master branch)
• GNOME 42 - 44: Use tag GNOME-44,
• GNOME 3.26 - 41: Use tag GNOME-41.

Thus e.g. for GNOME shell 44, run:

git switch -c gnome-44 GNOME-44

Then copy or symlink the directory argos@pew.worldwidemann.com into ~/.local/share/gnome-shell/extensions. Restart GNOME Shell by pressing <kbd>Alt+F2</kbd>, then entering r (GNOME/X11) or by logging out and logging in again (Wayland). On some systems, you may additionally have to enable the Argos extension using the GNOME "extensions" application or GNOME Tweak Tool.

From the GNOME Shell Extensions website (GNOME 3.32 and earlier)

<img src="https://img.shields.io/badge/extensions.gnome.org-Argos-9999ff.svg" height="30">

Important: Argos for GNOME shell 3.34 and later (including GNOME 40 and beyond) are not available on extensions.gnome.org. Read about the reasons here.

Examples

GNOME Shell log viewer

Argos plugins are great for monitoring your system, displaying anything that a command line script can output in a convenient, unobtrusive place.

Extension developers often rely on the central GNOME Shell log for debugging. That log may be viewed in a terminal with journalctl /usr/bin/gnome-shell -f – but it is also an excellent target for our first sample plugin:

shell_log.1s.sh

#!/usr/bin/env bash

LOG_ENTRY=$(journalctl /usr/bin/gnome-shell -n 1 --output=cat --no-pager)
echo "<span color='#9BF' weight='normal'><small><tt>$LOG_ENTRY</tt></small></span> | length=40"

echo "---"
echo "View GNOME Shell Log | bash='journalctl /usr/bin/gnome-shell -f'"

Make it executable and drop it into ~/.config/argos, and you should see something like this:

As the plugin updates every second, new log entries are shown almost without delay.

Simple launcher

Plugins are not limited to displaying information – they can also perform actions when the user clicks on a menu item. This allows you to rapidly create launchers that look and act exactly like you want.

launcher.sh

#!/usr/bin/env bash

echo "Launcher | iconName=starred"
echo "---"

WIKIPEDIA_ICON=$(curl -s "https://en.wikipedia.org/static/favicon/wikipedia.ico" | base64 -w 0)
echo "Wikipedia | image='$WIKIPEDIA_ICON' imageWidth=20 font=serif href='https://en.wikipedia.org'"

echo "---"
echo "Gedit | iconName=gedit bash=gedit terminal=false"
echo "Nautilus | iconName=system-file-manager bash=nautilus terminal=false"
echo "Process list (<span color='yellow'><tt>top</tt></span>) | iconName=utilities-terminal-symbolic bash=top"
echo "---"
echo "Looking Glass | eval='imports.ui.main.createLookingGlass(); imports.ui.main.lookingGlass.toggle();'"

Note how the Wikipedia icon is downloaded from the web and serialized into the menu item without ever needing to be saved to disk. All of this comes from a file smaller than the configuration files of most dedicated "launcher" extensions, while providing much more flexibility. Argos plugins blur the line between configuration and code.

Advanced launcher

An Argos plugin is just an executable file that writes to stdout. As such, any language can be used to create plugins. Switching from Bash to Python gives you easy access to the GNOME platform APIs, enabling even more powerful launchers.

launcher.py

#!/usr/bin/env python3

import re
from gi.repository import Gio

applications = {}

for app_info in Gio.AppInfo.get_all():
  icon, categories = app_info.get_icon(), app_info.get_categories()
  if icon is None or categories is None:
    continue
  # Remove "%U" and "%F" placeholders
  command_line = re.sub("%\\w", "", app_info.get_commandline()).strip()
  app = (app_info.get_name(), icon.to_string(), command_line)
  for category in categories.split(";"):
    if category not in ["GNOME", "GTK", ""]:
      if category not in applications:
        applications[category] = []
      applications[category].append(app)
      break

print("Applications\n---")

for category, apps in sorted(applications.items()):
  print(category)
  for app in sorted(apps):
    print("--%s | useMarkup=false iconName=%s bash='%s' terminal=false" % app)

And there you have it: A working clone of a full-blown GNOME Shell extension – implemented using a fraction of the code.

top viewer

Argos basically pipes standard output into a panel menu. This makes for some very cool plugins like this top output viewer:

top.3s+.sh

#!/usr/bin/env bash

echo "top"
echo "---"

if [ "$ARGOS_MENU_OPEN" == "true" ]; then
  # http://stackoverflow.com/a/14853319
  TOP_OUTPUT=$(top -b -n 1 | head -n 20 | awk 1 ORS="\\\\n")
  echo "$TOP_OUTPUT | font=monospace bash=top"
else
  echo "Loading..."
fi

It's top at your fingertips! Of course, this approach works with any other terminal program as well.

Note that the plugin checks the ARGOS_MENU_OPEN environment variable to ensure top is run only if the dropdown menu is visible, while the + in the filename forces a re-run whenever the user opens the menu. This pattern makes output available immediately when it is needed, but keeps idle resource consumption of the plugin near zero.

Usage

Argos monitors the directory ~/.config/argos for changes. Any executable file found in this directory is considered a plugin. Files whose name starts with a dot (.) and files in subdirectories are ignored.

Plugins are run and their standard output is interpreted as described below. For each plugin, a panel button with a dropdown menu is created. The arrangement of buttons from left to right follows the alphabetical order of the files they are generated from (except when a POSITION is explicitly specified in the filename). New plugins and edits to existing plugins are automatically detected and reflected in the panel.

Filename format

A plugin file may be named anything (it only needs to be executable), but if its name has the special form

NAME.POSITION.INTERVAL[+].EXTENSION

where

• POSITION consists of an integer (optional) + one of l (left), c (center) or r (right), and
• INTERVAL consists of an integer + one of s (seconds), m (minutes), h (hours) or d (days)

then

• the dropdown menu button is placed in the panel at POSITION, and
• the plugin is re-run and its output re-rendered every INTERVAL, and
• if INTERVAL is followed by +, the plugin is additionally re-run each time the dropdown menu is opened.

POSITION may be omitted entirely (in which case the button is placed before all other buttons on the right-hand side of the panel) while INTERVAL can be left empty. For example, a script named plugin.10s.sh is updated every 10 seconds, the button belonging to plugin.1c..sh is positioned just right of the GNOME Shell clock, and plugin.l.1m.sh is displayed left of the "Activities" button and updated every minute.

Output format

Argos plugins are executables (such as shell scripts) that print to standard output lines of the following form:

TEXT | ATTRIBUTE_1=VALUE ATTRIBUTE_2=VALUE ...

All attributes are optional, so the most basic plugins simply print lines consisting of text