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/cjbassi/gotop 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.

WAIT — Stale — last commit 3y ago

• 11 active contributors
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

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

What it runs against: a local clone of cjbassi/gotop — 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 cjbassi/gotop | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.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 ≤ 1164 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.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 "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "src/widgets" \\
  && ok "src/widgets" \\
  || miss "missing critical file: src/widgets"
test -f "src/termui/linegraph.go" \\
  && ok "src/termui/linegraph.go" \\
  || miss "missing critical file: src/termui/linegraph.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "colorschemes/default.go" \\
  && ok "colorschemes/default.go" \\
  || miss "missing critical file: colorschemes/default.go"

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

gotop is a terminal-based system activity monitor written in Go that displays real-time CPU, memory, disk, network, and process information with interactive graphs and tables. It provides a TUI alternative to desktop system monitors like gtop and vtop, running entirely in the terminal with mouse and keyboard support for process management. Modular single-binary architecture: main.go is the entry point; src/widgets/ contains reusable widget components (cpu.go, battery.go) that extend termui; src/termui/ wraps third-party termui/v3 with custom line graphs and tables; src/utils/ provides helper functions (bytes.go, conversions.go); colorschemes/ hold theme definitions as Go files and JSON; build/ handles packaging (nfpm.yml for Linux distributions).

Linux/macOS/FreeBSD system administrators and developers who want a lightweight, full-featured system monitor that runs in the terminal without GUI dependencies. Users who prefer keyboard-driven interfaces and want to kill processes or inspect system load directly from their terminal.

The project is no longer actively maintained by the original author (cjbassi) — the README explicitly states 'NO LONGER MAINTAINED' and directs users to a maintained fork at xxxserxxx/gotop. The codebase appears stable (last CI setup via .travis.yml, Go modules in go.mod), but lacks recent commit activity and active issue triage.

High maintenance risk: single original maintainer with no activity, and the project is explicitly abandoned in favor of a fork. Dependency risk is moderate — relies on gopsutil (shirou) for system metrics and termui/v3 (gizak) for rendering, both external unmaintained or slowly-updated libraries. No unit tests visible in file structure (no *_test.go files listed), only shell scripts in ci/. Windows support explicitly not implemented.

The project is in maintenance-only mode. The README directs all users to the maintained fork (xxxserxxx/gotop). No active development indicated by the file structure — no open PR directory, no active CI beyond .travis.yml, and no recent changelog updates visible in the snippet provided.

git clone https://github.com/cjbassi/gotop.git
cd gotop
go build -o gotop ./main.go
./gotop

Or install from source with go get github.com/cjbassi/gotop (requires Go 1.11+).

Daily commands: Development: make (see Makefile) or go run main.go. Binary: go build -o gotop or use prebuilt binaries via scripts/download.sh. Options: gotop -c monokai -r 2 (set colorscheme, update 2x/sec); gotop -m (minimal mode, CPU/Mem/Processes only); gotop -p (per-CPU display).

• main.go — Application entry point and main event loop; all contributors must understand the core initialization and widget rendering pipeline
• src/widgets — Widget interface implementations (cpu.go, mem.go, net.go, etc.) form the data-collection and UI backbone; essential for adding new monitoring features
• src/termui/linegraph.go — Custom terminal UI graph rendering component used by CPU, memory, and network widgets; critical for understanding visual output
• go.mod — Dependency manifest; gopsutil and termui/v3 are the primary OS metrics and rendering libraries
• colorschemes/default.go — Color scheme abstraction; referenced by main.go and all widgets for consistent theming
• src/utils/conversions.go — Unit conversion utilities (bytes, percentages) shared across all metric widgets

Add a New System Metric Widget

