GO — Healthy across the board

• Last commit today
• 10 active contributors
• Distributed ownership (top contributor 43% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

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

gopsutil is a pure-Go port of Python's psutil library that provides cross-platform system and process metrics without requiring cgo. It exposes CPU, memory, disk, network, and process information across Linux, Windows, macOS, FreeBSD, OpenBSD, Solaris, and other Unix variants through a unified Go API. Single-package monorepo structure: top-level directories for each subsystem (cpu/, mem/, disk/, net/, process/, host/, etc.), each with platform-specific implementations (cpu_linux.go, cpu_darwin.go, cpu_windows.go, etc.). Platform fallback pattern: most packages have both specific implementations and fallback versions (cpu_fallback.go). Common utilities in common/env.go handle HOST_PROC, HOST_SYS environment variables for containerized/chroot scenarios.

Go developers building system monitoring tools, infrastructure dashboards, container orchestration platforms, and DevOps utilities who need portable access to OS-level metrics without C dependencies or external binaries.

Production-ready and actively maintained. The project uses calendar versioning (v4.24.04 format), has comprehensive CI/CD via GitHub Actions (build_test.yml, lint.yml, test.yml workflows), extensive test coverage across platforms (cpu_linux_test.go, cpu_freebsd_test.go, etc.), and was last tagged in 2024. The migration to v4 indicates deliberate API evolution rather than stagnation.

Low-to-moderate risk. Dependencies are minimal and stable (ebitengine/purego, tklauser/go-sysconf, yusufpapurcu/wmi), but the project appears to be primarily maintained by shirou with community contributions, creating single-maintainer risk. Platform-specific code paths (21 CPU variants alone) mean bugs in less-tested architectures (Plan9, Solaris, DragonFly) may go undetected. Breaking changes between major versions require migration planning.

Active maintenance focused on v4 stabilization and cross-platform correctness. Recent work includes CI improvements (dependabot.yml, sbom_generator.yml workflows), platform-specific optimizations (cpu_darwin_arm64.go, cpu_darwin_fallback.go additions), and likely addressing migration issues post-v4 release. No major new features visible, but steady bug fixes and test coverage improvements.

git clone https://github.com/shirou/gopsutil.git
cd gopsutil
go mod download
make test

The Makefile provides targets for testing. Verify with: go run -v ./... to build all packages.

Daily commands: This is a library, not a runnable application. Test with: go test ./... (runs all platform-specific tests). See README for usage example: import github.com/shirou/gopsutil/v4/mem, then call mem.VirtualMemory() or mem.VirtualMemoryWithContext(ctx).

• cpu/cpu.go — Core CPU info interface and platform-agnostic entry point; all platform implementations depend on this abstraction
• disk/disk.go — Core disk I/O and usage interface; foundational abstraction for all platform-specific disk implementations
• common/env.go — Shared environment utilities and common constants used across all platform-specific modules
• go.mod — Declares v4 module and all critical dependencies (purego, go-sysconf, wmi, golang.org/x/sys) required for cross-platform functionality
• .golangci.yml — Linting rules and code quality gates that enforce consistency across the codebase
• README.md — Project overview, versioning strategy, and architectural scope; essential context for understanding design intent
• Makefile — Build and test automation for multi-platform support; documents the build process

Add a new psutil metric (e.g., memory info)

1. Create platform-agnostic interface in new file memory/memory.go with public functions (e.g., VirtualMemory(), SwapMemory()) (memory/memory.go)
2. Implement Linux-specific logic by reading /proc/meminfo (memory/memory_linux.go)
3. Implement macOS logic using sysctl syscalls (memory/memory_darwin.go)
4. Implement Windows logic using WMI queries (memory/memory_windows.go)
5. Add unit tests with testdata fixtures in memory/testdata/ and memory/memory_test.go (memory/memory_test.go)
6. Update README.md to list new metric and test with 'make test' (README.md)

Add support for a new operating system (e.g., NetBSD disk support)

1. Create disk/disk_netbsd.go with DiskUsage() and IOCounters() implementations using OS-specific syscalls/APIs (disk/disk_netbsd.go)
2. If architecture-specific variants needed (e.g., ARM), create disk/disk_netbsd_arm.go (disk/disk_netbsd_arm.go)
3. Add testdata fixtures in disk/testdata/netbsd/ with sample /proc or /sys files (disk/testdata/netbsd/sample_mount_output.txt)
4. Add OS detection logic to disk/disk.go to route to NetBSD implementation (disk/disk.go)
5. Run 'make test' and verify .golangci.yml linting passes (Makefile)

Fix a cross-platform compatibility issue

1. Identify which platform modules are affected (e.g., cpu_linux.go vs cpu_darwin.go) and write a failing test case (cpu/cpu_test.go)
2. Update the affected platform-specific implementation(s) to handle edge case (cpu/cpu_linux.go)
3. If the issue affects the public API, update the platform-agnostic interface to document behavior (cpu/cpu.go)
4. Run tests: 'go test ./...' to validate fix on current platform (Makefile)
5. Verify CI passes across all platforms in .github/workflows/test.yml (.github/workflows/test.yml)

• CGO (C bindings) + purego (pure Go syscalls) — Allows direct access to platform-specific system calls (sysctl on BSD, WMI on Windows, /proc on Linux) with optional pure-Go fallbacks for environments where CGO is unavailable
• golang.org/x/sys — Cross-platform syscall bindings for Unix-like systems; abstracts low-level kernel calls (open, read, ioctl) needed for /proc parsing and system information retrieval
• WMI (go-ole wrapper) for Windows — Native Windows API for querying hardware and system metrics; standard Windows system introspection mechanism
• Build tags (//go:build) for conditional compilation — Enables per-platform code paths without runtime checks; reduces binary size and allows OS-specific optimizations

• Separate platform-specific files (cpu_linux.go, cpu_darwin.go, etc.) instead of single file with runtime OS checks

  • Why: Cleaner code organization, easier to maintain platform-specific logic, and enables compile-time elimination of unused code via build tags
  • Consequence: Requires testing on each platform to validate implementations; duplication of boilerplate across similar platforms

• Optional CGO support with pure-Go fallbacks

  • Why: Maximizes compatibility in restricted environments (containerized, WASM) while allowing performance optimizations where CGO is available
  • Consequence: Code complexity increases with dual implementation paths; fallback implementations may be slower or less accurate

• Direct parsing of /proc and /sys files on Linux instead of wrapping procfs library

  • Why: Minimal dependencies; gives full control over parsing logic and error handling
  • Consequence: Brittle to kernel format changes; requires test fixtures to validate parsing

• No caching at library level—caller responsible

  • Why: Simpler API; avoids cache invalidation issues and gives applications control over refresh rates
  • Consequence: High-frequency callers may incur repeated system call overhead; applications must implement their own caching if needed

• Real-time performance monitoring (not designed for sub-millisecond latency)
• Process lifecycle management (does not start/stop/kill processes)
• Persistent metrics storage (returns point-in-time snapshots only)
• Windows Vista or earlier support (targets modern Windows only)
• Plan 9 feature parity (limited Plan 9 implementations included as experimental)

1. Context-based overrides are first-priority: if you use common.EnvKey context with EnvMap, it overrides environment variables—test both paths. 2) Platform-specific test failures don't block CI: many platform-specific tests skip on unsupported OS (use runtime.GOOS checks in tests). 3) cgo is explicitly avoided: some metrics may use fallback implementations with reduced accuracy (see cpu_fallback.go); know which platform uses which implementation. 4) No Windows Event Log access: process creation/exit detection unavailable on Windows; use polling instead. 5) Container environments: /proc paths differ; must use HOST_PROC env var—tests may fail in Docker without it set.

• Platform-specific build tags (+build directives) — gopsutil uses Go's build constraints extensively (cpu_linux.go vs cpu_darwin.go) to compile only relevant code per OS; understanding //go:build is essential for adding cross-platform support
• /proc and /sys filesystem parsing — Linux metrics come from /proc/stat, /proc/cpuinfo, /proc/meminfo as text files; gopsutil manually parses these to extract CPU/memory data without cgo
• sysctl(3) interface — BSD variants (FreeBSD, OpenBSD, NetBSD) use sysctl for OS metrics instead of /proc; gopsutil wraps sysctl calls via golang.org/x/sys/unix
• WMI (Windows Management Instrumentation) — Windows metrics come via WMI queries (Win32_Processor, Win32_LogicalMemoryConfiguration); gopsutil uses yusufpapurcu/wmi to avoid cgo while accessing Windows APIs
• Context-based dependency injection (context.WithValue + common.EnvKey) — gopsutil allows runtime override of system paths (/proc, /sys, /etc) via context for containerized/test environments; essential for multi-environment deployments
• CPU affinity and NUMA topology — CPU functions report per-core metrics and logical/physical core counts; understanding NUMA (Non-Uniform Memory Access) helps interpret multi-socket systems correctly
• Process namespace isolation (PID, mount, net namespaces) — In containers, processes see isolated namespaces; gopsutil's process module must handle namespace-aware PID translation and resource accounting

• giampaolo/psutil — Original Python library that gopsutil ports; reference implementation for API design and cross-platform metric definitions
• containerd/containerd — Major consumer of gopsutil for container runtime metrics and resource tracking
• prometheus/client_golang — Common pairing: gopsutil feeds system metrics into Prometheus exporters for monitoring
• elastic/beats — Uses gopsutil for system module to collect host-level telemetry in Elastic Stack deployments

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 cpu/cpu_linux.go with cgroup v2 support

The cpu package has platform-specific implementations but cpu_linux.go lacks dedicated test coverage for cgroup v2 (unified hierarchy) which is now standard in modern Linux distributions. This would ensure compatibility with containerized environments and catch regressions when parsing CPU metrics from /sys/fs/cgroup/cpuset.cpus and related v2 interfaces.

• [ ] Create cpu/cpu_linux_cgroupv2_test.go with mock cgroup v2 directory structures in cpu/testdata/linux/
• [ ] Add test cases for parsing CPU limits and affinity from unified cgroup hierarchy
• [ ] Test fallback behavior when cgroup v2 files are unavailable but cgroup v1 exists
• [ ] Verify tests pass on Linux in CI pipeline (cpu/testdata/linux/ already has 1037, 1958, 424 fixtures to extend)

Add Windows-specific memory tests for virtual memory calculation edge cases

The project has comprehensive platform-specific memory implementations but cpu/cpu_windows_test.go shows the test pattern. The memory package likely lacks similar Windows test coverage for edge cases like when PagingFile metrics are unavailable or when AvailableBytes differs significantly from WorkingSetSize. This is critical for Windows monitoring reliability.

• [ ] Review memory/memory_windows.go for WMI queries and Win32_PerfFormattedData_PerfOS_Memory class usage
• [ ] Create memory/memory_windows_test.go following the pattern in cpu/cpu_windows_test.go
• [ ] Add test fixtures in memory/testdata/windows/ for scenarios: insufficient permissions, disabled pagefile, memory pressure
• [ ] Test GetVirtualMemory() error handling and fallback behavior

Add integration tests for process/process_*.go across all supported platforms

The repo has extensive platform-specific process implementations (process_linux.go, process_darwin.go, process_windows.go, etc.) but the file structure shows no dedicated testdata directory for process package like exists for cpu (cpu/testdata/). This gap means process-specific logic like /proc parsing, sysctl queries, and WMI calls lack regression protection.

• [ ] Create process/testdata/ directory mirroring cpu/testdata/ structure with platform subdirectories
• [ ] Add mock /proc/ filesystem snapshots in process/testdata/linux/ for various process states (running, zombie, sleeping)
• [ ] Create process/process_test.go with parameterized tests using testdata fixtures for GetProcesses(), Process.Name(), Process.Cmdline()
• [ ] Add platform-specific test files: process/process_linux_test.go, process/process_darwin_test.go, process/process_windows_test.go

• Add missing test coverage for cpu_openbsd.go and cpu_netbsd.go—these files have implementations but no dedicated test files like cpu_linux_test.go; write platform-specific unit tests that mock sysctl calls.
• Implement host.Uptime() for Plan9 in host/host_plan9.go—the file exists but likely has a stub; check host/host.go interface and port the uptime calculation from another platform.
• Document the context.WithValue() pattern with a concrete example in README.md—the feature exists (mentioned in doc snippet) but has no runnable example like the basic mem.VirtualMemory() usage shown.

The gopsutil repository demonstrates generally good security practices with CI/CD pipelines, dependency management, and structured architecture. However, there are areas for improvement: (1) The Go version specification appears non-standard and should be updated to a stable release; (2) Security scanning and automated vulnerability detection should be more explicitly documented; (3) CGO usage requires additional security validation; (4) Dependency pinning and supply chain security could be strengthened. No hardcoded secrets, injection vulnerabilities, or critical misconfigurations were detected in the visible file structure. The project would benefit from SAST integration, dependency scanning, and formal vulnerability disclosure procedures.

• Medium · Outdated Go Version — go.mod. The go.mod file specifies Go 1.24.0, which is a pre-release/future version. Production code should use stable, released Go versions. This may indicate version targeting issues or development environment inconsistencies. Fix: Use a stable, released Go version (e.g., 1.23.x or the latest stable release). Update go.mod to reflect a production-ready Go version.
• Low · Missing Dependency Lock File Verification — go.sum (missing). The go.sum file is not provided in the analysis. Without it, there's no way to verify the integrity of dependencies against potential tampering or supply chain attacks. Fix: Ensure go.sum is present in version control and regularly verify it with 'go mod verify' to detect any tampering or checksum mismatches.
• Low · Dependency Version Ranges Not Fully Specified — go.mod. Several dependencies use imprecise version constraints (e.g., 'github.com/ebitengine/purego v0.10.0'). While not critical, this can lead to inconsistent builds if minor/patch versions introduce vulnerabilities. Fix: Consider using go.mod's module version pinning or implementing automated dependency scanning. Review and test dependency updates regularly using tools like 'go list -u -m all'.
• Low · No Evidence of Security Policy Enforcement — .github/SECURITY.md. While a SECURITY.md file exists in .github/, there's no visibility into its contents. Best practices should include security policy documentation, vulnerability disclosure process, and security scanning in CI/CD. Fix: Ensure SECURITY.md contains: vulnerability disclosure process, security contact information, supported versions, and security best practices. Enable automated security scanning in GitHub Actions (SAST, dependency scanning).
• Low · Missing SBOM and Supply Chain Security Controls — .github/workflows/sbom_generator.yml. While an SBOM generator workflow exists, there's no evidence of signed releases, provenance verification, or artifact attestation in the visible CI/CD configuration. Fix: Implement signed releases using cosign or similar tools, generate and publish SBOMs, and enable GitHub's artifact attestation for released binaries.
• Low · CGO Usage in Architecture-Specific Files — cpu/ (various _cgo.go files). Files like 'cpu_aix_cgo.go' and 'cpu_aix_nocgo.go' indicate CGO usage. CGO can introduce security risks through C bindings if not carefully validated. Fix: Audit all CGO code for buffer overflows, unsafe memory operations, and input validation. Consider enabling SafeGo linting rules. Document CGO security assumptions.

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

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

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "cpu/cpu.go" \\
  && ok "cpu/cpu.go" \\
  || miss "missing critical file: cpu/cpu.go"
test -f "disk/disk.go" \\
  && ok "disk/disk.go" \\
  || miss "missing critical file: disk/disk.go"
test -f "common/env.go" \\
  && ok "common/env.go" \\
  || miss "missing critical file: common/env.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f ".golangci.yml" \\
  && ok ".golangci.yml" \\
  || miss "missing critical file: .golangci.yml"

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