Config

matchblox works without a config. The first run writes ~/.config/matchblox/config.toml with goals for this machine: load1_over is the number of cores, and the agents it finds. Every key is optional.

The service reads the config when it starts. To apply a change, stop the service and run matchblox again. The lock file next to the service socket holds its pid. With XDG_RUNTIME_DIR set (most Linux systems):

kill "$(cat "$XDG_RUNTIME_DIR/matchblox/matchblox.sock.lock")"
matchblox

Without it (macOS), the lock is in the temp directory:

kill "$(cat "${TMPDIR:-/tmp}/matchblox-$(id -u)/matchblox.sock.lock")"
matchblox

To use another file, give matchblox --config <file>.

Every key

# matchblox — copy to ~/.config/matchblox/config.toml and keep it local.
# Every key is optional; the values below are the defaults unless noted.

interval = "2s"          # cheap counters; processes every 3x, git every git.interval
agents = ["claude"]      # agent commands (default ["claude"]); the first run writes the ones it finds, e.g. ["claude", "codex", "opencode"]. Add any other by name
latency_target = ""      # host:port to time a TCP connect against every 10 s, e.g. "example.com:443"

[sessions]
compact_at = 85          # context % at which a session should compact
clear_idle = "30m"       # idle this long while holding clear_min_pct context: clear
clear_min_pct = 20
clear_stale = "24h"      # idle this long: clear whatever it holds
progress_prompt = true   # ask each new agent session for a progress bar; the console shows it
# [sessions.windows]     # context window by model-name prefix; it wins over the window the
# "some-model" = 1000000 # agent reports (Codex, OpenCode). Claude Code: 200k, or 1M when the
                         # model setting ends in [1m] or the session passed 200k

[alerts]                 # a zero threshold is off
temp_over_c = 95
load1_over = 0
load1_for = "2m"         # the condition must hold this long
psi_cpu_over = 0         # PSI cpu "some avg10", percent
psi_cpu_for = "2m"
mem_available_under_gb = 0
swap_over_gb = 0         # swap held although RAM is free:
swap_when_available_over_gb = 0
power_limits_w = []      # expected CPU package limits, long term then short term;
                         # empty alerts when a limit changes from its value at startup

[orphans]                # detached busy loops
cpu_over = 80            # percent of one core
for = "30s"
min_age = "2m"
commands = ["sh", "bash", "zsh", "dash", "fish"]   # empty: any command

# [[groups]]             # CPU share of containers whose name matches
# name = "CI runners"
# container = "runner"   # regular expression

[git]
interval = "5m"
# main = "main"         # default: the branch the remote's HEAD names
remote = "origin"
repos = []               # checkouts to watch besides the ones sessions use

[history]
log = ""                 # default ~/.local/share/matchblox/history.csv; "-" disables
source = ""              # another CSV with a ts column to chart alongside

[hooks]
alert = []               # argv run on each new alert, title and evidence appended,
                         # e.g. ["notify-send", "matchblox"]