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/aristocratos/btop 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.

GO — Healthy across the board

• Last commit 1w ago
• 24+ active contributors
• Distributed ownership (top contributor 30% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

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

What it runs against: a local clone of aristocratos/btop — 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 aristocratos/btop | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | 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 ≤ 37 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of aristocratos/btop. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/aristocratos/btop.git
#   cd btop
#
# 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 aristocratos/btop and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 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 "src/main.cpp" \\
  && ok "src/main.cpp" \\
  || miss "missing critical file: src/main.cpp"
test -f "src/btop.cpp" \\
  && ok "src/btop.cpp" \\
  || miss "missing critical file: src/btop.cpp"
test -f "src/btop_collect.cpp" \\
  && ok "src/btop_collect.cpp" \\
  || miss "missing critical file: src/btop_collect.cpp"
test -f "src/linux/btop_collect.cpp" \\
  && ok "src/linux/btop_collect.cpp" \\
  || miss "missing critical file: src/linux/btop_collect.cpp"
test -f "src/btop_draw.cpp" \\
  && ok "src/btop_draw.cpp" \\
  || miss "missing critical file: src/btop_draw.cpp"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 37 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~7d)"
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/aristocratos/btop"
  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).

btop++ is a C++23 cross-platform system resource monitor that displays real-time CPU, memory, disk, network, and process metrics in a TUI (text user interface). It's a modern successor to bashtop, compiled natively for Linux, macOS, FreeBSD, NetBSD, and OpenBSD, providing granular resource visualization without external dependencies beyond the fmt library. Single monolithic C++ application: src/ likely contains the core monitor logic, include/fmt/ contains the vendored formatting library, cmake/ holds platform-specific detection modules (Findkvm.cmake, Finddevstat.cmake for BSD-specific syscalls), and .github/workflows/ defines build matrix for Linux/macOS/FreeBSD/NetBSD/OpenBSD. Configuration is file-based (btop.desktop suggests freedesktop integration).

System administrators, DevOps engineers, and power users who need a fast, detailed resource monitoring tool that runs directly in the terminal without heavyweight desktop applications. Contributors are primarily C++23 developers interested in cross-platform systems programming and TUI optimization.

Production-ready and actively maintained. The project has continuous build workflows across 5 BSD/Linux variants and macOS, CMake-based compilation infrastructure, multi-platform CI/CD (GitHub Actions), and appears to be the canonical modern replacement for bashtop. Commits are regular, packaging status shows wide distribution (Repology badge), and the project supports snap installation.

Low risk for a single-author project with strong platform coverage. The main risk is reliance on aristocratos as sole maintainer, but the codebase is self-contained (vendored fmt library at include/fmt/), has no heavy external dependencies, and builds reproducibly across OSes. No breaking API surface to other projects, though syscall compatibility with BSD/Linux variants could diverge.

Continuous integration across 5 operating systems via GitHub Actions workflows (continuous-build-*.yml files), GPU support being added (continuous-build-gpu.yml), and security scanning with zizmor.yml. The project uses Renovate for dependency updates and actively maintains Snap packaging. No specific milestones visible in provided files, but multiplatform stability appears to be the focus.

Clone and build with: git clone https://github.com/aristocratos/btop.git && cd btop && cmake -B build && cmake --build build. Install with make install (per Makefile) or use your OS package manager (apt/brew/pkg). Run with btop command.

Daily commands: cmake -B build && cmake --build build produces the executable, then run ./build/btop or btop if installed system-wide. For development: make targets likely exist (see Makefile at repo root).

• src/main.cpp — Entry point for btop; initializes the application, sets up signal handlers, and orchestrates the main event loop.
• src/btop.cpp — Core application logic that coordinates data collection, drawing, and input handling; every contributor must understand the main draw-collect-input cycle.
• src/btop_collect.cpp — Platform-agnostic data collection interface; all OS-specific collectors implement this pattern—critical for cross-platform support.
• src/linux/btop_collect.cpp — Linux-specific system metrics collection from /proc and sysfs; most users run on Linux, making this the heaviest-used collector.
• src/btop_draw.cpp — Rendering and terminal UI output logic; responsible for all visual updates and theme application across the display.
• src/btop_input.cpp — User input handling and keybinding logic; manages interactive features like menus, sorting, and configuration.
• CMakeLists.txt — Build configuration for multi-platform compilation; defines platform detection, dependency requirements, and GPU module integration.

