jolt

repository·main·Indexed 19 days ago

A terminal-based battery and energy monitor for macOS and Linux. It provides a themeable TUI for real-time insights into power consumption, process energy usage, and battery health. The project includes the jolt-tui CLI and the jolt-platform crate, which abstracts battery and power monitoring across different operating systems.

Tokens: 51.3K
Snippets: 202
Records: 267
Agent score: 66%

What's inside jolt

Overview of jolt features
main
jolt is a terminal-based battery and energy monitor designed for macOS and Linux. It is specifically built for users who work in terminal environments, use SSH, or use terminal multiplexers like tmux where GUI-based monitors (like Activity Monitor or GNOME Power Statistics) are unavailable.
Key capabilities include:
- Battery Status: View charge percentage, time remaining, health, cycle count, and charger wattage.
- Power Metrics: Monitor system power draw (CPU, GPU, and total watts). On Apple Silicon, it also tracks ANE (Neural Engine) power.
- Process Tracking: Identify energy-intensive processes, sorted by impact with color-coded severity. You can expand parent processes to view children and kill energy-consuming processes directly from the UI.
- Extensibility: Supports JSON output for scripting and logging, and allows importing 300+ iTerm2 color schemes.
https://github.com/jordond/jolt/blob/main/website/src/content/docs/docs/getting-started.md
Understand the Starlight project structure
main
Starlight projects follow a specific directory structure for content and assets:
- Documentation Content: Place .md or .mdx files in src/content/docs/. Each file name determines its route.
- Images: Store images in src/assets/ and embed them in Markdown using relative links.
- Static Assets: Place files like favicons in the public/ directory.
- Configuration: Core settings are managed in astro.config.mjs and content.config.ts.
```
.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   └── docs/
│   └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json
```
https://github.com/jordond/jolt/blob/main/website/README.md

Create custom themes using TOML

main

Custom themes are defined as TOML files containing color definitions for both [dark] and [light] modes. Each mode must define specific color tokens to ensure proper rendering.

Color Tokens Reference

Token	Usage
`background`	Main background
`foreground`	Default text
`border`	Panel borders
`accent`	Highlights, selection
`muted`	Secondary text
`battery_high`	Battery > 50%
`battery_medium`	Battery 20-50%
`battery_low`	Battery < 20%
`impact_low`	Low energy impact
`impact_moderate`	Moderate impact
`impact_elevated`	Elevated impact
`impact_high`	High impact

Example Theme Structure

[dark]
background = "#282a36"
foreground = "#f8f8f2"
border = "#44475a"
accent = "#bd93f9"

# Battery gauge colors
battery_high = "#50fa7b"
battery_medium = "#f1fa8c"
battery_low = "#ff5555"

# Energy impact colors
impact_low = "#50fa7b"
impact_moderate = "#f1fa8c"
impact_elevated = "#ffb86c"
impact_high = "#ff5555"

[light]
# Light mode colors...

