caffeinate, htop and Friends

A machine that runs agents all day needs a few small tools around it. caffeinate keeps a Mac from sleeping in the middle of a long run, htop shows what is using the processor and memory right now, ncdu finds what is filling the disk, and a handful of helpers in Cole’s Dotfiles answer “what is this machine doing?” in one command. None of them is exotic, and all of them earn their place.

caffeinate: keep the Mac awake

caffeinate ships with macOS. It holds “assertions”, requests to the power manager not to sleep, for as long as it runs. The flags say which kind of sleep to block:

Flag	Prevents
-d	The display from sleeping
-i	The system from idle sleeping
-m	The disk from idle sleeping
-s	The system from sleeping at all, only while on AC power
-u	Declares the user active, which turns the display on
-t 3600	Drops the assertions after this many seconds
-w 1234	Holds them until process 1234 exits

It can also wrap a command and hold the assertion exactly as long as the command runs: caffeinate -i make keeps the Mac awake for the build and no longer.

Cole’s macOS role file adds three shortcuts on top:

caf() {
    local hours="${1:-12}"
    local secs=$(( hours * 3600 ))
    nohup caffeinate -dimsu -t "$secs" >/dev/null 2>&1 &
    disown

caf takes a number of hours (12 if you give none), blocks every kind of sleep for that long, and prints when it will end. nohup and disown detach it from the shell, so closing the terminal or the SSH session that started it does not end it. caf12 is twelve hours, and caf-stop ends any running caffeinate.

This matters on the Mac mini, which runs agents in tmux and gets reached from elsewhere, over SSH or with Screens 5. A sleeping Mac pauses every agent on it and stops answering the phone.

To see what is currently holding a Mac awake (or failing to), pmset -g assertions lists every active assertion and the process that took it.

htop: what is running

htop is an interactive process viewer for the terminal, a friendlier top. It runs on Linux, macOS and the BSDs, and Cole’s Brewfile and Linux installer both install it. The keys worth learning:

Key	Does
F5 or t	Tree view: every process under its parent
M / P / T	Sort by memory, by CPU, by running time
F4 or \	Filter the list by name
F3 or /	Search for a process
u	Show one user’s processes
Space / c	Tag a process, or a process and its children
F9 or k	Send a signal (kill) to the selected or tagged processes
F10 or q	Quit

Tree view is the one for agents. A coding agent is rarely one process: each Claude Code session brings its MCP servers, language servers and sometimes a headless browser. In tree view they hang under their session, so you can see which session a memory-hungry browser belongs to, and tag the whole branch with c before killing it.

One caution on a Mac: the memory column htop and ps show is resident memory (RSS), which leaves out pages macOS has compressed or swapped out. Under memory pressure that undercounts what a long-running session really holds, so treat it as a lower bound.

ncdu: what is filling the disk

ncdu scans a directory and shows the biggest folders first, with arrow keys to drill in and d to delete. ncdu ~ is the fastest way to find the forgotten node_modules, build caches and old transcripts that fill a disk. Agents generate a lot of files (worktrees, dependencies, logs, screenshots), so a full disk shows up sooner than you would expect. Cole’s shell also has duh, a one-level, size-sorted du of the current directory, which uses GNU du’s options.

One-command health checks

Two helpers in base/aliases.sh print a machine’s state without opening anything interactive, which also makes them easy for an agent to run:

• resources prints the processor, its load and the top processes by CPU; memory in use, compressed and free with the top processes by memory; and disk use with the biggest folders in your home directory. It reads /proc on Linux and vm_stat and sysctl on a Mac, so the same command works on both.
• resources-deep adds pressure detection: swap use, how fast the macOS memory compressor is growing over two seconds, how low free memory has fallen, and five one-second samples of one process you name (by default the macOS contacts daemon, or the Linux swap daemon), for when you suspect thrashing or a system process stuck spinning.

Both note a common trap: the %CPU that ps reports is an average over the process’s whole life, not what it is doing this second. For a live view, use htop or top.

For agents specifically, two more tools do the cleanup. claude-orphans and cko find and stop Claude Code sessions whose terminal went away (see cleaning up orphans), and cc-park parks idle sessions to free their memory without losing them.

A dashboard at login

All of this can be summarized before your prompt even appears. Cole wrote porchlight, a login dashboard for the terminal, released as open source: vitals, services, AI agents and their plan limits, Docker, pull requests, cloud status and ranked alerts, “rendered from cache in milliseconds”. A background collector refreshes each source on its own schedule, so a login never waits on the network, even over SSH from a phone, and one machine can act as a hub that gathers the others’ status over SSH. Its predecessor, fleet-motd, is archived, and development continues in porchlight.

The rest of the everyday kit

Tool	What it is for
jq	Reading and reshaping JSON on the command line; many of Cole’s scripts depend on it
bat	cat with syntax highlighting and line numbers
eza	A modern ls; Cole’s ls, ll and lt use it when it is installed
zoxide	z part-of-a-name jumps to a directory you visit often
fd	Finding files by name, the companion to ripgrep
tree	A directory as a tree
mtr	traceroute and ping combined, for “where is the network slow?”

They all come from the same two places: the Brewfile on a Mac, and the installer’s package list on Linux. The POSIX, macOS and Linux page explains why the same commands behave a little differently on each.