FAQ

Common questions and answers about jolt.

General

Does jolt work on Linux?

Yes! jolt supports Linux with the same features as macOS:

✅ Battery status (percentage, state, health, cycles)
✅ Power metrics (watts) via RAPL
✅ Process list with CPU usage
✅ All TUI features

Note: Power metrics on Linux require permissions. See installation guide.

Does jolt work on Intel Macs?

Yes, but with limited functionality. Intel Macs will show:

✅ Battery status (percentage, state, health, cycles)
✅ Process list with CPU usage
❌ Power metrics (watts) — requires Apple Silicon

For full power metrics on Intel hardware, use Linux with RAPL support.

Does jolt work over SSH?

Yes! jolt is fully terminal-based and works great over SSH:

ssh myserver
jolt

Make sure your terminal supports 256 colors for the best experience.

Does jolt work in tmux/screen?

Yes, jolt works in terminal multiplexers. If you experience display issues:

# In tmux, ensure 256 color support
set -g default-terminal "screen-256color"

How much battery does jolt itself use?

Very little. At the default 1-second refresh rate:

~0.1-0.2% CPU usage
~15-20 MB memory

Use --low-power mode to reduce even further.

Can I use jolt in scripts?

Yes! Use pipe mode for JSON output:

jolt pipe --samples 1 | jq '.battery.percentage'

Battery & Power

Why is “Time Remaining” sometimes inaccurate?

The time remaining is calculated based on current power consumption. It changes as your workload changes. A sudden increase in CPU usage will immediately affect the estimate.

What’s the difference between battery health and charge?

Charge — Current battery level (0-100%)
Health — Maximum capacity compared to original design (degrades over time)

A battery at 100% charge but 80% health can only hold 80% of its original capacity.

Why don’t I see power metrics (watts)?

Power metrics require platform-specific hardware support:

macOS:

Apple Silicon Mac (M1/M2/M3/M4)
macOS 11.0 or later

Intel Macs cannot report per-component power consumption.

Linux:

Intel or AMD CPU with RAPL support (kernel 3.13+)
Proper permissions configured

See the installation guide for Linux setup.

What does “Not Charging” mean?

Your Mac is connected to power but not charging. This happens when:

Battery is optimizing charge (staying at 80%)
Charger wattage is too low
Battery temperature is too high/low

How accurate are the power numbers?

Very accurate. jolt reads directly from Apple’s IOReport framework, the same source used by Activity Monitor and system power management.

Processes

Why do some processes show high energy impact with low CPU?

Energy impact considers more than CPU:

Disk I/O
Network activity
GPU usage
Wake frequency (waking from idle)

A process can have low CPU but high disk I/O, resulting in elevated energy impact.

Can I kill processes from jolt?

Yes! Select a process and press K. You’ll be asked to confirm before the process is killed.

Why are some processes grouped together?

jolt groups parent and child processes. Press Enter to expand a group and see individual children.

Themes

Where are themes stored?

Built-in themes: Bundled with jolt
Custom themes:
- macOS: ~/Library/Application Support/jolt/themes/
- Linux: ~/.config/jolt/themes/
Imported themes: Same as custom themes

How do I import an iTerm2 theme?

# From CLI
jolt theme import "Dracula"

# Or from TUI
# Press T, then i, search and select

My theme looks wrong

Check terminal color support:

echo $TERM
# Should show xterm-256color or similar

Validate theme:
Terminal window
```
jolt theme check --theme my-theme
```
Try a built-in theme to compare:
Terminal window
```
jolt --theme default
```

Daemon

Why use the daemon?

The daemon collects data continuously, even when you’re not running jolt. This enables:

Historical analysis
Trend tracking
Export and reporting

Does the daemon use a lot of resources?

No. The daemon:

Uses <0.1% CPU
Uses ~10 MB memory
Writes to disk once per minute (by default)

How do I know if the daemon is running?

jolt daemon status

Or in the TUI, press d to see daemon info.

Can I run jolt without the daemon?

Yes! The daemon is optional. The TUI works independently with real-time data.

Troubleshooting

jolt shows “Permission denied”

Some features require permissions:

Full Disk Access — For some process information
Automation — For system preference detection

Grant permissions in System Settings → Privacy & Security.

The display looks corrupted

Try:

Resize your terminal window
Press Ctrl+L to redraw
Check terminal color support
Try a different terminal emulator

jolt is slow/laggy

Increase refresh interval:
Terminal window
```
jolt --refresh-ms 2000
```
Use low power mode:
Terminal window
```
jolt --low-power
```
Check for resource-heavy processes in the list

Config changes aren’t applying

Check config file location:
Terminal window
```
jolt config --path
```

Validate config syntax:

macOS:

cat ~/Library/Application\ Support/jolt/config.toml

Linux:

cat ~/.config/jolt/config.toml

Reset to defaults:
Terminal window
```
jolt config --reset
```