GO — Healthy across all four use cases

• Last commit 1d ago
• 9 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 89% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

bottom (btm) is a cross-platform terminal-based graphical system monitor written in Rust that visualizes CPU, memory, disk, network, and process activity in real-time. It runs on Linux, macOS, and Windows, providing an interactive TUI alternative to htop/top with mouse support, process filtering, and customizable themes. Monolithic Rust binary with src/bin/main.rs (btm) as the entry point and src/bin/schema.rs for config schema generation. Core library logic in src/ (inferred), organized around widgets for CPU/memory/disk/network/process visualization. Configuration is TOML-based (docs/content/assets/screenshots/config visible). Platform-specific code gated with cfg-if for Linux/macOS/Windows.

System administrators and developers who need fast, lightweight system monitoring on Linux/macOS/Windows servers or workstations, and who prefer keyboard/mouse-driven TUI apps over heavy GUI tools or basic command-line utilities like htop.

Production-ready and actively maintained. The project is at v0.12.3 with extensive CI/CD coverage (workflows for bsd_vm_check, coverage, deployment, nightly builds), comprehensive test suites, and a well-documented codebase. Regular updates visible in CHANGELOG.md and active GitHub workflows indicate ongoing development and community adoption.

Low risk for end-users but moderate for heavy contributors: single maintainer (Clement Tsang) visible in Cargo.toml author field, though multiple CI workflows suggest some process maturity. Dependency count is reasonable (anyhow, crossterm, clap, serde) but GPU/battery features add optional complexity. No major red flags; breaking changes appear managed via semver.

Active maintenance at v0.12.3 with Rust 1.85 as MSRV. Recent workflows for BSD compatibility testing, documentation generation, and multi-platform release builds (build_releases.yml) suggest focus on cross-platform stability. Schema validation (validate_schema.yml) indicates configuration handling refinements.

git clone https://github.com/ClementTsang/bottom.git
cd bottom
cargo build --release
cargo run --bin btm -- --help

Daily commands:

cargo run --bin btm
# Or with features:
cargo run --bin btm --features battery,gpu
# For release binary:
cargo build --release
./target/release/btm

• Cargo.toml — Root manifest defining the project structure, dependencies (crossterm, tui-rs, serde), and build configuration for the cross-platform monitor.
• build.rs — Build script that compiles platform-specific code and generates version information—essential for understanding how the project handles Linux/macOS/Windows conditionals.
• src/main.rs — Application entry point orchestrating startup, event loop, and graceful shutdown; critical for understanding the overall control flow.
• src/app/mod.rs — Core application state and data model holding UI state, process data, and system metrics; the central hub for all collectors and state mutations.
• docs/content/configuration/config-file/index.md — Configuration file schema documentation; developers must understand the TOML structure to add new config options.
• .github/workflows/ci.yml — CI pipeline defining test matrix, linting, and release builds across Linux, macOS, and Windows; essential for understanding how PRs are validated.
• Cross.toml — Cross-compilation configuration for targeting different architectures and OSes; critical for contributing platform-specific code.

Add a new system metric widget (e.g., new disk stats column)

1. Add the new metric field to the App struct in src/app/mod.rs (src/app/mod.rs)
2. Implement collection logic in the appropriate data_collection module (e.g., src/data_collection/disks.rs) (src/data_collection/disks.rs)
3. Add a new widget or extend an existing one in src/ui/widgets/ to render the metric (src/ui/widgets/disk.rs)
4. Update the layout engine in src/ui/layout.rs to position the new widget (src/ui/layout.rs)
5. Add config options in src/config/mod.rs to allow users to toggle or customize the metric (src/config/mod.rs)
6. Document the new config option in docs/content/configuration/config-file/disk-table.md (docs/content/configuration/config-file/disk-table.md)

Add a new keyboard shortcut or command

