API reference
System and programs
CPU, memory, GPU, network and Wi-Fi with api.system(), and the busiest programs with api.topPrograms().
Two calls read how hard the machine is working: api.system() for CPU, memory, GPU, network and Wi-Fi, and api.topPrograms() for the programs behind the CPU load. Both read the machine when called; nothing monitors it in between. Both need "permissions": ["system"] in the manifest.
api.system()
system(): Promise<SystemInfo>api.every(1000, async () => {
const { cpu } = await api.system();
el.textContent = `${Math.round(cpu.load)} %`;
});CPU load and network speeds are differences between two reads, so they cover the time since the previous call, from any widget. Calls less than 500 ms apart share one read, so several widgets polling every second cost one read per second. Keep a history yourself if you want to chart a value.
| Field | Meaning |
|---|---|
hostname |
The machine's name. |
wifi |
The connected Wi-Fi network, or null: the name of its Windows profile, or of its NetworkManager connection on Linux. Both are the SSID unless renamed. |
cpu.load |
Load of all cores, in percent. |
memory.used, memory.total |
RAM in bytes: in use (the total minus the available memory, as in Task Manager), and usable in total. |
gpu.load, gpu.temperature |
The first NVIDIA GPU: percent and °C. gpu is null without one or without its driver. |
net.down, net.up |
Internet traffic since the previous call, in bytes per second. |
net.avg1m, .avg5m, .avg15m |
{ down, up } averaged over the calls of the last 1, 5 or 15 minutes. |
The averages only know the calls widgets made: they cover the full window while a widget keeps polling, and less right after polling starts or resumes, for example when a page comes back on screen.
On Linux, wifi is also null without NetworkManager, and net counts only the interfaces of a device: not the loopback, nor the virtual ones of Docker or virtual machines, whose traffic also goes through a real interface or never leaves the machine.
CPU temperature is not available, on either system: Windows doesn't expose it to normal apps.
A network meter
const format = (bytes) =>
bytes > 1e6 ? `${(bytes / 1e6).toFixed(1)} MB/s` : `${Math.round(bytes / 1e3)} kB/s`;
api.every(1000, async () => {
const { net } = await api.system();
el.textContent = `↓ ${format(net.down)} ↑ ${format(net.up)} (1 min ↓ ${format(net.avg1m.down)})`;
});api.topPrograms()
topPrograms(count: number): Promise<ProgramUsage[]>The programs that used the most CPU since the previous call (from any widget), busiest first: at most count, fewer when not that many used any.
api.every(1000, async () => {
const [top] = await api.topPrograms(1);
el.textContent = top ? `${top.name} · ${Math.round(top.cpu)} %` : 'Idle';
});| Field | Meaning |
|---|---|
name |
What Task Manager calls it: the executable's description (THE FINALS, Google Chrome), else its file name without .exe (crashpad_handler). On Linux, the name of its app in the app menu, else the executable's file name. All the processes with that name count as one program. |
cpu |
Percent of all logical processors, like Task Manager. |
Services and system processes are included, as in Task Manager. On Linux, the processes of every user are included too.
Like api.system(), it reads when called, and calls less than 500 ms apart share one read. It lists every process on the machine, which costs more than api.system(), so it is a separate call: only make it while you show the result.