cowdiag(1)

📦 version 0.3, in fedora 44

💖 cowdiag — the manual, but make it a group chat 💖

okay bestie, sit DOWN, because cowdiag is about to become your new hyperfixation. this is the cowdiag(1) page from the cow - Window Manager manual, and i'm giving it to you with full personality intact. no details lost, no cap. 🐄✨

✨ NAME ✨

cowdiag — the live diagnostics dashboard for cow and River. that's it, that's the whole vibe. a little window into everything your compositor is doing, in real time. 💅

🌸 SYNOPSIS 🌸


cowdiag -j [-w] [-i milliseconds]

🦋 DESCRIPTION 🦋

so cowdiag is a read-only terminal dashboard for cow(1). read-only meaning it's just looking, respectfully, like a girl who's not gonna touch your stuff, she's just observing. 👀

it combines three whole things:

  • CoW's status snapshot 🫶
  • internal manage/render timing counters
  • process statistics for CoW and River

okay and here's the part where i need you to listen, because it's giving nuance: the timing panels separate work actually done inside CoW callbacks from time spent just waiting around at the CoW/River protocol boundary. those are two different things and conflating them is a crime.

🚨 but like, important: these panels do not measure River's GPU rendering or frame presentation time. do not come for them for something they never claimed. periodt.

the interactive display is also a flexible queen — it adapts to your terminal width:

  • wide terminals get the full set: process, session, manage, render, and rolling-history panels 🌈
  • narrow terminals get a compact layout, still cute, still functional 🎀

💅 OPTIONS 💅

  • -h — print usage and exit. bye bestie 👋
  • -i milliseconds — set the sampling interval. default is 1000 milliseconds. values from 100 through 60000 are accepted. like, don't go below 100, she's not gonna do it.
  • -j — emit one combined JSON sample instead of opening the terminal dashboard. the command waits for one sampling interval so CPU percentages are based on two observations (you need two points to draw a line, babes 📈).
  • -v — print the version and exit. short and iconic.
  • -w — with -j, keep emitting newline-delimited JSON samples until interrupted. it's giving firehose 🔥

🎀 KEYS 🎀

  • q, Escape — quit. closing the app is self-care. 💖
  • Space — pause or resume sampling. freeze frame, main character energy. ✋
  • r — clear the local graph history. 🧹 important: CoW's process-lifetime counters are not changed. you're just clearing your local view, not rewriting history, bestie.
  • Tab, Left, Right, 1 through 4 — select the line graph. your options are: combined CoW and River CPU, CoW RSS, manage wait, or render wait. pick your fighter 🥊
  • g — toggle an expanded graph-only view. this also makes the graph available in narrow terminals, where the normal stacked layout has no graph panel. so if you were sad about your tiny terminal, g heard you. 🫶
  • ? — show or hide key help. the little pop-up that reminds you what you forgot. 🙈

⭐ METRICS ⭐

🌟 the manage panel reports:

  • requests registered by CoW and requests coalesced into the same cycle;
  • delay from the first pending request to River's manage_start event; and
  • time spent by CoW handling a manage cycle.

🌟 the render panel reports:

  • delay from CoW's manage_finish request to River's next render_start; and
  • time spent by CoW handling a render cycle.

🌟 and the portability tea:

CoW CPU time, process lifetime, and peak resident memory are portable. slay.

cowdiag also shows current CoW and River RSS and River CPU usage on Linux, FreeBSD, OpenBSD, and NetBSD.

  • Linux uses procfs 🌸
  • the BSD implementations use their native process sysctl interfaces 🌸
  • River is identified from the peer credentials of the Wayland socket 🦋
  • unsupported process fields are displayed as n/a on other systems. not a bug, just honesty. 💀

and CPU percentages use a per-core scale: one fully occupied CPU is 100 percent. so yes, you can go over 100 if you have multiple cores going off. she contains multitudes. 👑

🌈 ENVIRONMENT 🌈

  • XDG_RUNTIME_DIR — used to locate CoW's command and status sockets. 📍
  • WAYLAND_DISPLAY — selects the CoW instance and identifies the River process. 🔍
  • COW_IPC_SOCKET, COW_STATUS_SOCKET — override the normal command and status socket paths. custom paths, custom life. ✨

🫶 SEE ALSO 🫶

cow(1), cowbar(1), moocow(1) — the whole friend group, go say hi. 💜

💌 and that's the page!! this was version 0.3, dated 2026-09-07, from the cow - Window Manager manual. tysm for reading, bestie, go run cowdiag and watch your compositor absolutely perform. 🐄💖✨
📦 where this page comes from