Add a new system metric to collection

1. Define the metric struct in src/btop_collect.cpp (e.g., add field to struct collect_info) (src/btop_collect.cpp)
2. Implement platform-specific collection in target OS collector (e.g., parse from /proc on Linux) (src/linux/btop_collect.cpp)
3. Repeat for other platforms (FreeBSD, macOS, OpenBSD, NetBSD) by editing their respective btop_collect.cpp (src/freebsd/btop_collect.cpp)
4. Add rendering logic in src/btop_draw.cpp to display the new metric in the UI (src/btop_draw.cpp)
5. Optionally add configuration option in src/btop_config.cpp if the metric should be toggleable (src/btop_config.cpp)

Add a new keybinding or interactive feature

1. Define the keybinding constant in src/btop_input.hpp or update the key map in src/btop_input.cpp (src/btop_input.cpp)
2. Add input handling logic in the input event loop in src/btop_input.cpp to detect the key and dispatch the action (src/btop_input.cpp)
3. Implement the action logic in src/btop.cpp (main loop controller) or relevant module (e.g., menu handling in src/btop_menu.cpp) (src/btop.cpp)
4. Update the help menu text in src/btop_menu.cpp to document the new keybinding for users (src/btop_menu.cpp)

Add a new color theme

1. Create a new theme file in the user's config directory (e.g., ~/.config/btop/themes/mytheme.theme) with color definitions (src/btop_theme.cpp)
2. Use the theme loading logic in src/btop_theme.cpp which parses the color file automatically (src/btop_theme.cpp)
3. Reference the theme in configuration via src/btop_config.cpp theme setting (src/btop_config.cpp)
4. Verify rendering by running btop; theme colors are applied during draw phase in src/btop_draw.cpp (src/btop_draw.cpp)

• C++23 — Modern language features (ranges, formatting, spaceship operator) enable clean, efficient system monitoring code; compiled binaries are fast and have minimal runtime overhead.
• CMake — Cross-platform build abstraction allows single configuration to target Linux, macOS, FreeBSD, OpenBSD, NetBSD with platform-specific compiler flags and library discovery.
• fmt library (vendored) — Modern, type-safe string formatting replacing printf-style calls; reduces bugs and improves performance in high-frequency rendering code.
• Platform-specific OS APIs (procfs, sysctl, libproc, IOKit, kvm) — Direct OS interface access avoids heavy dependencies; each platform's collector uses native, lightweight APIs optimized for that OS.
• ANSI/VT100 terminal sequences — Universal terminal control without ncurses dependency; enables portable, minimal-overhead rendering across Unix-like systems.

• Platform-specific collectors (separate files per OS) rather than shared abstraction

  • Why: Each OS exposes system metrics via fundamentally different interfaces (/proc vs. sysctl vs. IOKit); tight coupling to OS APIs provides best performance and accuracy.
  • Consequence: Code duplication across collectors; adding a metric requires changes in 5 files. Mitigation: shared data structures in btop_collect.cpp define the interface.

• Non-blocking, high-frequency poll loop (100ms refresh) instead of event-driven or signal-based updates

  • Why: System metrics are continuous; polling ensures smooth, responsive UI updates and simple control flow.
  • Consequence: Higher CPU usage than a sleep-based daemon; acceptable for an interactive monitor where responsiveness is paramount.

• Vendored fmt library instead of std::format (C++20)

  • Why: Older compilers and broader compatibility; fmt is more mature and feature-complete.
  • Consequence: Larger binary and header overhead; mitigated by header-only include model.

• Configuration files in user home directory (~/.config/btop) instead of system-wide config

  • Why: Respects Unix principle of per-user configuration; aligns with XDG Base Directory spec.
  • Consequence: Settings are per-user; system-wide defaults require installation in multiple home directories or environment variables.

• Real-time guarantees—btop is a sampling monitor, not a hard real-time system.
• Remote monitoring over network—all data collection is local to the running system.
• Persistent data logging—btop displays live metrics; historical data is not stored.
• Root/elevated privilege execution—some metrics may be restricted without sudo, user accepts reduced visibility.
• GUI/

