Custom Modules

This special module type lets you extend the functionality of Ashell by creating your own simple components.

A custom module allows you to:

• Display the output of a command (live updates from a continuously running process).
• Run a command when the module is clicked.
• Change icons dynamically based on output.
• Show an alert indicator based on specific conditions.

warning

Ashell comes with a set of default icons that are used internally.

If you specify a font icon in the custom module configuration remember to install the font with that icon on your system.

For example you can use Nerd Fonts

Configuration

To define a custom module, use the following fields:

• name: Name of the module. Use this to refer to it in the modules definitions.
• type (optional): Display type. Can be Button (clickable, default) or Text (display only).
• icon: Icon displayed in the status bar (for button type).
• command: Command to execute when the module is clicked (for button type).
• listen_cmd (optional): Command to run in the background to update the module’s display.
• icons (optional): Regex-to-icon mapping to change the icon based on the listen_cmd output (for button type`). The first matching regex wins; since the mappings are stored as a map, the evaluation order is not guaranteed. Prefer mutually exclusive regexes or keep patterns precise to avoid ambiguous matches.
• alert (optional): Regex to trigger a red alert dot on the icon when matched in the listen_cmd output (for button type).

---

listen_cmd

The listen_cmd is started once on startup and should continuously run in the background, outputting JSON whenever the module's display should be updated. The most recent output is used to update the module's display.

How listen_cmd Works

The listen_cmd is not executed periodically. Instead, it runs as a long-lived process that outputs JSON whenever the displayed information changes. This is ideal for:

• Status monitoring: Commands that watch for changes and output when they occur
• Event listeners: Commands that wait for specific events and report them
• Live data: Commands that continuously stream status updates

For example, a notification listener might output JSON only when new notifications arrive, rather than polling every second.

The listen_cmd should output JSON in the Waybar format, using text and alt fields.

Example Output

{
  "text": "3",
  "alt": "notification"
}

---

Dynamic Icons

You can change the icon depending on the value of alt in the listen_cmd output.

Icons Example

icons.'dnd.*' = ""

This will change the icon to  when alt matches dnd.*.

---

Alerts

Use the alert field to show a red dot on the module icon if the output matches a given regex.

Alerts Example

alert = ".*notification"

---

Examples

Text-only Module (e.g., Custom Clock)

Text modules display only the text output from listen_cmd without any click action:

[[CustomModule]]
name = "MyClock"
type = "Text"
listen_cmd = "echo '{\"text\": \"$(date +'%H:%M')\", \"alt\": \"\"}'"

Note for Fish Shell Users: If you use Fish shell, wrap the command in sh -c for POSIX compatibility:

listen_cmd = "sh -c 'while true; do echo \"{\\\"text\\\": \\\"$(date +\"%H:%M\")\\\", \\\"alt\\\": \\\"\\\"}\"; sleep 1; done'"

Button Module with Icon (Interactive)

Button modules display an icon and/or text with a click action:

[[CustomModule]]
name = "CustomNotifications"
type = "Button"
icon = ""
command = "swaync-client -t -sw"
listen_cmd = "swaync-client -swb"
icons.'dnd.*' = ""
alert = ".*notification"

Button Module with Icon Only

[[CustomModule]]
name = "AppLauncher"
type = "Button"
icon = "󱗼"
command = "walker"

Button Module with Text Output

Button modules can also display text output from listen_cmd with a click action:

[[CustomModule]]
name = "Clipboard"
type = "Button"
command = "cliphist-rofi-img | wl-copy"
listen_cmd = "echo '{\"text\": \"📋\", \"alt\": \"\"}'"

Notifications (with wired)

[[CustomModule]]
name = "CustomNotifications"
type = "Button"
icon = ""
command = "wired --show 5"
listen_cmd = "wired count"
icons.'dnd.*' = ""
alert = ".*notification"

[[CustomModule]]
name = "CustomNotifications"
icon = ""
command = "swaync-client -t -sw"
listen_cmd = "swaync-client -swb"
icons.'dnd.*' = ""
alert = ".*notification"

App Launcher (with walker)

[[CustomModule]]
name = "AppLauncher"
icon = "󱗼"
command = "walker"

Clipboard (with cliphist)

[[CustomModule]]
name = "Clipboard"
icon = "📋"
command = "cliphist-rofi-img | wl-copy"

Migration from Deprecated Modules

The AppLauncher and Clipboard modules have been deprecated in favor of custom modules. To migrate from the deprecated modules:

Previous App Launcher Configuration

# Old deprecated way
app_launcher_cmd = "walker"

New Custom Module Configuration

# New recommended way
[[CustomModule]]
name = "AppLauncher"
icon = "�"
command = "walker"

Previous Clipboard Configuration

# Old deprecated way
clipboard_cmd = "cliphist-rofi-img | wl-copy"

New Custom Module Configuration

# New recommended way
[[CustomModule]]
name = "Clipboard"
icon = "󰅏"
command = "cliphist-rofi-img | wl-copy"

Then add the custom modules to your modules configuration:

[modules]
right = [ [ "Clock", "Privacy", "Settings", "AppLauncher", "Clipboard" ] ]