catfood-bar 0.3.0

A system bar component of the catfood utility suite
Documentation

Catfood Bar =,=

Catfood Bar

A customizable system status bar built with Rust and extensible with Lua. Part of the catfood utility suite.

Features

  • Modular Components: Choose from 13+ built-in components or create custom Lua components
  • Live Configuration: Hot-reload config changes without restarting
  • Sparkline Visualization: Real-time usage graphs for system metrics
  • Multi-Bar Layout: Left, middle, and right bar sections
  • Color Support: Optional colorize mode (TODO: Configurable color themes)
  • Error Handling: Graceful error display and logging

Installation

Dependencies

  • Rust 1.70+
  • Hyprland
  • NetworkManager
  • lm-sensors (for component temperatures)
  • kitty terminal (makes use of kitten panel to render the bar)

[!NOTE] You may wish to try using catfood without the Kitty terminal emulator. Functionality is not guaranteed in this case, but you are free to experiment using the --no-kitten command line flag.

From crates.io

# Install the bar component
cargo install catfood-bar

From Source

# Build and install
cargo install --path crates/bar

# Or build and run locally
cargo run --release --bin catfood-bar

Usage

Run the system bar:

catfood-bar

When run through the main catfood CLI, it automatically spawns in a kitty panel:

# Top of screen (default)
catfood bar

For other purposes, you can still run the catfood-bar binary independently:

# Bottom of screen
kitten panel --edge=bottom catfood-bar

Configuration

Configuration is stored in ~/.config/catfood/bar.json. The first run creates a default config with all components enabled.

Basic Configuration

{
  "bars": {
    "left": ["workspaces"],
    "middle": ["time", "separator", "weather"],
    "right": [
      "temperature",
      "cpu",
      "ram",
      "separator",
      "wifi",
      "separator",
      "brightness",
      "volume",
      "separator",
      "battery"
    ]
  },
  "colorize": true
}

Component Types

Components can be specified as either strings or objects with additional options:

String Components

{
  "bars": {
    "right": ["cpu", "ram", "wifi"]
  }
}

Object Components with Options

{
  "bars": {
    "right": [
      {
        "name": "cpu",
        "sparkline": true,
        "sparkline_length": 8,
        "sparkline_update_freq": 2
      }
    ]
  }
}

Available Components

System Monitoring

  • workspaces - Hyprland workspace switching
  • windows - Window management info
  • cpu - CPU usage percentage (supports sparkline)
  • ram - Memory usage percentage (supports sparkline)
  • temperature - CPU temperature
  • battery - Battery status and percentage

Network

  • wifi - WiFi connection status and signal strength (supports sparkline)
  • weather - Current weather information

Audio & Display

  • volume - System volume level
  • brightness - Screen brightness

Time & Date

  • time - Current date and time

Layout Components

  • separator - Visual separator (" | ")
  • space - Single space character for fine spacing

Sparkline Components

The following components support sparkline visualization:

  • cpu - Real-time CPU usage graph
  • ram - Memory usage over time
  • wifi - WiFi signal strength history

Sparkline Options

  • sparkline (default: false) - Enable sparkline mode
  • sparkline_length (default: 10) - Graph width in characters
  • sparkline_update_freq (default: varies) - Update frequency in seconds
    • CPU: 3 seconds
    • RAM: 2 seconds
    • WiFi: 2 seconds
  • sparkline_logarithmic (default: false) - Use logarithmic scaling

Custom Lua Components