Platform-specific syscall differences: FreeBSD uses kvm/devstat libraries unavailable on Linux; NetBSD/OpenBSD use proplib. CMake must detect these correctly or build fails silently. C++23 requires recent compiler versions (gcc ≥11 or clang ≥14). The vendored fmt library at include/fmt/ must not be updated independently of upstream compatibility. Building on BSD variants requires system headers in non-standard paths (handled by Findkvm.cmake, but easy to miss if not using CMake). No containerized development environment provided, so native BSD testing is difficult.

• Virtual Memory Management & /proc/stat parsing — btop reads Linux /proc/stat and BSD sysctl/kvm for memory pages, swap, and cache—understanding page frames vs. virtual addresses is essential for correct metrics display
• BSD kvm (kernel virtual memory) library — FreeBSD/OpenBSD/NetBSD require kvm_* syscalls to read kernel memory directly—this is the core abstraction hiding OS differences that btop abstracts in cmake/Findkvm.cmake
• sysctl interface (BSD/macOS) — macOS and BSD systems expose hardware metrics (CPU count, memory, uptime) via sysctl MIB tree instead of /proc; btop must call sysctl() with correct OID chains
• Terminal Control Sequences (ANSI/CSI) — TUI rendering uses ANSI escape codes for colors, cursor positioning, and screen clearing—btop must emit correct CSI sequences for portable terminal support
• CMake cross-compilation & platform detection — btop's CMakeLists.txt uses custom Find*.cmake modules to detect platform libraries (kvm, devstat, proplib, elf)—understanding CMAKE_SYSTEM_NAME and find_library() patterns is essential for porting
• Process and task enumeration via /proc and procfs variants — btop lists processes by parsing /proc/[pid]/ on Linux or using procctl/kvm on BSD—each OS exposes different file layouts and requires OS-specific code paths
• C++23 modules and std::format — btop targets C++23 features; the vendored fmt library (at include/fmt/) is a backport of C++20 std::format to older compilers—understanding fmt's string formatting API is critical for any output changes

• gofumpt/gofumpt — Similar TUI-first philosophy for system tools; shows patterns for cross-platform CLI/TUI development
• htop-dev/htop — Direct competitor in resource monitoring space; htop is portable C (POSIX) while btop is C++23, shows design trade-offs for process listing
• sharkdp/bat — Similar Rust rewrite philosophy (speed + features); demonstrates how modern rewrites of Unix tools gain platform coverage
• fmtlib/fmt — Upstream of the vendored dependency at include/fmt/; btop vendors fmt to avoid version conflicts across BSD/Linux package managers

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 comprehensive unit tests for btop_config.cpp configuration parsing

The repo has extensive CI/CD workflows for building across Linux, macOS, FreeBSD, NetBSD, and OpenBSD, but there are no visible unit tests for the configuration system (btop_config.cpp/hpp). Configuration parsing is critical for cross-platform compatibility and user experience. Adding tests would catch regressions early and document expected behavior for contributors.

• [ ] Create src/tests/ directory structure with CMake integration
• [ ] Write unit tests for btop_config.cpp covering: config file parsing, default values, validation, and error handling
• [ ] Add test CMake target to CMakeLists.txt
• [ ] Integrate test execution into cmake-linux.yml and cmake-freebsd.yml workflows as a post-build step
• [ ] Document test running instructions in CONTRIBUTING.md

Add platform-specific integration tests in GitHub Actions for GPU monitoring

There is a continuous-build-gpu.yml workflow but no corresponding test validation. The GPU monitoring feature is complex and platform-specific. Integration tests would verify GPU data collection works correctly across different GPU types and drivers, preventing silent failures in GPU monitoring.

• [ ] Extend continuous-build-gpu.yml to validate GPU metrics are being collected (not just that build succeeds)
• [ ] Create src/tests/gpu_monitor_test.cpp to test GPU detection and data parsing
• [ ] Add conditional compilation flags to CMakeLists.txt for GPU tests
• [ ] Document GPU testing requirements (NVIDIA/AMD drivers needed) in CONTRIBUTING.md
• [ ] Add skip logic in CI workflow for runners without GPU hardware

