A customizable cross-platform graphical process/system monitor for the terminal.
Supports Linux, macOS, and Windows. Inspired by gtop, gotop, and htop.
Demo using the Gruvbox theme (--theme gruvbox), along with IBM Plex Mono and Kitty
This is a fork.
monis bottom with four additions, described below. Everything past that section is upstream's documentation and still applies -- the binary is just namedmoninstead ofbtm. SeeNOTICE.
Nothing here changes the default layout or default behaviour. Every addition is opt-in.
A power graph widget plotting power draw in Watts, sampled from Apple Silicon's own
counters via macmon. No sudo.
Up to five channels: whole-system, CPU package, GPU, ANE, and DRAM. Not every chip wires up
every rail -- on an M4, cpu, ane, and ram report a constant 0.0 -- so
hide_unreported defaults on and drops the ones this machine never reports, rather than
drawing flat lines that read as "idle".
Cluster labels come from SocInfo rather than being hardcoded: they are E/P on M1-M4
but P/S on M5+.
Three widgets reading live Claude Code activity off
~/.claude:
claude-- a sortable table of live sessions: name, directory, model family, state, tokens, cost, context-window occupancy, subagent countclaude_graph-- token throughput by model family over time, on a log axis by defaultclaude_stats-- the equivalent of Claude Code's own/statusstats screen, as stacked rounded-staircase bands of token spend by model family. That screen bars by day; this buckets by minute over the last hour, so the shape of a working session is visible rather than collapsed into a single bar. Built by walking~/.claude/projectsand attributing each record to a bucket from its own timestamp, so the window is complete the moment the widget appears rather than having to be accumulated live -- and it keeps the tokens of sessions that have since exited, which the live-session view cannot
Backed by the claude-metrics workspace crate, which has no dependency on bottom. Counting
is the fiddly part and the rules are documented in that crate: dedupe on
requestId + message.id, take cache_creation_input_tokens without the ephemeral buckets
it already sums, ignore usage.iterations[], and treat output_tokens as a running total
across a message's per-content-block records.
Cost, context, and rate limits need a small tee in your statusline -- see
the docs.
Without it those columns read N/A and everything else still works.
sample_configs/claude_config.toml is a ready-made layout with all three and nothing else:
$ mon -C sample_configs/claude_config.toml --pixel_graphs kitty--marker <braille|octant|sextant|quadrant|half_block|dot|block|bar>.
All eight were already implemented by the vendored chart renderer and simply unreachable,
because the marker was picked from a hardcoded braille/dot pair. This resolves upstream's
own TODO in options/args.rs. --dot_marker still works and still means --marker dot.
--pixel_graphs kitty draws graphs as real pixels rather than cell markers, worth roughly
an order of magnitude more vertical resolution on a short graph.
The image covers the data region only, and goes down first -- the border, both sets of
axis labels, and the legend are ordinary text drawn on top of it afterwards, which is how
they reclaim their own cells. The region is the chart's own graph_area, asked for rather
than re-derived: the Kitty renderer packs an entire row's escape sequence into that row's
first cell, so overlapping the y-axis by one column does not cost a column, it erases the
whole image. If encoding fails the chart falls back to drawing its usual cell-marker line.
Lines are anti-aliased, and the anti-aliasing is unblended back into the alpha channel before the image is handed over. bottom never paints a background of its own, so the rasteriser has to guess one, and softening edges against a guessed background is what puts a dark fringe along every line on a light terminal. Carrying the softening as alpha instead lets the terminal composite against its own real background, which also keeps the widget theme-neutral rather than stamping a guessed rectangle on screen.
The encoded image is cached alongside the pixels and rebuilt only when the data changes. Encoding per frame re-transmits the whole buffer as base64, which tmux's passthrough cannot keep up with -- the graph flickers in and out.
Use kitty rather than auto under tmux. Measured on Ghostty 1.3.1 + tmux 3.7c: the Kitty
capability query gets no reply through tmux's passthrough, even though the image transport
itself works fine. Only detection is broken, so auto can never select it there.
As (yet another) process/system visualization and management application, bottom supports the typical features:
Graphical visualization widgets for:
- CPU usage over time, at an average and per-core level
- RAM and swap usage over time
- Network I/O usage over time
- Temperature over time
- Disk I/O usage over time
with support for zooming in/out the current time interval displayed.
Widgets for displaying info about:
A process widget for displaying, sorting, and searching info about processes, as well as support for:
Cross-platform support for Linux, macOS, and Windows, with more planned in the future.
Customizable behaviour that can be controlled with command-line options or a config file, such as:
- Custom and built-in colour themes
- Customizing widget behaviour
- Changing the layout of widgets
- Filtering out entries in some widgets
And more:
You can find more details in the documentation.
bottom officially supports the following operating systems and corresponding architectures:
- macOS (
x86_64,aarch64) - Linux (
x86_64,i686,aarch64) - Windows (
x86_64,i686)
These platforms are tested to work for the most part and issues on these platforms will be fixed if possible. Furthermore, binaries are built and tested using the most recent version of stable Rust at the time.
For more details on supported platforms and known problems, check out the documentation.
bottom may work on a number of platforms that aren't officially supported. Note that unsupported platforms:
- Might not be tested in CI to build or pass tests (see here for checked platforms).
- Might not be properly tested by maintainers prior to a stable release.
- May only receive limited support, such as missing features or bugs that may not be fixed.
Note that some unsupported platforms may eventually be officially supported (e.g., FreeBSD).
A non-comprehensive list of some currently unofficially-supported platforms that may compile/work include:
- FreeBSD (
x86_64) - Linux (
armv6,armv7,powerpc64le,riscv64gc,loongarch64) - Android (
arm64) - Windows (
arm64) - NetBSD (
x86_64)
For more details on unsupported platforms and known problems, check out the documentation.
Installation via cargo can be done by installing the bottom crate:
# You might need to update the stable version of Rust first.# Other versions might work, but this is not guaranteed.
rustup update stable
# Install the binary from crates.io.
cargo install bottom --locked
# If you use another channel by default, you can specify# the what channel to use like so:
cargo +stable install bottom --locked
# --locked may be omitted if you wish to not use the# locked crate versions in Cargo.lock. However, be# aware that this may cause problems with dependencies.
cargo install bottomAlternatively, you can use cargo install using the repo as the source.
# You might need to update the stable version of Rust first.# Other versions might work, but this is not guaranteed.
rustup update stable
# Option 1 - Download an archive from releases and install
curl -LO https://github.com/ClementTsang/bottom/archive/0.14.8.tar.gz
tar -xzvf 0.14.8.tar.gz
cargo install --path . --locked
# Option 2 - Manually clone the repo and install
git clone https://github.com/ClementTsang/bottom
cd bottom
cargo install --path . --locked
# Option 3 - Install using cargo with the repo as the source
cargo install --git https://github.com/ClementTsang/bottom --locked
# You can also pass in the target-cpu=native flag to try to# use better CPU-specific optimizations. For example:
RUSTFLAGS="-C target-cpu=native" cargo install --path . --lockedbottom is available as a package for Alpine Linux via apk:
apk add bottomPackages for documentation (bottom-doc) and completions for Bash (bottom-bash-completion), Fish (bottom-fish-completion), and Zsh (bottom-zsh-completion) are also available.
bottom is available as an official package that can be installed with pacman:
sudo pacman -S bottomIf you want the latest changes that are not yet stable, you can also install bottom-gitfrom the AUR:
# Using paru
paru -S bottom-git
# Using yay
yay -S bottom-gitA .deb file is provided on each stable release and
nightly builds for x86, aarch64, and armv7.
Some examples of installing it this way:
# x86-64
curl -LO https://github.com/ClementTsang/bottom/releases/download/0.14.8/bottom_0.14.8-1_amd64.deb
sudo dpkg -i bottom_0.14.8-1_amd64.deb
# ARM64
curl -LO https://github.com/ClementTsang/bottom/releases/download/0.14.8/bottom_0.14.8-1_arm64.deb
sudo dpkg -i bottom_0.14.8-1_arm64.deb
# ARM
curl -LO https://github.com/ClementTsang/bottom/releases/download/0.14.8/bottom_0.14.8-1_armhf.deb
sudo dpkg -i bottom_0.14.8-1_armhf.deb
# musl-based
curl -LO https://github.com/ClementTsang/bottom/releases/download/0.14.8/bottom-musl_0.14.8-1_amd64.deb
sudo dpkg -i bottom-musl_0.14.8-1_amd64.debbottom is available as a rust package that can be installed with cave:
cave resolve -x repository/rust
cave resolve -x bottomWarning
atim/bottom seems to be unmaintained and may be outdated (relevant issue)
bottom is available on COPR:
sudo dnf copr enable atim/bottom -y
sudo dnf install bottombottom is also available via Terra:
sudo dnf install --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' --setopt='terra.gpgkey=https://repos.fyralabs.com/terra$releasever/key.asc' terra-release
sudo dnf install bottom.rpm files are also generated for x86 in the releases page.
For example:
curl -LO https://github.com/ClementTsang/bottom/releases/download/0.14.8/bottom-0.14.8-1.x86_64.rpm
sudo dnf install ./bottom-0.14.8-1.x86_64.rpmAvailable in the official Gentoo repo:
sudo emerge --ask sys-process/bottomAvailable in Nixpkgs as bottom:
nix profile install nixpkgs#bottombottom can also be installed and configured through the home-manager module:
{programs.bottom.enable=true;}Available in openSUSE Tumbleweed:
zypper in bottombottom is available as a snap:
sudo snap install bottom
# To allow the program to run as intended
sudo snap connect bottom:mount-observe
sudo snap connect bottom:hardware-observe
sudo snap connect bottom:system-observe
sudo snap connect bottom:process-controlAvailable in the Solus repos:
sudo eopkg it bottomAvailable in the void-packages repo:
sudo xbps-install bottombottom can also be installed on Linux or macOS using gah:
gah install bottomThe formula is available here:
brew install bottomAvailable here:
sudo port selfupdate
sudo port install bottomChocolatey packages are located here:
choco install bottomAvailable in the Main bucket:
scoop install bottomThe winget package can be found here:
winget install bottom
# If you need a more specific app id:
winget install Clement.bottomYou can uninstall via Control Panel, Options, or winget --uninstall bottom.
You can manually install bottom as a Windows program by downloading and using the .msi file from the latest release.
You can install bottom using conda with this conda-smithy repository:
# Add the channel
conda config --add channels conda-forge
conda config --set channel_priority strict
# Install
conda install bottombottom is available in mise. You can install it like so:
mise use -g bottom@latest
You can also use the pre-built release binaries:
To use, download and extract the binary that matches your system. You can then run by doing:
./monor by installing to your system following the procedures for installing binaries to your system.
The release binaries in the releases page are packaged with shell auto-completion files for Bash, Zsh, fish, Powershell, Elvish, Fig, and Nushell. To install them:
- For Bash, move
mon.bashto$XDG_CONFIG_HOME/bash_completion or /etc/bash_completion.d/. - For Zsh, move
_monto one of your$fpathdirectories. - For fish, move
mon.fishto$HOME/.config/fish/completions/. - For PowerShell, add
_mon.ps1to your PowerShell profile. - For Elvish, the completion file is
mon.elv. - For Fig, the completion file is
mon.ts. - For Nushell, use
mon.nu.
The individual auto-completion files are also included in the stable/nightly releases as completion.tar.gz if needed.
You can run it using mon.
- For help on flags, use
mon -hfor a quick overview ormon --helpfor more details. - For info on key and mouse bindings, press
?inside bottom or refer to the documentation page.
You can find more information on usage in the documentation.
bottom accepts a number of command-line arguments to change the behaviour of the application as desired. Additionally, bottom will automatically generate a configuration file on the first launch, which can be changed.
More details on configuration can be found in the documentation.
If some things aren't working, give the troubleshooting page a look. If things still aren't working, then consider asking a question or filing a bug report if you think it's a bug.
The main documentation page can be found at https://bottom.pages.dev, using Cloudflare Pages. If needed, a mirror hosted using Github Pages is also available at https://clementtsang.github.io/bottom.
Whether it's reporting bugs, suggesting features, maintaining packages, or submitting a PR, contribution is always welcome! Please read CONTRIBUTING.md for details on how to contribute to bottom.
Thanks to all contributors:
This project is very much inspired by gotop, gtop, and htop.
This application was written with many, many libraries, as well as many services and programs, all built on top of the work of many talented people. bottom would not exist without all of this.
And of course, thank you again to all contributors and package maintainers!
I also really appreciate anyone who has used bottom, and those who go out of their way to report bugs or suggest ways to improve things. I hope it's been a useful tool for others.
To those who support my work financially via donations, thank you so much.
Thanks to JetBrains for providing access to tools that I use to develop bottom as part of their open source support program.
Also thanks to SignPath.io for providing a free code signing service, and to the SignPath Foundation for the certificate.