1. Create a new widget file in src/widgets/ (e.g., src/widgets/gpu.go) that implements widget initialization and update logic (src/widgets/gpu.go)
2. For platform-specific code, create gpu_linux.go, gpu_darwin.go, etc. following the pattern in src/widgets/temp_*.go (src/widgets/gpu_linux.go)
3. In main.go, instantiate the widget and add it to the widgets grid layout (main.go)
4. If the widget displays a time series, use src/termui/linegraph.go; for tables, use src/termui/table.go (src/termui/linegraph.go)
5. Use src/utils/conversions.go for unit formatting (e.g., MB, GB) in your widget's display callback (src/utils/conversions.go)

Add a New Color Scheme

1. Create a new file in colorschemes/ (e.g., colorschemes/dracula.go) that implements the Colorscheme interface (colorschemes/dracula.go)
2. Define color struct with fields matching colorschemes/default.go (Fg, Bg, HighlightFg, etc.) (colorschemes/default.go)
3. In main.go, add a command-line flag case and instantiate your colorscheme (main.go)

Support a New Platform or OS

1. Create platform-specific widget implementations (e.g., src/widgets/mem_netbsd.go) following the pattern in src/widgets/mem_*.go (src/widgets/mem_other.go)
2. For temperature, create src/widgets/temp_netbsd.go (FreeBSD and OpenBSD examples exist) (src/widgets/temp_freebsd.go)
3. For process list, create src/widgets/proc_netbsd.go if needed (see proc_linux.go, proc_freebsd.go, proc_windows.go) (src/widgets/proc_linux.go)
4. Test with gopsutil to ensure it works on the target OS; update README.md with compatibility notes (README.md)

• Go — Cross-platform, statically compiled binary with minimal dependencies; ideal for lightweight CLI tools that target multiple OSes (Linux, macOS, FreeBSD, Windows)
• gopsutil (shirou/gopsutil) — Unified, well-maintained interface to OS-level metrics (CPU, memory, disk, network, processes) across Linux, Windows, macOS, and BSD variants
• termui/v3 (gizak/termui) — Mature terminal UI framework providing grid layouts, widgets, and event handling for building interactive TUI dashboards
• drawille-go — Enables smooth, high-resolution line graphs in terminals using Unicode/Braille characters instead of ASCII blocks
• distatus/battery — Cross-platform battery status library for laptops; abstracts platform differences (sysfs on Linux, IOKit on macOS, etc.)

• Platform-specific widget implementations (mem_freebsd.go, proc_linux.go, temp_darwin.go) instead of single abstraction

  • Why: FreeBSD and Linux expose system metrics through different sysfs/procfs interfaces; a unified abstraction would require excessive conditional logic or performance overhead
  • Consequence: Increased code duplication (~3–4 versions per widget); requires testing on each OS; easier to optimize for each platform's API

• Fixed 1-second update interval in main loop instead of configurable refresh rate

  • Why: Simplicity and consistent CPU usage across devices; most system monitors
  • Consequence: undefined

Platform detection: src/logging/ uses build tags (arm64 vs others) — may hide unexpected behavior on uncommon archs. Colorscheme loading: expects ~/.config/gotop/ for custom schemes; XDG_CONFIG_HOME may override (see src/utils/xdg.go). Process killing: requires elevated privileges; dd keybind may silently fail without errors if permissions insufficient. No Windows support: termui/v3 on Windows may panic; explicitly not supported per README. Dependency pinning: go.mod pins old versions of gopsutil (2.18.11+incompatible) and termui (v3.0.0 from 2019); upgrading may break graph rendering or metric collection.

