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/bpytop 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 all four use cases

• Last commit 11mo ago
• 16 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 11mo ago
• ⚠ Concentrated ownership — top contributor handles 74% of recent commits

_{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/bpytop repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/aristocratos/bpytop.

What it runs against: a local clone of aristocratos/bpytop — 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/bpytop | 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 master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 369 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "aristocratos/bpytop(\\.git)?\\b" \\
  && ok "origin remote is aristocratos/bpytop" \\
  || miss "origin remote is not aristocratos/bpytop (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "bpytop.py" \\
  && ok "bpytop.py" \\
  || miss "missing critical file: bpytop.py"
test -f "pyproject.toml" \\
  && ok "pyproject.toml" \\
  || miss "missing critical file: pyproject.toml"
test -f "tests/test_classes.py" \\
  && ok "tests/test_classes.py" \\
  || miss "missing critical file: tests/test_classes.py"
test -f "tests/test_functions.py" \\
  && ok "tests/test_functions.py" \\
  || miss "missing critical file: tests/test_functions.py"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"

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

bpytop is a Python-based system resource monitor for Linux, macOS, and FreeBSD that displays real-time CPU, memory, disk, and network statistics in an interactive terminal UI. It reads system metrics from /proc, /sys, and platform-specific APIs to render a visually rich dashboard with customizable color themes, replacing the older bashtop bash implementation. Monolithic Python application: bpytop.py is the main entry point; themes/ folder contains 14 .theme color definitions; tests/ covers test_classes.py, test_functions.py, test_title.py; pyproject.toml and poetry.lock define Python package metadata and lockfile. Makefile handles build/install tasks. No deep package structure; logic is concentrated in the root bpytop.py module.

Linux/Unix system administrators and developers who need a htop/top alternative with a modern Python codebase they can extend, theme, and understand. Contributors interested in building terminal UIs or system monitoring tools in Python.

Production-ready but transitioning to maintenance mode. The repo has 14+ custom themes, CI via GitHub Actions (see .github/workflows/testing.yml), and test coverage (tests/ directory). However, the maintainer has shifted focus to btop (C++ rewrite) as of September 2021, suggesting bpytop is no longer the primary active project. Likely receives bug fixes but not major new features.

Low risk for end-users; moderate risk for contributors relying on active development. Single maintainer (aristocratos), no visible recent commits in the provided snapshot, and the CHANGELOG + README explicitly note btop++ as the successor. Dependencies are minimal (Python 3.7+, psutil for cross-platform /proc reading), reducing supply-chain risk. Main risk: features will not be backported from btop++, and platform-specific bugs may languish.

The project is in maintenance mode. The most significant recent activity is the announcement of btop++ (C++ successor) with roadmap for 1.1.0 (macOS), 1.2.0 (FreeBSD), and 1.3.0 (GPU monitoring). bpytop itself is unlikely to receive major feature updates; focus is on stability and bug fixes. No active PRs or issues visible in the provided file list.

Clone the repo, install dependencies via poetry, and run:

git clone https://github.com/aristocratos/bpytop.git
cd bpytop
poetry install
poetry run python bpytop.py

Alternatively, use make install (see Makefile for system-wide install).

Daily commands: Execute python bpytop.py or poetry run python bpytop.py from repo root after poetry install. Check Makefile for system-level install targets (make install, make uninstall).

• bpytop.py — Main entry point and orchestrator for the resource monitor; contains the core event loop and UI rendering logic that every contributor must understand
• pyproject.toml — Project configuration, dependencies, and build metadata; essential for setting up development environment and understanding Python version requirements
• tests/test_classes.py — Core unit tests for classes that validate business logic; contributors should run these before submitting changes
• tests/test_functions.py — Unit tests for utility functions and data collection; ensures cross-platform compatibility (Linux/OSX/FreeBSD)
• Makefile — Build and deployment automation; defines how the project is tested, installed, and packaged
• themes/default_black.theme — Reference theme file demonstrating the theme format; needed to understand how to add or modify color schemes

• bpytop.py (Python 3.7+, POSIX APIs, curses/terminal control) — Core orchestrator; owns data collection logic, UI state machine, rendering, and theme loading
  • Failure mode: If metric collection fails, UI may freeze; if rendering breaks, terminal corrupted; if theme parse fails, falls back to defaults
• System APIs (via bpytop.py) (Linux /proc, OSX sysctl, FreeBSD syscalls) — Abstracts /proc, sysctl, and system calls for CPU, memory, disk, process metrics per platform
  • Failure mode: If /proc missing (non-Linux) or sysctl fails, metrics return zero or error; code branches handle missing data
• Theme files (themes/*.theme) (YAML-like key-value format) — Define color palette and styling rules for UI elements; no logic
  • Failure mode: If theme file invalid or missing, bpytop falls back to default_black.theme or hardcoded colors
• Test suite (tests/) (pytest, tox, platform mocking) — Validates metric collection accuracy, data class integrity, and UI title generation across platforms
  • Failure mode: Test failures signal platform-specific regressions; CI blocks merges if tests fail

• System kernel → bpytop.py (metric collection functions) — Kernel exports process, CPU, memory, disk stats via /proc (Linux), sysctl (OSX), or equivalent
• bpytop.py (metric collection) → bpytop.py (data model classes) — Raw metrics parsed and aggregated into CPU, Memory, Disk, Process objects with computed fields (deltas, percentages)
• bpytop.py (data models) → bpytop.py (UI rendering) — Aggregated metrics formatted and positioned for terminal display
• themes/*.theme → bpytop.py (UI rendering) — Theme colors applied to rendered text before sending to terminal

Add a new system metric display

1. Create a data collection function in bpytop.py that reads the metric from /proc (Linux) or system calls (OSX/FreeBSD) (bpytop.py)
2. Write unit tests for the new metric collection across all three platforms (tests/test_functions.py)
3. Add a class to bpytop.py to model the metric data structure (bpytop.py)
4. Integrate the metric into the main UI rendering loop in bpytop.py (bpytop.py)
5. Update default theme colors in themes/default_black.theme to style the new metric (themes/default_black.theme)

Add a new color theme

1. Copy themes/default_black.theme to themes/myname.theme (themes/myname.theme)
2. Edit the color hex values in the new .theme file for each UI element (themes/myname.theme)
3. Test the theme by running bpytop.py with the --theme flag (implementation in main) (bpytop.py)

Fix a cross-platform compatibility bug

1. Identify the platform-specific code path in bpytop.py using sys.platform checks (bpytop.py)
2. Add a new test case in tests/test_functions.py that reproduces the bug on the affected platform (tests/test_functions.py)
3. Modify the platform-specific implementation in bpytop.py (bpytop.py)
4. Run Makefile test targets to verify fix across all platforms via tox (Makefile)

• Python 3.7+ — Cross-platform scripting language supporting Linux, OSX, and FreeBSD; good standard library for system calls
• POSIX APIs (/proc, sysctl, system calls) — Direct access to kernel metrics across Unix-like systems; more accurate than parsing tool output
• Poetry + pyproject.toml — Modern Python dependency management with reproducible builds and clear version constraints
• pytest + tox — Ensures code quality across Python versions and platforms before release

• Single monolithic bpytop.py file instead of modular package structure

  • Why: Simplifies deployment as a single-file tool; easier distribution via pip and package managers
  • Consequence: File grows large with UI, data collection, and theme logic mixed; refactoring requires careful planning

• Direct system API calls rather than abstracting via psutil library

  • Why: Tighter control over metric collection; avoids external dependency bloat
  • Consequence: Must maintain platform-specific code paths (sys.platform checks) for Linux/OSX/FreeBSD compatibility

• Synchronous single-threaded event loop

  • Why: Simpler code; sufficient for refresh rates ~1s; avoids threading complexity
  • Consequence: Brief UI freezes during heavy I/O possible; not suitable for sub-100ms updates

• YAML-like .theme files instead of JSON or structured format

  • Why: Human-readable and easy to edit for end-users without programming knowledge
  • Consequence: Requires custom parser in bpytop.py; no off-the-shelf theme validation tools

• Remote monitoring (local system only)
• Persistent data logging or history storage
• Real-time data export to monitoring platforms
• Interactive process killing or resource management (read-only monitor)
• Windows support (POSIX systems only)

Terminal capability detection: the app relies on curses/ncurses features that may not work in all terminal emulators (e.g., truecolor support). psutil version differences: /proc parsing differs between Linux versions and kernel releases. No explicit Python environment isolation in the Makefile; may install globally or pollute system Python. Theme loading order and fallback behavior not documented in README. Configuration directory conventions (~/.config/bpytop or similar) likely hardcoded in bpytop.py but not explicitly listed in docs.

• /proc filesystem — bpytop reads CPU, memory, disk, and network stats from /proc on Linux; understanding /proc/stat, /proc/meminfo, /proc/net/* is essential for debugging metric collection or extending the monitor.
• psutil library and cross-platform abstraction — psutil abstracts /proc (Linux), sysctl (macOS/FreeBSD), and WMI (Windows) differences; bpytop relies on psutil's API to remain portable across OSes without rewriting metric gathering code per platform.
• ncurses/curses terminal UI — bpytop uses Python's curses module to render the TUI; understanding curses (windows, colors, key event handling) is necessary to modify UI layout or add interactive features.
• Theme/config file parsing and templating — bpytop loads themes from flat .theme files and dynamically applies color schemes; the theme system demonstrates config-driven UI customization without code changes, a pattern useful for extensible terminal apps.
• Platform detection and conditional compilation — bpytop branches on os_type (Linux/macOS/FreeBSD) to handle OS-specific metric sources and APIs; contributors must test changes across multiple platforms or use platform-mocking in tests.
• Real-time sampling and rate limiting in event loops — bpytop continuously samples /proc and redraws the UI at a fixed refresh rate without blocking on input; understanding event loop design (select/poll, non-blocking I/O) is key to modifying update frequency or responsiveness.

• aristocratos/btop — Official C++ successor to bpytop; where active development and new features (GPU support, macOS/FreeBSD) are happening post-2021.
• htop-dev/htop — Canonical ncurses-based system monitor in C; bpytop is the Pythonic alternative and reimplements many of htop's features and UI patterns.
• giampaolo/psutil — Core dependency for bpytop's cross-platform /proc and system metric gathering; critical for understanding how metrics are collected.
• nicolargo/glances — Alternative Python system monitor with similar goals (cross-platform, real-time metrics); useful reference for Python curses/TUI patterns.
• dylanaraps/pure-bash-bible — Spiritual predecessor: bashtop (pure bash) was the original version before bpytop; demonstrates the evolution from shell scripting to Python for system tools.

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 platform-specific integration tests in tests/ for Linux/OSX/FreeBSD

The repo supports three major platforms (Linux, OSX, FreeBSD) but tests/ only contains basic unit tests (test_classes.py, test_functions.py, test_title.py). There are no platform-specific integration tests to verify resource monitoring accuracy across different OS implementations. This is critical for a system resource monitor where OS-specific behavior varies significantly.

• [ ] Create tests/test_linux_monitor.py with CPU, memory, and disk read tests using /proc filesystem
• [ ] Create tests/test_osx_monitor.py with equivalent tests using OSX-specific APIs
• [ ] Create tests/test_freebsd_monitor.py with FreeBSD-specific system call verification
• [ ] Update tox.ini to conditionally run platform-specific tests based on OS detection
• [ ] Document expected behavior differences in CONTRIBUTING.md for platform testing

Add missing GitHub Actions workflow for multi-platform testing

The repo has .github/workflows/testing.yml but it likely only runs on Linux (standard GitHub Actions default). Given that bpytop explicitly supports OSX and FreeBSD, there should be a multi-platform CI workflow. This ensures code changes don't break functionality on non-Linux systems before merging.

• [ ] Expand .github/workflows/testing.yml to use matrix strategy with ubuntu-latest, macos-latest, and a FreeBSD runner
• [ ] Configure platform-specific test commands using conditional steps (if: runner.os == 'Linux')
• [ ] Update GitHub Actions to test against Python 3.7+ across all platforms
• [ ] Document FreeBSD runner setup in CONTRIBUTING.md if using third-party FreeBSD action

Add comprehensive theme validation tests in tests/test_themes.py

The repo includes 14+ theme files in themes/ directory with no apparent validation tests. Theme files are user-facing configuration that could be malformed, and there's no automated check that all themes parse correctly or contain required color definitions. This prevents theme regressions and validates new community theme contributions.

• [ ] Create tests/test_themes.py to iterate through all .theme files in themes/
• [ ] Add tests to verify each theme file parses as valid config (YAML or custom format used by bpytop)
• [ ] Validate that required color keys are present in each theme (based on default_black.theme structure)
• [ ] Test that theme inheritance/overrides work correctly if supported
• [ ] Add test to ensure bpytop-themes/ submodule themes also validate

• Add type hints to bpytop.py: the monolithic main file has no type annotations. Start by adding type hints to utility functions in tests/test_functions.py, then propagate to the main module. This improves maintainability without changing behavior.
• Expand test coverage for platform-specific code paths: tests/test_classes.py and test_functions.py likely do not cover all Linux/macOS/FreeBSD conditional branches in bpytop.py. Write platform-mocked tests (using unittest.mock) for the OS detection and metric gathering code.
• Document theme file format and add a theme template: themes/ has 14 examples but no formal spec. Create themes/TEMPLATE.theme with inline comments explaining each color key, update README.md with theme authoring guide, and add a linter script (e.g., tests/test_themes.py) to validate .theme syntax.

The bpytop codebase appears to be a well-structured system monitoring tool with reasonable security practices. No critical vulnerabilities were identified in the visible structure. Primary concerns include: (1) inability to assess dependencies due to missing package file contents, (2) potential command injection risks inherent to system monitoring tools that must execute privileged commands, and (3) theme file processing which could be exploited if not properly validated. The project follows good practices with GitHub Actions CI/CD and organized code structure. Recommendations focus on dependency management, input validation for system calls, and theme file security.

• Medium · Missing Dependency Information — pyproject.toml, poetry.lock. The dependency/package file content was not provided for analysis. Unable to verify if the project uses outdated or vulnerable dependencies. The project appears to use Python 3.7+ based on README, but exact dependencies from pyproject.toml or poetry.lock cannot be verified. Fix: Provide dependency files for analysis. Regularly run 'pip audit' or 'poetry check' to identify vulnerable dependencies. Use tools like Dependabot to automatically detect and alert on vulnerable packages.
• Low · Potential Command Execution via System Monitoring — bpytop.py (main module). As a system resource monitor, bpytop likely executes system commands to gather resource information. If user input is not properly sanitized before being passed to system commands, this could lead to command injection vulnerabilities. Fix: Ensure all system calls use subprocess with shell=False and proper argument passing. Never concatenate user input directly into command strings. Use shlex.quote() for any required shell escaping.
• Low · Theme File Processing — themes/ directory. The themes directory contains multiple .theme files that are processed by the application. If theme files are parsed without proper validation, malicious theme files could potentially cause issues (e.g., via path traversal or code injection if themes support expressions). Fix: Implement strict validation when parsing theme files. Use whitelisting for allowed configuration keys and values. Sanitize any file paths referenced in theme configurations. Consider using a safe configuration parser (e.g., configparser with safe restrictions).

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.