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/Chris911/iStats 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

• 9 active contributors
• MIT licensed
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 58% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

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

What it runs against: a local clone of Chris911/iStats — 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 Chris911/iStats | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 1226 days ago | Catches sudden abandonment since generation |

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

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

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

iStats is a Ruby CLI gem that exposes macOS system metrics—CPU temperature, fan speeds, battery health, and raw SMC sensor data—via command-line commands and sparkline graphs. It wraps native C code (in ext/osx_stats/smc.c) that communicates directly with the System Management Controller to read hardware telemetry without dependencies on external APIs. Modular Ruby structure: lib/iStats/ contains domain logic split by concern (battery.rb, cpu.rb, fan.rb, smc.rb) with a command dispatcher (command.rb); native C extension in ext/osx_stats/ handles SMC communication; bin/istats is the CLI entry point; utilities and formatters (color.rb, printer.rb, symbols.rb) handle output rendering.

macOS users and system administrators who need to monitor hardware health from the terminal; DevOps engineers integrating machine stats into monitoring systems (Zabbix support included); developers building system dashboards or CLI tools that need reliable hardware metrics without GUI tools.

Active but minimal-scope project with ~32KB Ruby and ~17KB C code. No visible test suite in the file list, no CI configuration mentioned, and README shows basic command documentation without examples of recent commits or release cadence. Likely production-ready for its narrow use case but lacks test coverage.

Single-maintainer pattern (Chris911) visible in GitHub username; direct SMC register access in C code is macOS-version fragile and may break on future OS updates; no public test suite means regressions in hardware data parsing are undetected; gem has minimal dependencies but tight coupling to undocumented Apple hardware interfaces.

No recent activity indicators visible in file list; based on README structure, the project appears mature and stable with no urgent development signals (no TODO sections, no beta features). Integrations folder shows Zabbix template suggesting enterprise monitoring use.

git clone https://github.com/Chris911/iStats.git
cd iStats
gem install bundler
bundle install
bundle exec rake build
sudo gem install pkg/iStats-*.gem

Daily commands: After install: istats all (show all stats), istats cpu temp (CPU temperature), istats fan speed, istats battery, istats scan (raw SMC sensor dump). Pass --fahrenheit for Fahrenheit, --no-graphs to disable sparklines.

• ext/osx_stats/smc.c: Core SMC kernel communication—reads raw hardware registers; any macOS version incompatibility surfaces here
• lib/iStats/smc.rb: Ruby wrapper around C extension; parses SMC key names and temperature sensor data into user-facing metrics
• lib/iStats/command.rb: Command router and dispatcher; all CLI subcommand logic flows through here (all, cpu, fan, battery, scan, enable, disable)
• lib/iStats/battery.rb: Battery stat aggregator; demonstrates the pattern for querying multiple SMC keys and presenting them as a unit
• bin/istats: CLI entry point; minimal wrapper that parses argv and delegates to lib/iStats/command.rb
• lib/iStats/printer.rb: Output formatter for sparklines, graphs, and aligned labels; handles --no-graphs and --value-only flags

New stat type: add file in lib/iStats/ (e.g., lib/iStats/memory.rb) following battery.rb pattern, then register in lib/iStats/command.rb route handler. New SMC keys: scan with istats scan, enable with istats enable [key], add parsing logic to lib/iStats/smc.rb. Output tweaks: edit lib/iStats/printer.rb and lib/iStats/color.rb.

C extension requires macOS SDK and Xcode toolchain to build (extconf.rb); older OS X versions may need ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future during gem install per README; SMC register addresses are undocumented Apple internals—compatibility with newer M1/M2 Macs may require smc.c updates; bin/istats likely requires root/sudo for some sensor reads due to kernel SMC access.

• System Management Controller (SMC) — iStats' entire purpose is exposing SMC data; understanding SMC is required to add new sensors or debug hardware-specific issues
• Kernel Extension / Privileged Access — SMC reads in smc.c require kernel-level privileges; contributors must understand why some commands need sudo and how sandboxing affects capability
• Native C Extension in Ruby (FFI / Native gems) — iStats bridges Ruby and C via extconf.rb; contributors modifying hardware access must understand Ruby gem C extension patterns and compilation
• ANSI Color Codes & Terminal Escape Sequences — lib/iStats/color.rb renders colored output; understanding ANSI codes is needed to enhance terminal UI or add new output modes
• Sparkline graphs for CLI — iStats renders ASCII sparklines (▁▂▃▄▅▆▇█) to show metric trends in the terminal; lib/iStats/printer.rb implements this visualization pattern
• Command-line Argument Parsing in Ruby — lib/iStats/command.rb manually parses argv; understanding CLI UX patterns helps extend subcommands without breaking existing usage

• exelban/stats — Active macOS stats monitoring tool written in Swift; overlaps on CPU/battery/fan metrics but offers menu bar widget UI vs. iStats' CLI-only approach
• ptg/MacFanControl — Older SMC-based fan controller for macOS; shares smc.c reverse-engineering knowledge and SMC register definitions
• zabbix/zabbix — Zabbix monitoring platform; iStats explicitly integrates with it via integrations/zbx-istats-template.xml and --zabbix scan output
• Homebrew/homebrew-core — iStats is distributed via Homebrew; Homebrew formulae depend on this repo's gem releases and build infrastructure

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 lib/iStats/smc.rb