• Braille-art line graphs (Drawille) — gotop renders graphs using Unicode braille characters (src/termui/drawille-go/) to achieve smooth curves on fixed-size terminal cells; this is non-obvious and explains the jagged appearance vs. pixel graphics
• Process state buffering and delta calculation — CPU and memory widgets buffer multiple snapshots and compute deltas (src/widgets/cpu.go pattern); without this, metrics cannot be graphed over time in a low-res terminal
• TUI event loop and non-blocking I/O — gotop's main.go must handle keyboard/mouse input, system metric polling at configurable rates (-r flag), and terminal refresh without blocking; this is a concurrent event loop pattern specific to TUI applications
• Per-CPU vs. aggregate CPU metrics — The -p flag switches between showing one graph for all cores vs. one graph per core; gopsutil provides both via Percent(percpu=bool) but rendering strategy differs significantly
• XDG Base Directory specification — gotop loads custom colorschemes from ~/.config/gotop/ following XDG spec; src/utils/xdg.go handles this, making the app compatible with dotfile managers and multi-machine configs
• Platform-specific syscalls via build tags — src/logging/ and widgets use Go build tags to include/exclude platform-specific code (e.g., src/logging/logging_arm64.go); critical for supporting Linux, macOS, FreeBSD, OpenBSD with differing syscall availability
• Process grouping and hierarchies — The Tab keybind toggles process grouping (children under parent), but implementation relies on gopsutil's process parent tracking; understanding process tree traversal is key to debugging the feature

• xxxserxxx/gotop — The actively maintained fork of this project; users should migrate here for bug fixes and new features
• aksakalli/gtop — Original Node.js inspiration for gotop; predecessor that prompted this Go rewrite for better performance
• MrRio/vtop — Another Node.js system monitor that inspired gotop's design; shows the TUI-based monitoring trend
• gizak/termui — Core dependency providing TUI primitives (boxes, grids, widgets); understanding its API is essential for extending gotop
• shirou/gopsutil — System metric collection library used throughout gotop for CPU, memory, process, and disk data; any metric bugs likely originate here

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 unit tests for src/utils package functions

The src/utils directory contains critical utility functions (bytes.go, conversions.go, math.go) that handle data transformations and formatting for display. These functions lack test coverage, making refactoring risky and increasing the chance of bugs in memory/disk size formatting or unit conversions across different platforms. Adding tests would improve code quality and serve as documentation.

• [ ] Create src/utils/bytes_test.go with tests for byte conversion functions
• [ ] Create src/utils/conversions_test.go with tests for unit conversion logic
• [ ] Create src/utils/math_test.go with tests for mathematical operations
• [ ] Ensure tests cover edge cases (zero values, very large numbers, different unit scales)
• [ ] Run tests with go test ./src/utils/... and verify coverage

Add GitHub Actions workflow for multi-platform builds and testing

The repo currently uses Travis CI (.travis.yml) which is outdated/deprecated. The codebase supports Linux, FreeBSD, macOS, and Windows (planned), but there's no modern CI verifying builds work across these platforms. GitHub Actions would replace Travis, enable matrix testing across OS/Go versions, and provide artifact builds matching the ci/script.sh intent.

• [ ] Create .github/workflows/build.yml with matrix strategy for linux, macos, freebsd, windows
• [ ] Include Go version matrix (1.13+) to test compatibility
• [ ] Add steps to run go build and go test ./... for each platform combination
• [ ] Configure artifact uploads for successful binary builds
• [ ] Remove or deprecate .travis.yml file and update CI badge in README.md

Add widget-specific unit tests for src/widgets platform-specific files

The widgets directory has multiple platform-specific implementations (mem_freebsd.go, mem_other.go, proc_linux.go, proc_windows.go, temp_darwin.go, etc.) but no corresponding test files. These platform-specific code paths are impossible to verify on other systems without tests, leading to silent breakage. Tests would ensure cross-platform compatibility and catch regressions.

