LookInfo is an experimental Linux information provider written in C++20. It runs in the foreground, periodically gathers selected local and network data, and writes human-readable values to files in a configurable per-user cache directory. Desktop components and scripts can read those files instead of duplicating polling and parsing logic.
The project is under active development. It currently supports TOML configuration and automated tests, but does not yet provide service-manager integration, graceful shutdown, or a stable cache schema.
LookInfo currently implements services for weather, memory, battery, wallpaper-path selection, and quotes. Weather, memory, battery, and wallpaper services are currently wired into the application and scheduled independently by a priority-queue scheduler. Services publish their latest value to files under a configured cache directory, falling back to $HOME/.cache/lookinfo.
The application reads its configuration from ~/.config/lookinfo/config.toml. Battery devices are discovered from Linux sysfs at runtime. See Configuration before running it.
Desktop widgets often repeat the same work: polling a weather API, reading /proc or /sys, maintaining timers, and formatting data. LookInfo explores a different boundary: collect data once in a small Linux process, then let presentation tools consume the latest cached value.
This separates data collection from presentation. It is intended to make integrations with tools such as Waybar, Hyprlock, Eww, and shell scripts simpler without coupling LookInfo to any one desktop environment.
Implemented today:
- C++20 executable built with CMake.
- Priority-queue scheduling based on
std::chrono::steady_clock. - Weather retrieval from the Open-Meteo API.
- Memory usage collection from
/proc/mem 8000 info. - Battery status collection through Linux sysfs device discovery.
- Random wallpaper-path selection from a configured local directory.
- TOML configuration for service enablement, intervals, weather coordinates, wallpaper directory, and cache directory.
- File-based cache output under the configured cache directory.
- GoogleTest coverage for configuration loading and service behavior.
Current limitations:
- QuoteService is implemented but is not currently registered by
src/main.cpp. - Quote data paths and battery/memory source paths are not configurable yet.
- The process runs indefinitely in the foreground and has no graceful signal handling.
- Cache files are plain presentation text, not a versioned machine-readable API.
- There is no systemd service or installation target yet.
flowchart TD
Main[src/main.cpp] --> Scheduler
Scheduler --> Weather[WeatherService]
Scheduler --> Memory[MemoryService]
Scheduler --> Battery[BatteryService]
Scheduler --> Wallpaper[WallpaperService]
Weather --> WeatherFile[weather.txt]
Memory --> MemoryFile[memory.txt]
Battery --> BatteryFile[battery.txt]
Wallpaper --> WallpaperFile[wallpaper.txt]
WeatherFile --> Cache[$HOME/.cache/lookinfo]
MemoryFile --> Cache
BatteryFile --> Cache
WallpaperFile --> Cache
The scheduler receives service objects and intervals. It waits until the next due task, calls update(), then requeues that task for a later run. Services are responsible for gathering their own data and writing their own cache output.
.
├── CMakeLists.txt Build definition
├── README.md
├── data/
│ └── quotes.txt Quote data used by QuoteService
├── include/
│ ├── IService.hpp Common service interface
│ ├── scheduler.hpp Priority-queue scheduler
│ ├── weather.hpp
│ ├── batteryService.hpp
│ ├── memoryService.hpp
│ ├── quoteService.hpp
│ ├── wallpaper.hpp
│ ├── fileHandler.hpp Cache-file writing helper
│ └── pathFinder.hpp Cache-directory helper
├── src/
│ ├── main.cpp Current application composition
│ ├── scheduler.cpp
│ ├── weather.cpp
│ ├── batteryService.cpp
│ ├── memoryService.cpp
│ ├── quoteService.cpp
│ ├── wallpaper.cpp
│ ├── fileHandler.cpp
│ └── pathFinder.cpp
└── trash/ Historical experiments; not built or supported
There are currently no release packages or installation rules. Build from a clone of this repository.
Requirements:
- Linux environment with
/procand/sys. - CMake 3.20 or newer.
- A C++20-capable compiler.
- libcurl development files discoverable by CMake.
- nlohmann/json headers available to the compiler.
Package names vary by distribution. For example, Debian/Ubuntu users will typically need development packages for libcurl and nlohmann/json in addition to CMake and a C++ compiler.
git clone https://github.com/KagE-Akumaa/lookinfo.git
cd lookinfo
cmake -S . -B build
cmake --build buildThe build produces build/lookinfo.
When GoogleTest is available, CMake also builds build/lookinfo_tests and
registers the tests with CTest.
LookInfo loads its configuration from:
~/.config/lookinfo/config.toml
The loader validates TOML types, positive intervals, coordinate ranges, and
non-empty paths. Invalid configuration stops startup with an error message.
The ~ prefix is expanded for configured cache and wallpaper paths.
Example:
[general]
cache_dir = "~/.cache/lookinfo"
[weather]
enabled = true
interval_seconds = 1800
latitude = 30.7333
longitude = 76.7794
[battery]
enabled = true
interval_seconds = 30
[memory]
enabled = true
interval_seconds = 10
[wallpaper]
enabled = false
interval_seconds = 300
directory = "~/Pictures/Wallpapers"
[quotes]
enabled = false
interval_seconds = 3600The currently supported settings are:
| Setting | Current value | Notes |
|---|---|---|
weather.enabled |
false |
Enables weather collection. |
weather.interval_seconds |
1800 |
Polling interval for Open-Meteo. |
weather.latitude / longitude |
0.0 |
Used to construct the Open-Meteo URL. |
battery.enabled |
true |
Enables battery collection. |
battery.interval_seconds |
30 |
Scans /sys/class/power_supply. |
memory.enabled |
true |
Enables memory collection. |
memory.interval_seconds |
10 |
Reads /proc/meminfo. |
wallpaper.enabled |
false |
Enables wallpaper-path selection. |
wallpaper.interval_seconds |
300 |
Scans the configured directory recursively. |
wallpaper.directory |
empty | Directory containing .jpg, .jpeg, or .png files. |
general.cache_dir |
empty | Uses $HOME/.cache/lookinfo when empty. |
Quote settings are parsed by the configuration loader but QuoteService is not
currently registered by the application. The [scheduler] section in the
example file is reserved for future use and is currently ignored.
Create the configuration directory and copy or create a configuration file:
mkdir -p ~/.config/lookinfo
cp config.example.toml ~/.config/lookinfo/config.tomlReview the paths and enabled services before starting LookInfo:
./build/lookinfoThe process continues running until it is terminated externally. It has no built-in graceful shutdown support yet.
Inspect currently written cache files from another terminal:
cat "$HOME/.cache/lookinfo/memory.txt"
cat "$HOME/.cache/lookinfo/battery.txt"
cat "$HOME/.cache/lookinfo/weather.txt"
cat "$HOME/.cache/lookinfo/wallpaper.txt"The actual cache location is controlled by general.cache_dir. The commands
above assume it is empty or set to $HOME/.cache/lookinfo.
A shell consumer can read a value directly:
printf 'Memory: %s\n' "$(cat "$HOME/.cache/lookinfo/memory.txt")"Consumers should tolerate missing files and temporarily unavailable data. Cache-file contents are not yet a stable API.
Output is formatted for display and can vary with the system and weather response. The current implementation prefixes memory, battery, and weather values with Unicode icons; [icon] below denotes that prefix without embedding it in the documentation.
# memory.txt
[memory icon] 5.3G / 15.4G
# battery.txt
[battery icon] 84% Discharging
# weather.txt
[weather icon] 18.4°C | ↑22.0° ↓12.1°
# wallpaper.txt
/home/example/Wallpapers/forest.jpg
The presentation strings are not a stable long-term API.
| Module | Source | Current status | Output |
|---|---|---|---|
| WeatherService | Open-Meteo HTTP API | Scheduled when enabled; default interval is 1800 seconds | weather.txt |
| MemoryService | /proc/meminfo |
Scheduled when enabled; default interval is 10 seconds | memory.txt |
| BatteryService | First discovered Battery device under /sys/class/power_supply |
Scheduled when enabled; default interval is 30 seconds | battery.txt |
| WallpaperService | Configured local wallpaper directory | Scheduled when enabled; default interval is 300 seconds | wallpaper.txt |
| QuoteService | ../data/quotes.txt relative to CWD |
Implemented, but not currently registered | quotes.txt |
Battery discovery reads each power-supply device's type file and uses the first device identified as Battery. On systems without a battery, battery.txt is written as an empty value. Multiple batteries are not aggregated; the selected device depends on the filesystem iteration order. Wallpaper selection recognizes .jpg, .jpeg, and .png extensions.
sequenceDiagram
participant S as Scheduler
participant Q as Priority queue
participant Service as Due service
S->>Q: Remove task with earliest next run
S->>S: Sleep until task deadline
S->>Service: update()
S->>Q: Requeue task at prior deadline + interval
The scheduler uses std::chrono::steady_clock, which is appropriate for measuring elapsed time because wall-clock adjustments do not move its time points. Updates execute synchronously on one scheduler thread; a slow service can therefore delay others.
The cache directory is selected from general.cache_dir. If it is empty, the
default is:
$HOME/.cache/lookinfo/
Each active service writes a single text file. Values are human-readable strings intended for desktop display, not structured records. There is currently no schema version, timestamp, freshness marker, or atomic-publication guarantee.
| File | Current content |
|---|---|
weather.txt |
Current, maximum, and minimum temperatures formatted as text. |
memory.txt |
Used and total memory in GiB formatted as text. |
battery.txt |
Battery percentage and status formatted as text. |
wallpaper.txt |
Absolute path of a selected image. |
quotes.txt |
Random quote text if QuoteService is invoked; not currently produced by main.cpp. |
The current composition root is src/main.cpp. It constructs services, selects output paths, and registers scheduled work. IService defines the common update() interface; Scheduler determines when updates are called.
When investigating or extending the implementation, start with:
include/IService.hppfor the service interface.src/scheduler.cppfor current scheduling behavior.src/main.cppfor active service registration and configuration wiring.- Individual service headers and sources for collection and formatting logic.
Adding a module is not yet documented as a stable extension API. In the current design, a new service needs to implement IService, write an output value, and be registered in src/main.cpp with an int
6AE1
erval. Please open or discuss an issue before introducing a new module so the configuration, error-handling, and cache-format implications can be considered.
The project has GoogleTest coverage for the services and configuration loader.
The trash/ directory contains historical experimental files and is not part
of the build or test process.
Configure, build, and run the tests with:
cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failureThe current test suite covers configuration defaults, valid values, invalid values, malformed TOML, filesystem errors, and service behavior.
Contributions are welcome, especially around correctness, portability, testing, configuration, and documentation. The repository does not yet have a formal contribution guide.
For now:
- Open an issue or comment on an existing issue before substantial changes.
- Keep changes focused on one concern.
- Build the project with the documented CMake commands.
- Explain tested environments and any Linux-specific assumptions in the pull request.
- Do not treat files in
trash/as supported implementation or test code.
Planned work includes:
- Robust cache publication and a documented cache schema.
- Graceful shutdown and operational logging.
- QuoteService integration and configurable quote-data paths.
- A systemd user-service setup for background operation.
- Command-line selection of the configuration file.
- CMake installation support and reproducible dependency declarations.
- Fixture-based and representative-layout testing for battery discovery.
- Improved portable resource paths.
- Optional IPC and plugin exploration after the core runtime is reliable.
See the issue tracker for current work items.
LookInfo is distributed under the MIT License.