Understand Process Energy Impact
main
jolt calculates an energy impact rating for processes based on CPU, GPU, disk, and network activity. These are categorized by color-coded levels:
Level Color Description
Low Green Minimal battery impact
Moderate Yellow Normal usage
Elevated Orange Higher than typical
High Red Significant battery drain
Analysis Tips:
- Steady high impact: The process is consistently intensive.
- Spikes: Occasional intensive tasks (usually normal).
- High impact background processes: May indicate a runaway process that should be investigated.
https://github.com/jordond/jolt/blob/main/website/src/content/docs/docs/understanding-metrics.md
How jolt-platform abstracts battery and power monitoring
main
The jolt-platform crate provides a platform-agnostic way to monitor battery and power metrics using two core traits: BatteryProvider and PowerProvider.
It abstracts the underlying OS differences (macOS vs. Linux) so your application can interact with a unified interface.
- macOS implementation: Uses the battery crate for basics, ioreg for advanced battery metrics (like charger wattage), and the IOReport framework/SMC for highly accurate power measurements (CPU, GPU, ANE, and System power).
- Linux implementation: Uses the battery crate for basics, sysfs for battery status, RAPL for CPU power, and hwmon for GPU power.
Because implementations are platform-specific, you must use conditional compilation (#[cfg(target_os = "...")]) to instantiate the correct provider for your target OS.
```
use jolt_platform::{BatteryProvider, PowerProvider};

#[cfg(target_os = "macos")]
use jolt_platform::macos::{MacOSBattery, MacOSPower};

#[cfg(target_os = "linux")]
use jolt_platform::linux::{LinuxBattery, LinuxPower};

fn main() -> color_eyre::Result<()> {
    #[cfg(target_os = "macos")]
    let mut battery = MacOSBattery::new()?;
    
    #[cfg(target_os = "linux")]
    let mut battery = LinuxBattery::new()?;
    
    battery.refresh()?;
    
    let info = battery.info();
    println!("Charge: {:.1}%", info.charge_percent);
    
    Ok(())
}
```
https://github.com/jordond/jolt/blob/main/crates/platform/README.md
Interpret energy impact colors in the Process List
main
The Process List uses color indicators to represent the energy impact level of each process:
- 🟢 Green: Low (Minimal battery impact)
- 🟡 Yellow: Moderate (Some battery drain)
- 🟠 Orange: Elevated (Above normal usage)
- 🔴 Red: High (Significant battery drain)
https://github.com/jordond/jolt/blob/main/website/src/content/docs/docs/tui-interface.md
Interpret Power Metrics and Consumption
main
jolt tracks power consumption in Watts (W) to help you understand battery drain.
Total Power (Watts)
This is the combined draw of all components. Typical usage levels include:
- 2-5W: Idle or light tasks.
- 5-15W: Web browsing or document editing.
- 15-30W: Development or video calls.
- 30-50W: Video editing or compilation.
- 50W+: Heavy workloads or gaming.
Platform Limitations:
- Intel Macs: Cannot report power consumption.
- Linux: Requires RAPL support and appropriate permissions.
Component-Specific Power
- CPU Power: Power used by processor cores (efficiency and performance cores on Apple Silicon).
- GPU Power: Power used by the graphics processor (increases with external displays, video playback, or GPU compute workloads).
- ANE Power (Neural Engine): Power used by Apple's Neural Engine for ML tasks (Siri, photo analysis, Core ML).
Power Mode (macOS only)
- Low Power: Reduced performance to save battery.
- Normal: Balanced performance.
- High Performance: Maximum performance (typically when plugged in).
https://github.com/jordond/jolt/blob/main/website/src/content/docs/docs/understanding-metrics.md
Extend an existing theme
main
You can create a theme that inherits from another by using the extends key. This allows you to only override the specific colors you want to change.
```
extends = "dracula"

[dark]
# Only override specific colors
accent = "#ff79c6"
```
https://github.com/jordond/jolt/blob/main/website/src/content/docs/docs/custom-themes.md
How jolt aggregates historical data
main
To maintain storage efficiency, jolt automatically aggregates older data into different resolutions based on its age:
Age Resolution
< 24 hours Full resolution
1-7 days Hourly averages
7-30 days 4-hour averages
> 30 days Daily averages
This ensures the database remains manageable while preserving long-term trends.
https://github.com/jordond/jolt/blob/main/website/src/content/docs/docs/historical-data.md
Monitor battery and power usage in jolt
main
jolt provides real-time monitoring of your system's energy state:
Battery Health
The battery panel displays:
- Current charge percentage
- Charging state (charging, discharging, full)
- Time remaining estimate
- Battery health percentage
- Cycle count
Power Metrics
The power panel shows real-time wattage for:
- Total: Combined system power draw
- CPU: Processor power consumption
- GPU: Graphics power consumption
- ANE: Neural Engine power (Apple Silicon only)
Note: Power metrics are unavailable on Intel Macs and require RAPL permissions on Linux.
https://github.com/jordond/jolt/blob/main/website/src/content/docs/docs/quick-start.md
Hardware requirements for power metrics
main
While basic battery data is available on most supported systems, advanced power metrics (CPU, GPU, and total system watts) require specific hardware support:
- macOS: Requires Apple Silicon (M-series chips) to access CPU, GPU, and ANE power metrics.
- Linux: Requires RAPL (Running Average Power Limit) support.
Note: Intel-based Macs will only display basic battery data and will not show detailed power metrics.
https://github.com/jordond/jolt/blob/main/website/src/content/docs/docs/getting-started.md

Level	Color	Description
Low	Green	Minimal battery impact
Moderate	Yellow	Normal usage
Elevated	Orange	Higher than typical
High	Red	Significant battery drain

Age	Resolution
< 24 hours	Full resolution
1-7 days	Hourly averages
7-30 days	4-hour averages
> 30 days	Daily averages

Understand the jolt TUI layout

main

The jolt Terminal User Interface (TUI) is organized into several functional panels that provide a comprehensive view of your laptop's power state:

Battery Panel: Displays charge percentage, state (Charging, Discharging, etc.), estimated time, battery health, cycle count, and charger wattage.
Power Panel: Shows real-time power consumption metrics including Total watts, CPU, GPU, and ANE (Apple Neural Engine) power, along with the current power mode.
Process List: Lists running processes sorted by energy impact, including Name, PID, CPU usage, and an Energy impact rating.
Graph Panel: Provides a sparkline graph showing historical data for either battery percentage or power (watts) over time.
Status Bar: Located at the bottom, showing the current theme, refresh rate, key hints, and daemon connection status.

┌─────────────────────────────────────────────────────────┐
│  Battery Panel          │  Power Panel                  │
│  (charge, health)       │  (CPU, GPU, total watts)      │
├─────────────────────────┴───────────────────────────────┤
│  Process List                                           │
│  (sorted by energy impact)                              │
├─────────────────────────────────────────────────────────┤
│  Graph Panel                                            │
│  (battery % or power over time)                        │
├─────────────────────────────────────────────────────────┤
│  Status Bar                                             │
└─────────────────────────────────────────────────────────┘

jolt

What's inside jolt

Color Tokens Reference

Example Theme Structure

Total Power (Watts)

Component-Specific Power

Power Mode (macOS only)

Battery Health

Power Metrics