• [ ] Create src/widgets/mem_test.go with mock tests for platform-agnostic memory widget logic
• [ ] Create src/widgets/proc_test.go with tests for process parsing (reference proc_linux.go data structure)
• [ ] Create src/widgets/temp_test.go with tests for temperature reading logic
• [ ] Add build tags (e.g., //+build linux) to platform-specific test files where needed
• [ ] Run full test suite with go test ./src/widgets/... and verify coverage above 60%

• Add unit tests for src/utils/ functions (bytes.go, conversions.go, math.go) — currently no *_test.go files visible, making refactoring risky.
• Document the colorscheme format in CHANGELOG.md or README — currently only mentions template.go and default.json; new users cannot easily understand the color mappings without reading Go code.
• Add missing platform-specific logging for OpenBSD — README mentions 'works with some caveats' but src/logging/ has no logging_openbsd.go, leaving debug output path unclear for OpenBSD users.

This project presents significant security concerns. It is explicitly marked as 'NO LONGER MAINTAINED', meaning no security updates will be provided. The dependencies are severely outdated (some from 2018) and likely contain known vulnerabilities. The codebase includes platform-specific code (C, Windows, BSD) that may have incomplete testing and validation. This project should not be used in production environments. Users should migrate to the maintained fork at https://github.com/xxxserxxx/gotop. If the codebase must be used, a comprehensive security audit and dependency update would be required as a minimum.

• High · Outdated and Unmaintained Dependencies — go.mod, go.sum. The project uses several outdated dependencies with known vulnerabilities. Notable examples include: github.com/shirou/gopsutil v2.18.11+incompatible (released 2018), github.com/gizak/termui/v3 v3.0.0 (old version), and github.com/docopt/docopt.go v0.0.0-20180111231733 (2018). These dependencies may contain unpatched security vulnerabilities. The README explicitly states 'NO LONGER MAINTAINED', indicating no active security updates. Fix: Migrate to the maintained fork at https://github.com/xxxserxxx/gotop. If continuing maintenance is desired, audit and update all dependencies to their latest versions and establish a regular dependency update schedule.
• High · Project No Longer Maintained — README.md. The README clearly states 'NO LONGER MAINTAINED' and directs users to a fork. This means security vulnerabilities discovered in dependencies or the codebase itself will not be patched. The last commit and release dates indicate the project is abandoned. Fix: Use the maintained fork at https://github.com/xxxserxxx/gotop instead. Do not deploy this version in production environments where security updates are critical.
• Medium · Use of Indirect Dependencies — go.mod. The project has several indirect dependencies marked with '// indirect' comments (StackExchange/wmi, davecgh/go-spew, go-ole, mattn/go-runewidth, mitchellh/go-wordwrap, pmezard/go-difflib, shirou/w32, stretchr/testify, golang.org/x, howett.net/plist). These transitive dependencies are not directly controlled and may introduce vulnerabilities through their own dependency chains. Fix: Run 'go mod tidy' and 'go mod verify' to ensure dependency integrity. Consider using 'go mod audit' (if available) or third-party tools like Nancy or Trivy to scan for known vulnerabilities in transitive dependencies.
• Medium · Windows Support Incomplete — src/widgets/. The README states 'Windows support is planned' with only partial implementation (temp_windows.go, proc_windows.go, wmi dependency). This suggests incomplete testing and potential security issues on Windows platforms, such as insufficient error handling or unvalidated system calls. Fix: Complete Windows support with thorough testing, or clearly document Windows as unsupported. If Windows is targeted, ensure all system calls are properly validated and error-handled.
• Low · Missing Input Validation in Command-Line Arguments — main.go, github.com/docopt/docopt.go. The project uses docopt for CLI parsing. Without reviewing the actual main.go implementation, there's a risk of improper input validation when parsing user-supplied arguments that might be passed to system commands or file operations. Fix: Ensure all command-line arguments are properly validated and sanitized before use in system calls, file operations, or other sensitive operations. Use allowlists where possible.
• Low · C Code Inclusion Without Review — src/widgets/include/smc.c, src/widgets/include/smc.h. The project includes C code (src/widgets/include/smc.c, smc.h) for system monitoring. C code is prone to memory safety vulnerabilities such as buffer overflows, use-after-free, and integer overflows if not carefully written. Fix: Conduct a security audit of the C code, especially focusing on buffer operations, memory allocation, and bounds checking. Consider using static analysis tools for C code (clang-analyzer, cppcheck). Ensure it's only used on macOS where intended.

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.