1. Define the new command enum variant in src/event/mod.rs or relevant event handler (src/event/mod.rs)
2. Map the keyboard input to the command in src/event/input.rs (src/event/input.rs)
3. Implement the command handler logic in src/app/mod.rs (e.g., state mutation or action execution) (src/app/mod.rs)
4. Add the keybinding to the config schema in src/config/mod.rs if user-customizable (src/config/mod.rs)
5. Document the new shortcut in docs/content/configuration/command-line-options.md (docs/content/configuration/command-line-options.md)

Support a new platform or OS variant

1. Add the target triple to Cross.toml and .github/workflows/ci.yml (Cross.toml)
2. Update build.rs to detect and compile platform-specific code for the new target (build.rs)
3. Implement platform detection in src/utils/mod.rs if needed (src/utils/mod.rs)
4. Add platform-specific data collection overrides in src/data_collection/ modules (leveraging sysinfo crate's platform support) (src/data_collection/mod.rs)
5. Test the new target by running CI workflow .github/workflows/ci.yml against it (.github/workflows/ci.yml)

Add a new color theme or styling option

1. Define the theme colors in src/styling.rs (src/styling.rs)
2. Add theme config parsing in src/config/mod.rs to allow TOML-based customization (src/config/mod.rs)
3. Apply the theme colors when rendering widgets in src/ui/ modules (src/ui/mod.rs)
4. Document the new theme in docs/content/configuration/config-file/styling.md (docs/content/configuration/config-file/styling.md)

• Rust — Memory safety, zero-cost abstractions, and excellent cross-platform support enable a fast, reliable system monitor without runtime garbage collection.
• sysinfo crate — Abstracts platform-specific system API calls (Linux /proc, macOS libSystem, Windows WMI) into a unified interface for CPU, memory, disk, network, and process stats.
• crossterm — Provides cross-platform terminal manipulation (Windows native, Unix raw mode) and event polling without external TUI framework lock-in.
• ratatui (formerly tui-rs) — Immediate-mode TUI rendering library for building complex terminal UIs with declarative layout and minimal boilerplate.
• serde + TOML — Enables strongly-typed, human-readable config files with zero-runtime parsing overhead via serde's derive macros.
• GitHub Actions + Cross — Automates multi-platform testing (Linux glibc/musl, macOS, Windows, BSD) and binary releases without maintaining native CI infrastructure.

• Single-threaded event loop with background data-collection thread (via crossbeam channels)
  • Why: Avoids TUI library constraints (most require single-threaded rendering
  • Consequence: undefined

Feature flags matter: deploy is the default and includes battery + gpu + zfs; building with minimal features omits these. Platform detection uses cfg_if, so cross-platform bugs hide until tested on each OS. GPU support requires NVIDIA nvml-wrapper (external dependency not shipped); battery support requires starship-battery crate. Config schema validation (validate_schema.yml) suggests strict TOML parsing—malformed configs will error loudly. Rust 1.85+ MSRV is enforced; older toolchains will fail silently on Edition 2024 syntax.

• Terminal User Interface (TUI) event loop — bottom's core is a crossterm-based event loop polling for keyboard/mouse input and rendering widget frames; understanding the event→render cycle is essential for adding interactivity or new widgets
• Feature flags and conditional compilation — bottom uses Cargo features (battery, gpu, zfs, deploy) and cfg_if macros to gate platform-specific and optional-dependency code; critical for understanding why builds differ and how to extend with new optional functionality
• Cross-platform system metrics collection (/proc, sysctl, WMI) — bottom must read CPU/memory/disk from Linux /proc filesystem, macOS sysctl, and Windows WMI; each platform has different APIs, so code is heavily cfg-gated and platform-specific behavior is non-obvious
• TOML configuration parsing and schema generation — bottom's config system uses serde for TOML deserialization and schema generation (schemars) for validation; understanding how config flows from TOML→struct→serde is needed to modify settings
• Semver and MSRV (Minimum Supported Rust Version) — bottom pins Rust 1.85 as MSRV and uses Edition 2024; this affects what language features are available and requires understanding version constraints for CI/releases
• Multi-platform CI/CD with GitHub Actions and Cross — bottom's release process (build_releases.yml, Cross.toml, bsd_vm_check.yml) shows how to test and build on Linux/macOS/Windows/BSD from a single workflow; essential for contributing or maintaining the release pipeline

• xxxserxxx/gotop — Direct inspiration listed in README; Go-based process monitor with similar TUI widget layout—shows design pattern bottom follows
• aksakalli/gtop — Another listed inspiration; Node.js system monitor that pioneered graphical process visualization in terminal UIs
• htop-dev/htop — Classic C-based process monitor; bottom modernizes htop's UX with mouse support and Rust's safety guarantees
• ratatui-org/ratatui — Rust TUI framework that bottom likely uses (not explicit in Cargo.toml snippet but standard for Rust terminal apps); ecosystem companion for TUI development
• starship/starship — Starship battery crate (starship-battery) is a dependency; popular Rust CLI project sharing infrastructure patterns (clap, feature flags, CI/CD)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for configuration file parsing and validation

The repo has a comprehensive configuration system (evidenced by docs/content/assets/screenshots/config/ and validate_schema.yml workflow), but there's no dedicated integration test suite visible in the file structure. New contributors could add tests that validate config parsing for different scenarios (valid configs, malformed TOML, missing fields, deprecated options) to prevent regressions and catch edge cases early.

• [ ] Create tests/config_integration_tests.rs to test configuration loading from various TOML files
• [ ] Test disk filtering configurations referenced in docs/content/assets/screenshots/config/disk-filtering/
• [ ] Test layout configurations to ensure custom layouts parse correctly
• [ ] Add test fixtures in tests/fixtures/config/ with valid and invalid config examples
• [ ] Ensure tests cover the schema validation workflow (validate_schema.yml)

Add platform-specific unit tests for battery and GPU monitoring features

The repo has optional features for battery and GPU monitoring (battery, nvidia, gpu in Cargo.toml), but comprehensive unit test coverage for these platform-specific features appears minimal. New contributors could add tests that mock system calls and validate correct behavior across Linux, macOS, and Windows without requiring actual hardware.

• [ ] Create tests/battery_tests.rs with mocked starship-battery calls for different charge states
• [ ] Create tests/gpu_tests.rs with mocked nvml-wrapper calls for GPU memory/utilization readings
• [ ] Add platform-conditional tests using #[cfg(target_os = "...")] for OS-specific edge cases
• [ ] Test fallback behavior when battery/GPU features are disabled or hardware unavailable
• [ ] Validate integration with the CI workflows (ci.yml handles multiple platforms)

Create missing documentation for custom color themes and layout configuration

The screenshots show extensive configuration options (process sorting, layout customization, disk filtering), but docs/content appears incomplete based on the file structure. New contributors could document the color theme system, provide theme examples, and create a comprehensive layout configuration guide with examples to reduce support burden and improve user experience.

• [ ] Create docs/content/configuration/colors.md documenting available color options and hex format requirements
• [ ] Create docs/content/configuration/layouts.md with step-by-step examples (reference the sample_layout.webp screenshot)
• [ ] Add example theme files in docs/content/examples/themes/ for popular color schemes (Nord, Dracula, Solarized)
• [ ] Document process filtering/sorting options visible in docs/content/assets/screenshots/process/
• [ ] Link new documentation pages to the main docs/README.md navigation

• Add missing integration tests for platform-specific code paths (Linux /proc parsing, macOS syscall handling, Windows WMI queries). Currently only unit tests visible; add tests/ directory with platform-specific test cases under cfg guards.: Multi-platform system monitor risks platform-specific regressions; CI would catch them with broad test coverage.
• Expand schema documentation: add JSON Schema comments to the generate_schema binary (src/bin/schema.rs) explaining each config field with examples. docs/content/assets/screenshots/config/ shows UI but not programmatic schema docs.: Config-heavy tools need both human docs (which exist) and machine-readable schema with descriptions for editor integration.
• Add battery/GPU feature documentation: docs/ mentions these features exist but sample_configs/ (excluded from package) likely has examples. Extract sample configs for deploy features into docs/ with explanations of battery thresholds and GPU display settings.: Features like --features battery,gpu are discoverable but not documented with working examples; new users hit configuration friction.

The 'bottom' project demonstrates generally good security practices as a legitimate open-source system monitoring tool. No critical vulnerabilities were identified from the available file structure and metadata. The main concerns are: (1) incomplete dependency list in the provided Cargo.toml prevents full vulnerability assessment, (2) use of edition 2024 which may not be standard, (3) optional GPU/NVIDIA support expands attack surface, and (4) lack of visible security policy. The project appears well-maintained with active CI/CD workflows and uses standard Rust tooling. Recommendations focus on dependency auditing with 'cargo audit', documentation of security practices, and careful management of optional features.

• Medium · Incomplete Dependency List — Cargo.toml - [dependencies] section. The Cargo.toml file shows truncated dependency declarations (e.g., 'iterto' appears cut off). This makes it impossible to fully assess all dependencies for known security vulnerabilities. The complete dependency tree cannot be verified. Fix: Provide the complete Cargo.toml file. Run 'cargo audit' regularly to check for known vulnerabilities in dependencies. Ensure all dependencies are pinned to specific versions or ranges that have been audited.
• Low · Edition 2024 May Not Be Stable — Cargo.toml - edition field. The Cargo.toml specifies edition = '2024', which is beyond the current stable Rust edition (2021). This may indicate a configuration error or use of unstable/nightly features that could introduce compatibility issues. Fix: Verify this is intentional. If using features from 2024 edition, ensure all CI/CD and build systems support this. Consider using edition = '2021' for broader compatibility unless there's a specific requirement for 2024 features.
• Low · Feature Flags with Security Implications — Cargo.toml - [features] section. The 'deploy' feature includes GPU (nvidia) support which requires external NVIDIA libraries. This expands the attack surface if not properly managed. The 'logging' feature uses 'fern' and 'log' which could expose sensitive information if misconfigured. Fix: Ensure GPU/NVIDIA dependencies are from official sources and regularly updated. Review logging configuration to prevent sensitive data (passwords, tokens, system paths) from being logged. Use conditional logging levels in production builds.
• Low · Missing Security.md or Vulnerability Disclosure Policy — Repository root. No visible security policy file (SECURITY.md) in the repository structure to guide responsible vulnerability disclosure. Fix: Create a SECURITY.md file with instructions for reporting vulnerabilities responsibly. Include contact information and expected response timeframes.
• Low · Build Script Present — build.rs. The presence of build.rs indicates custom build-time code execution. While necessary for legitimate builds, this should be audited to ensure it doesn't execute untrusted code or perform unsafe operations. Fix: Review build.rs to ensure it only performs necessary build-time operations. Avoid downloading files or executing arbitrary commands during build. Use checksums for any downloaded artifacts.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ClementTsang/bottom shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ClementTsang/bottom repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ClementTsang/bottom.

What it runs against: a local clone of ClementTsang/bottom — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ClementTsang/bottom | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ClementTsang/bottom. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ClementTsang/bottom.git
#   cd bottom
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ClementTsang/bottom and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ClementTsang/bottom(\\.git)?\\b" \\
  && ok "origin remote is ClementTsang/bottom" \\
  || miss "origin remote is not ClementTsang/bottom (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "build.rs" \\
  && ok "build.rs" \\
  || miss "missing critical file: build.rs"
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/app/mod.rs" \\
  && ok "src/app/mod.rs" \\
  || miss "missing critical file: src/app/mod.rs"
test -f "docs/content/configuration/config-file/index.md" \\
  && ok "docs/content/configuration/config-file/index.md" \\
  || miss "missing critical file: docs/content/configuration/config-file/index.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ClementTsang/bottom"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.