btop
Generates a btop theme file — the colours behind the resource monitor's CPU/memory/network/process boxes, gradient meters, temperature scales, and status text. btop is a curses-style TUI for terminals; it reads one .theme file at a time and re-reads it when sent SIGUSR2.
Installation
Built into tinct — nothing to install separately. tinct generate -o btop works out of the box.
Quick start
tinct generate -i image -p ~/Pictures/wallpaper.jpg -o btop
The first time, you also need to point btop at the theme — see Integration.
Generated files
| File | Path | Role |
|---|---|---|
tinct.theme | ~/.config/btop/themes/tinct.theme | btop theme file. Sets every theme[...] key btop recognises: backgrounds, foregrounds, gradient endpoints for CPU/memory/network/disk graphs, box outlines, and meter backgrounds. |
The filename matches --btop.theme-name (default tinct). The filename without .theme is also the value you put into btop's color_theme config key.
Integration
btop loads themes by name from ~/.config/btop/themes/. After the first generate, tell btop to use it — either edit the config:
# ~/.config/btop/btop.conf
color_theme = "tinct"
…or pick it interactively: press p (options menu) → cycle to "tinct" in the theme list → Esc to save.
The theme name is tinct by default; if you used --btop.theme-name=mything then it's "mything" instead.
Reload behaviour
Automatic
After writing the theme file the plugin sends SIGUSR2 to every running btop process (this is the verb declared in Hooks().Reload). btop traps that signal and re-reads its config + active theme, so the colours change live without exiting the TUI.
The reload only applies if color_theme = "tinct" is already set in btop.conf; otherwise btop re-reads the file but keeps using whichever theme it was already on. Use --btop.reload=false to skip the signal.
Manual fallback
If the signal didn't reach btop (it wasn't running at generate time, or you're in a different mount namespace):
pkill -SIGUSR2 -x btop
Or restart the process, or press p in the running TUI and re-select the theme.
Uninstall / revert
-
Remove the config line: edit
~/.config/btop/btop.confand either deletecolor_theme = "tinct"or change it to another theme name (e.g.color_theme = "Default"). -
Delete the generated file:
rm ~/.config/btop/themes/tinct.theme -
Reload to drop the theme:
pkill -SIGUSR2 -x btopOr restart btop. If
color_themestill pointed attinctyou may briefly see a missing-theme warning until you set it to something else. -
External state: this plugin only writes to
~/.config/btop/themes/. No further cleanup is required.
Flags
| Flag | Default | Description |
|---|---|---|
--btop.output-dir | ~/.config/btop/themes | Override the output directory |
--btop.theme-name | tinct | Theme name; written as <name>.theme and used as the color_theme value |
--btop.reload | true | Send SIGUSR2 to running btop instances after writing the theme |
Colour role mapping
| btop key | Tinct role | Notes |
|---|---|---|
main_bg | background | Terminal background; leave empty in the template for transparent terminals |
main_fg | foreground | Main text colour |
title | accent1 | Box titles |
hi_fg | accent2 | Highlighted shortcut keys |
selected_bg / selected_fg | accent1 / onAccent1 | Selected row in process list |
inactive_fg | foregroundMuted | Greyed-out text |
proc_misc | accent3 | Mini graphs in process box |
cpu_box, mem_box, net_box, proc_box | outline | Box borders |
div_line | outlineVariant | Divider line at top of each box |
temp_start / temp_mid / temp_end | success / warning / danger | Temperature gradient (cool → hot) |
cpu_start / cpu_mid / cpu_end | accent1 / accent2 / accent3 | CPU usage gradient |
free_start | success | Memory: free |
cached_start | info | Memory: cached |
available_start | accent2 | Memory: available |
used_start / used_mid / used_end | accent1 / warning / danger | Memory: used (low → critical) |
download_* / upload_* | info/accent1/accent2 and warning/accent3/danger | Network throughput gradients |
process_start / process_mid / process_end | accent1 / accent2 / accent3 | Process box graph |
meter_bg | surfaceContainer | Background of meter bars |
Customising the template
Dump the default template to override it:
tinct plugins templates dump -o btop -l ~/.config/tinct/templates/btop
This writes ~/.config/tinct/templates/btop/tinct.theme.tmpl. Tinct uses your copy in preference to the embedded default.
See the templating reference for available functions.
Troubleshooting
Theme didn't change
Check color_theme is actually set:
grep color_theme ~/.config/btop/btop.conf
If it's not "tinct" (or whatever --btop.theme-name you used), btop is reloading the file but ignoring it. Set it via p in the TUI or by editing the conf.
pkill: SIGUSR2: unknown signal
Some pkill implementations want -USR2 or numeric -12. The plugin uses Go's signal package so this only affects manual reload commands. Try:
pkill -USR2 -x btop
Theme list is empty inside btop
btop only scans ~/.config/btop/themes/ (plus its built-in themes). If tinct.theme is in a different directory (because you set --btop.output-dir), move or symlink it back, or accept that btop won't find it.
Background isn't transparent
main_bg is set to the theme background. To get terminal-transparent btop, override the template and set theme[main_bg]="" (empty string), or edit the generated file in place.