Alien Conky Suite

A modular, feature-rich collection of 20 Conky scripts across 10 categories, designed to create a cohesive and interactive desktop experience. Run everything together or each component independently.

• All components are fully modular
• Designed for low clutter, high signal
• Easily customizable and extendable
• Conky scripts built on Linux Mint 22.3/Cinnamon Edition

---

Overview

Category	Scripts
Analog Clock	Analog Clock
Clock	Animated Clock, Now Playing (Song Info)
Weather	Current Conditions, Forecast, Full Panel
Calendar	Horizontal Calendar (Lua), Horizontal Calendar (Bash), khal calendar, allcombined Lua Calendar, Side Panel calendar
System	Single-line System Monitor
Network	vnStat Bandwidth Monitor
Arc	Enhanced Arc (weather + moon phase)
Google Calendar	Month-view (gcalcli + Lua)
RSS	Click-enabled Feed Viewer
Stocks	Current stock prices
Terminator	Day/night terminator map

The Earth Viewer component is adapted from the Aurora set.

---

Getting Started

Install conky and dependencies:

sudo apt install conky-all tmux curl xdotool vnstat jq python3-ephem playerctl librsvg2-bin luarocks gcalcli khal git fonts-ibm-plex

Install Alien:

cd ~/.conky
git clone https://github.com/rew62/alien.git
cd alien

Run the setup script:

./configure-alien.sh or ./configure-alien2.sh (includes automated font install)

This will:

• Create or update .env with:

  • OWM_API_KEY — OpenWeatherMap API key
  • FINNHUB_API_KEY — FinnHub API key (stocks widget)
  • CITY_ID — OWM city ID
  • LAT / LON — Latitude and longitude
  • UNITS — metric (Celsius) or imperial (Fahrenheit)
  • LANG — Language code (e.g. en, fr, de)
  • ICON_SOURCE — cdn or local weather icons
  • CACHE_TTL — Weather cache lifetime in seconds (default: 300)
  • INTERFACE_NAME — Network interface (auto-detected)
  • CRONPATH — Cron user (defaults to current user)

• Patch calendar/sys-small.rc with the active network interface

• Patch vnstat/vnstat.lua with the active network interface

• Update earth/crontab with the correct home path (if present)

• Run a font availability check or for ./configure-alien2.sh, installs the fonts in the fonts directory automatically.

See .env-example for the format reference.

---

Features

Interactive RSS Feed

• Clickable articles using xdotool

• Toggle feeds via the double-arrow control

• Fully customizable via:

  RSS/feeds.conf
  

Animated Clock Enhancements

• Seconds are visualized within the minute divider

Weather System

• Uses National Weather Service (NWS) data for forecast and openweathermap.org (OWM) API for current conditions.

  • Note - OWM requires an API key. You can obtain one free at https://openweathermap.org/

• Separate scripts for:

  • Current conditions
  • Forecast

Stock Price table display for current stock prices

• Requires an API key from FinnHub for stock data. You can obtain one free at https://www.finnhub.io/
• Customize stock symbols at stocks/symbols.conf

Arc Widget Enhancements

• Includes current forecast and moon phase rendering
• Expanded from original github/@gtex62 design

Modular Design

• Every widget runs independently:

  conky -c script.rc

tmux Integration

• Launch all widgets at once:

  ./alien-tmux

• Stop everything:

  tmux kill-session -t conky

alien-tmux2 — Selective Launch

alien-tmux2 lets you launch any subset of widgets by passing short codes as arguments. Up to 4 conky processes are grouped per tmux window; the layout is tiled automatically.

Usage:

# Launch specific widgets by code
./alien-tmux2 t a wc wf

# Or pass a bracketed, comma-separated list
./alien-tmux2 [t,a,wc,wf]

Widget Codes:

