| Build |   |
|---|---|
| Python |      |
| Platforms |   |
| Project |   |
Track the CPU and RAM usage of a process — and every process it spawns, including children that daemonize and detach themselves. Or follow the busiest processes of the whole machine, as a service from boot to shutdown.
treehawk is a free, open-source resource usage monitor for Linux and macOS:
- Track CPU usage and track RAM usage of any command, script or running process, including its child processes.
- Log resource usage over time and get peak and average memory and CPU.
- Find memory leaks and CPU spikes across the whole machine.
- Get a PDF report with charts of CPU and memory usage.
- Tracking GPU usage is planned.
Documentation: https://ibadrather.github.io/treehawk/
curl -LsSf https://github.com/ibadrather/treehawk/releases/latest/download/install.sh | shLinux and macOS, including Apple Silicon, with Python 3.10+. The script needs no uv or pipx. For its options, upgrading, uninstalling and other ways to install, see Install.
treehawk run -- python train.py --epochs 10 # start a command and follow it; exact
treehawk watch train.py # attach to one already running
treehawk report treehawk-*.jsonl # summary in the terminal
treehawk pdf treehawk-*.jsonl # an 8-page PDF report
treehawk top # the top processes of the whole machine
sudo "$(command -v treehawk)" service install # ... as a systemd service (Linux)
treehawk report /var/lib/treehawk --since 2hBoth modes sample until stopped or until the workload ends. While they run you
get a live dashboard, and afterwards a log you can summarise, chart, or query
with jq.
| Track a workload | watch and run, and their options |
| Track the whole machine | top, the service, spikes and leak suspects |
| Read the results | report, pdf, and the log formats |
| How it works | membership rules, memory measures, limitations |
| Platforms | what Linux and macOS can and cannot report |
Metrics come from the kernel directly (/proc and cgroup v2 on Linux,
libproc and sysctl on macOS), not from ps, top or a third-party library.
uv sync
uv run ruff format && uv run ruff check && make typecheck && uv run pytestRead AGENTS.md before changing anything, and
Development for the
architecture, tests and releases.