Argos for GNOME Shell: Build Panel Menus with Bash

Argos Bash Plugins for GNOME Panel Interaction

Argos addresses a recurring GNOME Shell extension pattern: adding a panel button with a dropdown menu that displays information and exposes actions. The README says that implementing this directly involves a poorly documented and changing JavaScript API. Argos moves most of that work into executable scripts. A script writes menu definitions to standard output, and Argos renders them in the GNOME Shell panel.

The project is aimed at Linux desktop users who already use Bash and want command-line data in a graphical panel. Documented examples include showing the latest GNOME Shell log entry, launching applications, embedding a downloaded icon, and creating an application menu generated from installed desktop entries. The plugin model is practical for scripts that check system state, fetch information, or provide short commands.

Argos is not a complete replacement for GNOME Shell extension development. Its interface is intentionally narrow: an executable produces text and optional action metadata. Projects that need extensive direct interaction with GNOME Shell components may still need to use the platform's JavaScript APIs. Argos is better suited to panel menus than to extensions whose main purpose is changing the shell's broader window management or visual behavior.

From Executable Output to GNOME Panel Menu

The central mechanism is documented directly in the README: Argos turns executables' standard output into panel dropdown menus. Each plugin performs its own work, prints a menu description, and lets Argos handle the panel presentation. Separators written as `---` divide menu groups. Pipes attach metadata and actions to individual rows, including `iconName`, `image`, `href`, `bash`, `terminal`, and `eval`.

The log viewer example reads one entry from the GNOME Shell journal, formats the text with GNOME Shell markup, and adds a `View GNOME Shell Log` action. The filename `shell_log.1s.sh` indicates a one-second refresh according to the README's explanation. The launcher example combines several row types in one script. It can launch `gedit`, open `nautilus`, run `top`, visit a URL, or evaluate an expression that toggles GNOME Shell's Looking Glass interface.

This architecture separates data collection from presentation. Bash can handle shell commands, text processing, and HTTP requests, while Python can call `Gio` to enumerate installed applications. The README describes an asynchronous execution engine that schedules scripts intelligently and prevents slow plugins from blocking. That design is important for plugins that fetch remote data or run commands that may take longer than a normal menu refresh.

Selecting the Correct Argos Installation Branch

The README gives different installation references for different GNOME Shell releases. GNOME Shell 45 and newer use the `master` branch. GNOME Shell 42 through 44 use the `GNOME-44` tag, while GNOME Shell 3.26 through 41 use the `GNOME-41` tag. The repository listing contains no GitHub releases, so the documented branch or tag is the relevant upgrade path shown by the project.

For GNOME Shell 44, the documented commands are:

git clone https://github.com/p-e-w/argos
git switch -c gnome-44 GNOME-44

After selecting the appropriate version, copy or symlink `[email protected]` into `~/.local/share/gnome-shell/extensions`. On GNOME/X11, restart GNOME Shell by pressing `Alt+F2` and entering `r`. On Wayland, log out and log back in. The README also says that some systems require enabling Argos through the GNOME Extensions application or GNOME Tweak Tool.

The GNOME Shell Extensions website route has a documented boundary. The README says Argos for GNOME Shell 3.34 and later, including GNOME 40 and later, is not available through `extensions.gnome.org`. For those versions, the repository instructions are the documented installation route. The README does not provide one automated command that performs the copy, symlink, restart, and enablement sequence.

Building an Argos GNOME Shell Log Viewer

The first documented plugin is a Bash executable placed in `~/.config/argos`. It reads the latest GNOME Shell log entry, wraps it in markup, and defines a terminal action for viewing the complete log. The exact script from the README is:

#!/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 the file executable and put it in `~/.config/argos`. The panel should then show a menu containing the latest log entry and a `View GNOME Shell Log` item. The `.1s.sh` suffix requests one-second updates. Clicking the action runs the `journalctl` command shown in the output.

The example makes the plugin contract concrete. The script owns the `journalctl` call, chooses the text formatting, and declares the action. Argos owns the panel button and menu presentation. It also shows that output can combine content, styling, separators, and commands without a separate configuration file. The README does not document a command for validating a plugin before loading it, so the first practical check is whether the menu appears and refreshes in the target shell.

Argos Launchers for Applications and GNOME Actions

The README presents launchers as another main use case. In the Bash example, a plugin prints an initial `Launcher` row, a separator, and entries for Wikipedia, `gedit`, Nautilus, `top`, and Looking Glass. The `bash` field identifies the command to execute. `terminal=false` keeps an application action inside the graphical desktop, while `iconName` selects a theme icon. The `eval` field can call GNOME Shell imports directly.

The example also downloads the Wikipedia favicon through `curl`, encodes it with `base64`, and places it in an `image=` field. The image is therefore generated at runtime and passed through the menu output without being saved as a separate asset. This is useful when a menu should reflect current network content or local state rather than a fixed extension configuration.

Python plugins can perform richer local discovery. The README's `launcher.py` uses `Gio.AppInfo.get_all()` to gather applications, skips entries without icons or categories, removes `%U` and `%F` placeholders from command lines, groups applications by category, and prints rows with `useMarkup=false`. That creates a menu based on installed applications rather than a manually maintained launcher list. The documented contract remains executable output, so the practical requirement is a correctly executable script that prints the menu syntax.

Argos Compatibility and Upgrade Constraints

The main limitation is that installation depends on the GNOME Shell version. The README requires separate tags for older supported ranges and says that recent Argos versions are not available through the Extensions website. A user cannot safely treat every repository reference as interchangeable. The target shell version should be checked before cloning, switching branches, or copying the extension directory.

BitBar compatibility is another bounded feature. The README claims compatibility with BitBar 1.9.2 and says BitBar plugins that run on Linux work without modification. Plugins containing macOS-specific code are outside that claim. Compatibility therefore depends on the plugin actually being portable to Linux, not only on its filename or syntax.

The repository is not archived, and its last push was on 2026-05-04. The README describes Argos as optimized for low resource consumption, but it does not provide a reproducible measurement procedure, so no specific performance figure should be inferred. There are no GitHub releases in the repository listing, which means upgrades follow the documented Git branches and tags. The repository metadata does not identify a license. Users considering redistribution or incorporation into a larger project must locate and review the applicable license terms rather than assume a permissive license.

Editorial conclusion

Argos is appropriate for Linux users who want lightweight status displays or launch actions in GNOME Shell and are comfortable maintaining executable scripts. It is a poor fit for extensions requiring substantial GNOME Shell internals or a stable release package. Before adoption, verify the GNOME Shell version, the documented branch or tag, and the repository license, which is not identified in the project metadata.

Frequently asked questions

Official sources

1. Issues
2. p-e-w/argos on GitHub
3. Project website
4. README