Code	RC File	Widget
ac	aclock/aclock.rc	Analog clock
a	arc/arc.rc	Arc (horizon, planets, sun/moon, weather)
e	earth/earth.rc	Earth satellite image viewer
g	gcal/gcal.rc	Google Calendar month-view
h2	calendar/hcal2.rc	Horizontal Lua calendar (full-width)
hc	calendar/hcal.rc	Horizontal calendar (compact, bash)
kc	calendar/kcalendar.rc	khal-based calendar panel
lc	calendar/lcalendar.rc	Lua-drawn allcombined calendar
m	clock/song-info.rc	Now Playing (song info)
r	rss/rss2.rc	RSS feed viewer
$	stocks/ticker.rc	Stock price table
s	calendar/sys-small.rc	Single-line system monitor
s2	calendar/sys-small2.rc	Single-line system monitor (larger font)
sc	calendar/sidepanel-calendar.rc	Side panel calendar
t	clock/clock.rc	Animated clock
v	vnstat/vnstat.rc	vnStat bandwidth monitor
vs	vnstat/vnstat-summary.rc	vnstat short
wa	weather/full.rc	Full weather panel
wc	weather/current.rc	Current conditions
wf	weather/forecast.rc	5-day forecast strip
tm	terminator/terminator.rc	Day/night terminator map

---

Directory and File Tree

├── alien.png
├── alien-tmux                          - launch all widgets via tmux
├── alien-tmux2                         - selective tmux launch (short codes)
├── background.png                      - Alien theme background (3440×1440)
├── aclock/                             [ac] Analog clock
│   └── aclock.rc
├── arc/                                [a]  Arc (horizon, planets, sun/moon, weather)
│   ├── arc.rc
│   ├── arc3.lua
│   ├── settings.lua
│   └── sky_update.py
├── calendar/
│   ├── hcal2.rc                        [h2] Horizontal Lua calendar (full-width)
│   ├── hcal.rc                         [hc] Horizontal calendar (compact, bash)
│   ├── kcalendar.rc                    [kc] khal-based calendar panel
│   ├── lcalendar.rc                    [lc] Lua-drawn allcombined calendar
│   ├── sidepanel-calendar.rc           [sc] Side panel calendar
│   ├── sys-small.rc                    [s]  Single-line system monitor
│   ├── sys-small2.rc                   [s2] Single-line system monitor (larger font)
│   ├── fmt.lua
│   ├── hcal2.lua
│   ├── hcal.sh
│   ├── khal-calendar.sh
│   ├── loadall.lua
│   └── settings.lua
├── clock/
│   ├── clock.rc                        [t]  Animated clock widget (0.5 s updates)
│   ├── song-info.rc                    [m]  Now Playing (song info)
│   ├── clock.lua
│   ├── loadall.lua
│   └── settings.lua
├── configure-alien.sh                  - interactive setup (API key, lat/lon, interface)
├── configure-alien2.sh                 - setup with automated font install
├── earth/                              [e]  Earth satellite image viewer
│   ├── earth.rc
│   ├── crontab
│   ├── fourmilab-earth.sh
│   ├── loadall.lua
│   └── settings.lua
├── fonts/                              - bundled font files
├── gcal/                               [g]  Google Calendar month-view
│   ├── gcal.rc
│   ├── gcal2.lua
│   ├── loadall.lua
│   └── settings.lua
├── rss/                                [r]  RSS feed viewer
│   ├── rss.rc
│   ├── feeds.conf
│   ├── rss-click.sh
│   ├── rss-daemon.sh
│   ├── rss-fetch.sh
│   ├── rss-next.sh
│   ├── loadall.lua
│   └── settings.lua
├── scripts/                            - shared scripts and Lua libraries
│   ├── owm_fetch.sh
│   ├── allcombined2.lua
│   ├── background.lua
│   ├── json.lua
│   ├── loadall.lua
│   └── lua3-bars.lua
├── stocks/                             [$]  Stock price table
│   ├── ticker.rc
│   ├── symbols.conf
│   ├── stocks.lua
│   ├── loadall.lua
│   └── settings.lua
├── terminator/                         [tm] Day/night terminator map
│   └── terminator.rc
├── theme.lua                           - global colors (borders, backgrounds)
├── utils/
│   ├── rc                              - shortcut launcher (place on PATH)
│   └── save-pos.sh                     - save all conky window positions
├── vnstat/                             [v]  vnStat bandwidth monitor
│   ├── vnstat.rc
│   ├── vnstat-summary.rc                   [vs] vnstat short
│   ├── vnstat.lua
│   ├── vnstat-summary.lua
│   ├── loadall.lua
│   └── settings.lua
└── weather/
    ├── current.rc                      [wc] Current conditions
    ├── forecast.rc                     [wf] 5-day forecast strip
    ├── full.rc                         [wa] Full weather panel
    ├── alien-weather-current.lua
    ├── alien-weather-forecast.lua
    ├── alien-weather-full.lua
    ├── loadall.lua
    ├── nws_weather.lua
    ├── owm-current.sh
    ├── owm-fetch.lua
    └── settings.lua