Create custom components in ~/.config/catfood/components/*.lua:

Component Structure

Each Lua component should return a table with the following structure:

return {
    -- Optional configuration
    config = {
        -- Component-specific settings
    },
    
    -- Optional update function (called periodically)
    update = function()
        -- Update internal state or fetch external data
    end,
    
    -- Required render function
    -- Returns text to display, optionally with color
    render = function(colorize)
        -- colorize: boolean indicating if colors should be used
        -- Returns either:
        -- 1. A string: "text"
        -- 2. A table: {"text", "color"}
        
        return {"12:34", "yellow"}
    end
}

Available Colors

Lua components can use the following color names:

  • red, green, yellow, blue, magenta, cyan, white, black
  • gray/grey, dark_red, dark_green, dark_yellow, dark_blue, dark_magenta, dark_cyan, dark_gray

![NOTE] Color support is a work in progress. Not all of these colors may work. In future, user-defined colors may be supported along with fallback values for more restricted terminal color-spaces.

Example Components

Simple Clock Component
return {
    config = {
        show_seconds = true
    },
    
    render = function(colorize)
        local time = os.date("%H:%M")
        if true then -- show_seconds from config
            time = os.date("%H:%M:%S")
        end
        
        if colorize then
            local hour = tonumber(os.date("%H"))
            local color = "yellow"
            if hour < 6 or hour >= 18 then
                color = "magenta"
            end
            return {time, color}
        else
            return {time, nil}
        end
    end
}
System Uptime Component
return {
    update = function()
        -- Store uptime in component state (simplified)
        _uptime = io.open("/proc/uptime"):read("*a"):match("(%d+)")
    end,
    
    render = function(colorize)
        local uptime = tonumber(_uptime) or 0
        local hours = math.floor(uptime / 3600)
        local minutes = math.floor((uptime % 3600) / 60)
        local text = string.format("Uptime: %dh %dm", hours, minutes)
        
        if colorize then
            return {text, "green"}
        else
            return {text, nil}
        end
    end
}

Installation

  1. Create the components directory:

    mkdir -p ~/.config/catfood/components

  2. Add your Lua component files (.lua extension)

  3. Reference them in config.json by filename (without extension)

  4. Restart catfood_bar or wait for automatic config reload

Error Handling

  • If a Lua component fails to load or has errors, it will display as ❌ component_name
  • Built-in components are unaffected by Lua component failures
  • Check application logs for detailed error information

Limitations

  • Lua components run in the same process as the main application
  • Long-running operations in update() may affect UI responsiveness
  • No direct file system or network access beyond standard Lua libraries (can be extended if needed)
  • Component state is not persisted across restarts

Configuration Examples

Minimal Setup

{
  "bars": {
    "left": ["workspaces"],
    "middle": ["time"],
    "right": ["battery"]
  }
}

System Monitoring Focus

{
  "bars": {
    "left": ["workspaces"],
    "middle": ["time", "separator", "temperature"],
    "right": [
      {"name": "cpu", "sparkline": true, "sparkline_length": 8},
      "space",
      {"name": "ram", "sparkline": true, "sparkline_length": 8},
      "separator",
      {"name": "wifi", "sparkline": true, "sparkline_length": 10}
    ]
  }
}

Compact Layout

{
  "bars": {
    "left": ["workspaces"],
    "middle": ["time"],
    "right": [
      {"name": "cpu", "sparkline": true, "sparkline_length": 4},
      "space",
      {"name": "ram", "sparkline": true, "sparkline_length": 4},
      "space",
      {"name": "wifi", "sparkline": true, "sparkline_length": 4}
    ]
  }
}

Advanced Configuration

Component Reference

Special Components

kitty_tabs - Kitty terminal tabs with program icons

  • Requires kitty --single-instance flag for proper detection
  • Active tab: Shows full tab title (up to 20 chars)
  • Inactive tabs: Shows program icons only for compact display
  • Supports nvim, vim, htop, btop, git, ssh, cargo, and more
  • Custom socket path configuration available:
{
  "name": "kitty_tabs",
  "socket_path": "/tmp/custom-kitty-socket"
}

separator - Visual separator (" | ") space - Single space character for fine spacing

Sparkline Configuration

The cpu, ram, and wifi components support sparkline mode with these options:

  • sparkline (default: false) - Enable sparkline mode
  • sparkline_length (default: 10) - Graph width in characters
  • sparkline_update_freq (default: varies) - Update frequency in seconds
  • sparkline_logarithmic (default: varies by component) - Use logarithmic scaling

Sparkline Scaling

Linear Scaling (default for CPU/RAM)

  • Equal percentage changes have equal visual impact
  • Best for bounded ranges like percentages

Logarithmic Scaling (default for WiFi)

  • Equal ratio changes have equal visual impact
  • Best for data with high dynamic range (network traffic)
  • Small values remain visible when large values are present

Scaling Examples

// CPU with linear scaling (default)
{
  "name": "cpu",
  "sparkline": true,
  "sparkline_length": 10,
  "sparkline_update_freq": 3
}

// WiFi with logarithmic scaling (default)
{
  "name": "wifi",
  "sparkline": true,
  "sparkline_length": 15,
  "sparkline_update_freq": 2
}

// Override: CPU with logarithmic scaling
{
  "name": "cpu",
  "sparkline": true,
  "sparkline_length": 10,
  "sparkline_update_freq": 3,
  "sparkline_logarithmic": true
}

// Override: WiFi with linear scaling
{
  "name": "wifi",
  "sparkline": true,
  "sparkline_length": 15,
  "sparkline_update_freq": 2,
  "sparkline_logarithmic": false
}

Additional Configuration Examples

Network Focus

{
  "bars": {
    "left": ["workspaces"],
    "middle": ["time", "separator", "weather"],
    "right": ["wifi", "separator", "battery"]
  }
}

Terminal Workflow Focus

{
  "bars": {
    "left": ["workspaces", "separator", "kitty_tabs"],
    "middle": ["time"],
    "right": ["wifi", "separator", "battery"]
  }
}

Full System Monitoring with Sparklines

{
  "bars": {
    "left": ["workspaces"],
    "middle": ["time", "separator", "weather"],
    "right": [
      {
        "name": "cpu",
        "sparkline": true,
        "sparkline_length": 8,
        "sparkline_update_freq": 2
      },
      "space",
      {
        "name": "ram", 
        "sparkline": true,
        "sparkline_length": 8
      },
      "separator",
      {
        "name": "wifi",
        "sparkline": true,
        "sparkline_length": 10
      },
      "separator",
      "battery"
    ]
  }
}

Mixed Traditional and Sparkline Display

{
  "bars": {
    "left": ["workspaces"],
    "middle": ["time"],
    "right": [
      {
        "name": "cpu",
        "sparkline": true,
        "sparkline_length": 12
      },
      "separator",
      "ram",
      "separator",
      "wifi"
    ]
  }
}

Custom Grouping

{
  "bars": {
    "left": ["workspaces"],
    "middle": ["time", "separator", "weather"],
    "right": [
      "temperature", "cpu", "ram",
      "separator", "separator",
      "wifi",
      "separator",
      "brightness", "volume", "battery"
    ]
  }
}

Fine-tuned Spacing

{
  "bars": {
    "left": ["workspaces"],
    "middle": ["time", "space", "separator", "space", "weather"],
    "right": [
      "temperature", "space", "cpu", "space", "ram",
      "separator",
      "wifi", "space",
      "separator",
      "brightness", "space", "volume", "space", "battery"
    ]
  }
}

Minimal with Custom Spacing

{
  "bars": {
    "left": ["workspaces"],
    "middle": ["time", "space", "weather"],
    "right": ["wifi", "space", "battery"]
  }
}

Hot-Reload

Configuration changes are applied automatically:

  1. Edit ~/.config/catfood/bar.json
  2. Save the file
  3. Changes appear instantly without restarting

Logging

Errors are logged to ~/.local/share/catfood/logs/bar.log:

2025-12-21T03:45:12Z [ERROR] [COMPONENT_WORKSPACES] Error: Failed to get workspaces
2025-12-21T03:45:13Z [ERROR] [CONFIG] Failed to reload configuration: ...

The log maintains the last 1000 lines.

License

Copyright (c) Thom Bruce thom@thombruce.com

Licensed under the MIT license.