The SMC (System Management Controller) module is critical for reading hardware stats but appears to have no unit tests. This is a high-risk module that bridges Ruby and C code (ext/osx_stats/smc.c). Adding tests would catch regressions when macOS versions change and improve maintainability. Tests should cover SMC key lookups, temperature/fan data parsing, and error handling.

• [ ] Create spec/iStats/smc_spec.rb with test cases for SMC initialization
• [ ] Add tests for temperature and fan speed reading methods in lib/iStats/smc.rb
• [ ] Add tests for error cases (e.g., missing SMC keys, invalid hardware)
• [ ] Verify tests run with Rake test task (Rakefile)

Add GitHub Actions CI workflow for multi-macOS version testing

The README mentions compatibility issues with older OS X versions requiring special ARCHFLAGS. There is no CI configuration visible (.github/workflows/). A GitHub Actions workflow would automatically test builds on multiple macOS versions (11, 12, 13, etc.) and Ruby versions, catching incompatibilities early and reducing user install failures.

• [ ] Create .github/workflows/ci.yml with matrix testing for macOS 11, 12, 13, 14
• [ ] Add Ruby version matrix (3.0, 3.1, 3.2, 3.3) to test compatibility
• [ ] Include gem install, spec runs, and basic istats command execution
• [ ] Test the ARCHFLAGS workaround mentioned in README

Extract and document public API in lib/iStats.rb with YARD documentation

The main lib/iStats.rb file lacks formal documentation/docstrings. Contributors and users cannot easily understand which methods are public API vs internal. Adding YARD documentation with @param, @return, @example tags would clarify the module interface and make it easier for other gems to integrate with iStats.

• [ ] Add YARD docstrings to all public methods in lib/iStats.rb
• [ ] Document the module-level methods (cpu, battery, fan, etc.) with examples
• [ ] Add @return type documentation for each method return value
• [ ] Generate YARD docs with rake yard and verify output is clear

• Add RSpec test suite for lib/iStats/cpu.rb, lib/iStats/battery.rb, and lib/iStats/fan.rb—currently no test/ directory exists and core stat parsing is untested; mock SMC responses to validate temperature unit conversions and threshold logic.
• Document SMC sensor key mappings: create a SENSORS.md file in root that lists all keys found by istats scan --zabbix and their meanings; requires manual testing on multiple Mac models to discover which keys are universal vs. model-specific.
• Extend lib/iStats/printer.rb to support JSON output format (add --json flag)—currently only ASCII/ANSI output; enables easier integration with external monitoring tools beyond Zabbix.

The iStats project is a native macOS system monitoring tool with moderate security concerns. The primary risk is the C extension (smc.c) which handles low-level system access and is susceptible to memory safety vulnerabilities. Input validation practices in CLI parsing need review. Without visibility into the dependency tree, transitive dependency vulnerabilities cannot be assessed. The project lacks evidence of security testing practices. Recommend conducting security code review of C extensions, implementing comprehensive input validation, maintaining dependency audits, and establishing secure development practices.

• High · Native C Extension with Potential Memory Safety Issues — ext/osx_stats/smc.c, ext/osx_stats/smc.h. The codebase includes native C extensions (ext/osx_stats/smc.c) for accessing System Management Controller data. C code is prone to memory safety vulnerabilities such as buffer overflows, use-after-free, and improper memory management. Without access to the actual C code, there's elevated risk of exploitation. Fix: 1. Conduct thorough code review of C extension for memory safety issues. 2. Use static analysis tools (clang-analyzer, cppcheck). 3. Implement bounds checking and safe memory operations. 4. Consider using safer alternatives or sandboxing the C code. 5. Implement proper error handling.
• Medium · Insufficient Input Validation in CLI Command Parsing — bin/istats, lib/iStats/command.rb. The bin/istats executable and lib/iStats/command.rb file suggest command-line argument parsing. Without input validation, there may be risks of command injection or argument parsing vulnerabilities if user input is passed to system commands. Fix: 1. Implement strict input validation for all CLI arguments. 2. Use allowlist/whitelist approach for valid commands. 3. Avoid passing user input directly to system calls. 4. Use proper escaping/quoting when necessary. 5. Consider using well-tested CLI parsing libraries.
• Medium · Missing Dependencies Documentation — Gemfile, Gemfile.lock (if exists). No Gemfile or dependency lock file content was provided. Ruby gems can contain vulnerabilities. Without visibility into dependencies, it's impossible to assess known CVEs in third-party libraries. Fix: 1. Maintain and commit Gemfile.lock for reproducible installs. 2. Regularly audit dependencies using bundle audit. 3. Keep gems updated to latest secure versions. 4. Document all external dependencies. 5. Use tools like Dependabot for automated vulnerability scanning.
• Low · Potential Information Disclosure in Error Messages — lib/iStats/printer.rb, lib/iStats/utils.rb. System stats tools may expose sensitive information through error messages or verbose output (CPU details, thermal data, battery health). While generally not sensitive, detailed hardware information could aid reconnaissance. Fix: 1. Sanitize error messages to avoid exposing sensitive system details. 2. Implement appropriate logging levels. 3. Consider access controls if used in shared environments. 4. Review what information is exposed in output.
• Low · Hardcoded Configuration Paths — lib/iStats/settings.rb. The settings.rb and config-related files may contain hardcoded paths or default values that could be problematic in restricted environments or containerized deployments. Fix: 1. Use environment variables for configuration paths. 2. Avoid hardcoding system-specific paths. 3. Implement proper configuration hierarchy (env vars > config files > defaults). 4. Document configuration options.

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.