Add input/keybinding documentation and validation tests for btop_input.cpp

The btop_input.cpp file handles user interactions across multiple platforms with different terminal capabilities. There is no visible test coverage for input handling, and the keybinding system is complex. Adding validation tests and documenting the input model would help contributors understand input flow and catch platform-specific input bugs early.

• [ ] Create src/tests/input_handler_test.cpp with tests for: key parsing, modifier combinations, terminal type detection
• [ ] Document keybinding architecture and platform differences in docs/INPUT_DESIGN.md
• [ ] Add tests for terminal escape sequence parsing edge cases
• [ ] Integrate input tests into cmake-linux.yml, cmake-macos.yml, and cmake-freebsd.yml workflows
• [ ] Add test cases for known platform-specific input issues referenced in CHANGELOG.md

• Add unit tests for the fmt library vendoring to catch version mismatches across platforms—currently no test/ directory visible; contribute test suite that validates formatting on Linux/macOS/FreeBSD
• Document the platform detection flow in cmake/Find*.cmake modules with inline comments—these files are complex (kvm/devstat/proplib abstractions) but undocumented; add explanation of what each CMake find module does and why it's platform-specific
• Create GitHub issue templates for platform-specific bugs—currently issue templates exist but don't prompt reporters to specify OS or compiler version; enhance templates to include CMake output, compiler version (gcc/clang/appleclang), and OS version

The btop codebase is a C++23 system monitoring application with generally good security posture. No critical vulnerabilities were identified from the provided file structure. Main concerns are: (1) potential buffer overflows in platform-specific system data collection routines that require code review, (2) format string safety in logging functionality, (3) keeping bundled fmt library updated, and (4) proper handling of large integer values in resource calculations. The absence of visible dependency files, hardcoded credentials, web components, or database operations reduces attack surface. Recommendations focus on defensive coding practices for native C++ system programming and regular dependency maintenance.

• Medium · Potential Buffer Overflow in System Data Collection — src/linux/btop_collect.cpp, src/freebsd/btop_collect.cpp. The codebase collects system resource data across multiple platforms (Linux, FreeBSD, etc.). Without visibility into btop_collect.cpp implementations, there's a risk of buffer overflows when parsing /proc filesystem files or system APIs that may contain unexpected data sizes. Fix: Review all buffer allocations and string parsing operations. Use bounds-checking functions, validate input sizes before copying, and consider using safe string libraries or STL containers with automatic bounds management.
• Medium · Potential Format String Vulnerability in Logging — src/btop_log.cpp, src/btop_log.hpp. The presence of btop_log.cpp suggests logging functionality. Format string vulnerabilities can occur if user-controlled input or system data is passed directly to format functions without proper validation. Fix: Ensure all logging uses format strings as compile-time constants. Never pass dynamic data as format strings. Use parameterized logging: fmt::print("{}", data) instead of fmt::print(data).
• Low · Third-party Dependency - fmt Library — include/fmt/. The codebase includes the fmt library (include/fmt). While fmt is generally well-maintained, bundled third-party libraries should be kept updated to address any discovered vulnerabilities. Fix: Regularly update the fmt library to the latest stable version. Monitor fmt's security advisories and consider using package managers for dependency management instead of bundling.
• Low · Potential Information Disclosure via System Process Monitoring — src/btop_collect.cpp (platform-specific implementations). As a system resource monitor, btop may expose sensitive information about running processes, memory usage, and system configuration to any user with access to the application. Fix: Document permission requirements. Ensure sensitive data is only readable by appropriate users. Consider implementing access control mechanisms if sensitive process information is displayed.
• Low · Integer Overflow Risk in Resource Calculations — src/linux/btop_collect.cpp, src/freebsd/btop_collect.cpp, src/btop_tools.cpp. System monitoring involves numerous arithmetic operations on resource metrics (memory, CPU, disk). Large values could potentially overflow if using 32-bit integers or improper casting. Fix: Use 64-bit integer types (uint64_t, int64_t) for all resource calculations. Validate calculations don't overflow before use. Add range checks for memory and storage conversions.

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

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

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