---

Utilities

• save-pos.sh — Calculates the current position of all running conkys. Using alt+mouse drag, relocate conkys to your desired position and in a separate terminal window run save-pos.sh. The script can also be run on individual windows using the keys below.

  Note: Each conky redraws at its next update interval. Widgets with long intervals (such as calendar scripts) should be restarted after repositioning to reflect the change immediately.

  Window Reference — keys used to target individual windows:

  Key	Window Title	RC File
  rss	rss	rss/rss.rc
  sys-small	sys-small	calendar/sys-small.rc
  sys-small2	sys-small2	calendar/sys-small2.rc
  current	w-current	weather/current.rc
  forecast	w-forecast	weather/forecast.rc
  full	w-full	weather/full.rc
  song-info	song-info	clock/song-info.rc
  clock	conky_clock	clock/clock.rc
  vnstat	vnstat	vnstat/vnstat.rc
  vnstat-summary	vnstat-summary	vnstat/vnstat-summary.rc
  hcal2	hcal2	calendar/hcal2.rc
  hcal	hcal	calendar/hcal.rc
  arc	conky-arc	arc/arc.rc
  sp-cal	sp-cal	calendar/sidepanel-calendar.rc
  khal-cal	khal-cal	calendar/kcalendar.rc
  ac-cal	ac-cal	calendar/lcalendar.rc
  earth	earth	earth/earth.rc
  gcal	gcal	gcal/gcal.rc
  stocks	stocks	stocks/ticker.rc

• rc — Place in your ~/bin or any directory on PATH. Run any conky script with rc conky, saving keystrokes. Useful for launching individual conkys quickly.

---

Theming

Global appearance is controlled via:

theme.lua

This file defines:

• Border colors
• Background colors
• Theme font

---

Dependencies

Required

• conky (with Lua + Cairo support)
• jq
• curl
• xdotool
• tmux
• vnstat
• python3

Calendar & Agenda

• khal — local calendar store; used by kcalendar.rc
• gcalcli — Google Calendar CLI; used by gcal.rc

Media

• playerctl — MPRIS media player control; used by song-info.rc

Fonts

Bundled (in fonts/):

• Orbitron
• Oxanium
• Barlow Condensed — rss.rc
• Metropolis — clock.rc, sidepanel-calendar.rc
• Good Times — sidepanel-calendar.rc, hcal2.rc

Additional fonts required (install separately):

• MonaspiceNe Nerd Font — primary monospace, earth.rc
• FiraCode Nerd Font — sys-small.rc, song-info.rc
• SpaceMono Nerd Font — sys-small.rc, song-info.rc

Nerd Fonts: https://www.nerdfonts.com/

Optional

• lua-cjson (fallback included in scripts/json.lua)
• librsvg2-bin (only needed if weather icons are returned as SVG and you want PNG conversion)

---

Credits

• github/@gtex62 — Original author of gtex62-clean-suite - weather widget formed the foundation of the enhanced Arc implementation
• github/@wim66 — Original author of background.lua, lua3-bars.lua
• allcombined2.lua - Original Lua scripting: Mr Peachy, Modified/Maintained by: github/@Fehlix (MX Linux Team), MX Linux Conky Collection
• Aurora Set — Source of the Earth Viewer component github @rew62/aurora

---