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/brndnmtthws/conky 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 1d ago
• 22+ active contributors
• Distributed ownership (top contributor 47% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-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 brndnmtthws/conky repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/brndnmtthws/conky.

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

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.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 ".github/workflows/build-and-test-linux.yaml" \\
  && ok ".github/workflows/build-and-test-linux.yaml" \\
  || miss "missing critical file: .github/workflows/build-and-test-linux.yaml"
test -f "3rdparty/Vc/CMakeLists.txt" \\
  && ok "3rdparty/Vc/CMakeLists.txt" \\
  || miss "missing critical file: 3rdparty/Vc/CMakeLists.txt"
test -f ".github/instructions/cpp-review.instructions.md" \\
  && ok ".github/instructions/cpp-review.instructions.md" \\
  || miss "missing critical file: .github/instructions/cpp-review.instructions.md"
test -f ".clang-format" \\
  && ok ".clang-format" \\
  || miss "missing critical file: .clang-format"
test -f ".clang-tidy" \\
  && ok ".clang-tidy" \\
  || miss "missing critical file: .clang-tidy"

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

Conky is a lightweight, highly configurable system monitor that renders real-time OS metrics (CPU, memory, network, disk, process stats) and custom widgets directly onto your desktop via X11, Wayland, macOS, or output modes (console, file, HTTP). It supports Lua scripting for custom data sources and Cairo/Imlib2 for arbitrary drawing, making it a minimal-footprint alternative to heavy panel-based system monitors. Monolithic codebase with platform-agnostic core logic and pluggable display backends: src/ contains main C++ engine, lua/ subdirectory for Lua bindings, 3rdparty/Vc/ vendored SIMD library. .github/workflows/ defines build matrices for Linux, macOS, Docker, AppImage. CMakeLists.txt at root orchestrates compilation for all targets.

Linux/BSD desktop power users and system administrators who want customizable, low-resource system monitoring without bloated desktop environments; developers extending monitoring capabilities via Lua scripts or contributing C++/CMake improvements to cross-platform display backends.

Production-ready and actively maintained. The codebase is substantial (~2.4M lines of C++, multi-decade history), has comprehensive CI/CD across Linux/macOS/Docker (.github/workflows/), and supports 8+ Unix-like platforms. Recent work on Wayland support and web output modes indicates ongoing development, though the project appears maintainer-driven rather than highly team-staffed.

Single-maintainer risk is moderate (brndnmtthws appears to be primary steward). Dependency surface includes Vc SIMD library (3rdparty/Vc/), Cairo, Imlib2, and Lua, which require careful version management across platforms. No obvious red flags in file structure, but multi-platform support (X11, Wayland, macOS, BSD) means platform-specific bugs can hide in display backend code. Last concrete signal unclear from file list alone.

Active work on Wayland support (noted in README as 'with caveats'), HTTP output mode expansion, and build infrastructure improvements (sccache setup in .github/scripts/setup-sccache.sh, CodeQL security scanning). Docker/AppImage publishing is automated in CI.

git clone https://github.com/brndnmtthws/conky.git
cd conky
mkdir build && cd build
cmake ..
make
./conky

See CMakeLists.txt for platform-specific dependencies; .envrc hints at Nix development environment support.

Daily commands: After build: ./conky (no config file = default minimal output) or conky -c ~/.conkyrc with user config. For development, run cmake -DCMAKE_BUILD_TYPE=Debug .. then make in build/ directory. Docker: docker run brndnmtthws/conky.

• .github/workflows/build-and-test-linux.yaml — Primary CI/CD pipeline for Linux builds; defines how the project is compiled, tested, and validated on the main platform
• 3rdparty/Vc/CMakeLists.txt — SIMD vectorization library (Vc) integration; critical for performance-sensitive monitoring calculations across CPU architectures
• .github/instructions/cpp-review.instructions.md — Code review standards and C++ conventions for this project; mandatory reference for all code contributions
• .clang-format — Enforced code formatting rules across the entire C++ codebase; ensures consistency in all contributions
• .clang-tidy — Static analysis configuration for catching common C++ pitfalls early; defines linting baseline for PR acceptance
• .editorconfig — Cross-editor configuration for indentation and whitespace rules; prevents formatting disputes in PRs
• .github/labeler.yml — Automated PR labeling rules that route contributions to appropriate maintainers and track issue categories

Add a new system monitoring widget/plugin

1. Ensure C++ implementation follows .clang-format rules and passes .clang-tidy checks (.clang-format)
2. If the widget requires high-performance vector calculations, leverage 3rdparty/Vc SIMD library (3rdparty/Vc/CMakeLists.txt)
3. Update CMake build configuration to register the new widget (3rdparty/CMakeLists.txt)
4. Verify the implementation adheres to C++ code review checklist (.github/instructions/cpp-review.instructions.md)
5. Submit PR and ensure it passes Linux, macOS, Docker, and AppImage build workflows (.github/workflows/build-and-test-linux.yaml)

Update the build system or add a new platform target

1. Review CMake best practices in the review instructions (.github/instructions/cmake-review.instructions.md)
2. Modify or add workflow YAML for the target platform (.github/workflows/build-and-test-linux.yaml)
3. Update third-party dependency configuration if needed (3rdparty/CMakeLists.txt)
4. Ensure build scripts remain POSIX-compliant (.github/scripts/docker-build.bash)

Improve code quality or add linting rules

1. Modify clang-tidy checks and severity levels (.clang-tidy)
2. Update clang-format rules if style enforcement needed (.clang-format)
3. Add guidance to the C++ code review checklist (.github/instructions/cpp-review.instructions.md)
4. Run full CI suite to ensure no regressions across platforms (.github/workflows/build-and-test-linux.yaml)

Prepare a release or update distribution targets

1. Update release notes template with new features/fixes (.github/release.yml)
2. Verify AppImage build pipeline succeeds (.github/workflows/publish-appimage.yml)
3. Confirm Docker build and publish workflow is ready (.github/workflows/docker.yaml)
4. Test all platform builds (Linux, macOS) complete successfully (.github/workflows/build-and-test-linux.yaml)

• C++ with CMake — Lightweight, cross-platform system monitor requiring high performance and low memory footprint on X11, Wayland, macOS, and console targets
• Vc SIMD Library (3rdparty) — Vectorized math operations for CPU-efficient data collection and processing across x86/ARM architectures
• GitHub Actions CI/CD — Multi-platform automated builds and testing (Linux, macOS, Docker, AppImage, Nix) with sccache for performance
• Clang-Format & Clang-Tidy — Enforced code consistency and static analysis to catch bugs and style issues before merge
• Docker & AppImage — Distribution packaging for portability across Linux distributions without dependency hell

• Vendored Vc SIMD library vs. system package

  • Why: Ensures consistent performance optimizations and compatible SIMD support across all target architectures
  • Consequence: Slightly larger codebase (3rdparty) but eliminates environment-specific build failures

• Strict clang-format & clang-tidy enforcement

  • Why: Maintains code quality and consistency across distributed contributors
  • Consequence: Developer friction during local iteration; requires IDE integration or pre-commit hooks

• Multi-platform CI (Linux, macOS, Docker, AppImage, Nix) vs. single-target

  • Why: Conky runs on X, Wayland, macOS, console, and HTTP—each requires validation
  • Consequence: Longer CI times (~10+ min) and maintenance burden for platform-specific workflows

• Shallow distribution (GitHub releases + Docker Hub) vs. package managers

  • Why: Faster iteration and direct user control over versions
  • Consequence: Users must manually install or rely on third-party package repos

• Not a real-time kernel profiler or advanced system tracer—lightweight monitoring only
• Not a GUI application in the traditional sense—desktop widget/status bar focus
• Does not handle user authentication or multi-user isolation
• Not a data persistence or time-series database—in-memory current-state monitoring only
• Does not provide remote monitoring over untrusted networks (HTTP output is for local/trusted use)

CMake version sensitivity: uses modern CMake features; older toolchains may fail silently. Platform-specific code paths: X11 vs. Wayland selection at compile-time via CMake flags; testing on only one display server can mask bugs. Lua version lock: expects Lua 5.1+; breaking ABI between Lua major versions. sccache caching: .github/scripts/setup-sccache.sh enables caching but requires S3-compatible storage in CI; local rebuilds won't benefit. Display backend initialization order: Wayland fallback to X11 can mask permission issues; check DISPLAY and WAYLAND_DISPLAY env vars carefully.

• X11 Window Properties & Atoms — Conky uses X11 atoms to embed windows on desktops and handle window manager hints; understanding _NET_WM_WINDOW_TYPE, _NET_WM_STRUT, and XSelectInput is essential for display backend code
• Wayland Protocol & Output Buffers — Wayland support in Conky requires understanding wl_surface, wl_shell, and buffer swapping; fundamentally different from X11's drawable model and explains 'with caveats' in README
• /proc and /sys Filesystem (sysfs) — Conky's metric collection relies entirely on parsing /proc/stat, /proc/meminfo, /proc/net/dev, /sys/class/ for CPU, memory, network stats; understanding procfs format is critical for adding new metrics
• Cairo Graphics Context & Vector Drawing — Conky exposes Cairo to Lua for arbitrary widget drawing; understanding cairo_t context, path operations, and matrix transforms is required for custom gauge/chart Lua scripts
• SIMD Vectorization (AVX/SSE) — Vendored Vc library (3rdparty/Vc/) enables vectorized CPU stat calculations for performance; understanding aligned_load, simd_cast is useful for optimizing metric aggregation
• Lua C API & Binding Patterns — lua/lua.cpp implements the Lua FFI to Conky objects; understanding lua_pushvalue, lua_setglobal, userdata metatables is essential for extending or debugging Lua script integration
• CMake Cross-Platform Toolchain Configuration — CMakeLists.txt orchestrates builds across Linux, BSD, macOS with platform-specific flags and optional dependency detection; understanding find_package(), set_target_properties() is critical for adding new platforms or optional features

• torvalds/linux — Not a competitor, but Conky relies on /proc and /sys filesystem APIs for metric collection; useful for understanding stat sources
• polybar/polybar — Modern alternative status bar for X11/Wayland; overlapping use case (desktop monitoring) but heavier, panel-based architecture vs. Conky's freeform window approach
• z3bra/awesomewm — Tiling WM with Lua scripting; often paired with Conky for desktop stats, shares Lua ecosystem and X11 backend knowledge
• jarun/bashtop — Terminal-based system monitor (alternative to Conky's GUI); overlapping metric collection logic but different rendering backend (ncurses vs. Cairo)
• cairo/cairo — Core graphics library vendored and used heavily in Conky for arbitrary widget rendering; essential dependency for understanding display pipeline

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 CodeQL configuration for C++ SAST analysis

The repo has a codeql.yml workflow file but likely lacks C++-specific query configuration. Given that Conky is a C++ system monitor handling privileged operations and system resources, adding a tailored CodeQL C++ configuration would catch memory safety issues, buffer overflows, and use-after-free vulnerabilities early. This is high-value for a system utility.

• [ ] Create .github/codeql-config.yml with C++ query suites enabled
• [ ] Add c/cpp language matrix expansion to .github/workflows/codeql.yml
• [ ] Configure custom queries for security-sensitive areas (e.g., Vc SIMD operations in 3rdparty/Vc)
• [ ] Test locally and ensure no false positives in existing codebase
• [ ] Document findings in security-focused CONTRIBUTING section

Add unit tests for core monitoring modules (src/)

The file structure shows comprehensive GitHub Actions CI (build-and-test-linux.yaml, build-and-test-macos.yaml) but the partial structure doesn't reveal src/ test coverage. A system monitor needs reliable unit tests for core modules like CPU, memory, and network monitoring. Adding a structured test suite (likely using a C++ framework like Catch2 or Google Test) would catch regressions and improve contributor confidence.

• [ ] Audit src/ directory to identify untested modules (CPU, memory, network monitoring)
• [ ] Create tests/ directory structure mirroring src/ organization
• [ ] Add Catch2 or Google Test dependency to CMakeLists.txt (if not present)
• [ ] Write unit tests for at least 3 core monitoring modules with >80% coverage
• [ ] Integrate test execution into build-and-test-*.yaml workflows with coverage reporting

Document Vc SIMD library usage and performance implications in CONTRIBUTING.md

The repo includes a substantial 3rdparty/Vc/ (SIMD vectorization library) but there's no visible documentation about when/why to use it or how it impacts performance. This creates friction for contributors modifying performance-critical paths. Adding specific guidance on SIMD usage patterns would improve code quality and contributor onboarding.

• [ ] Review 3rdparty/Vc/README.md and existing usage patterns in codebase
• [ ] Create .github/instructions/simd-optimization.instructions.md with examples
• [ ] Document trade-offs (portability vs performance) for CPU, memory, and rendering loops
• [ ] Add benchmarking guidance and profiling tools (e.g., perf, valgrind)
• [ ] Link instructions in CONTRIBUTING.md for contributors touching performance-sensitive code

• Add unit tests for src/core.cpp metric parsing (CPU, memory, disk) — currently no test/ directory visible; start with basic harness using CMake's enable_testing().
• Extend Lua documentation in lua/ subdirectory with code examples for Cairo drawing and Imlib2 image loading — lua/*.cpp exports many functions but has minimal inline comments.
• Implement missing built-in variable for systemd unit status or cgroup memory usage — check src/core.cpp's conky_vars registry and add a new case for ${systemd_unit_active} or similar.

The Conky project demonstrates reasonable security practices including GitHub dependabot configuration, CodeQL analysis, and a transparent open-source development model. However, analysis is limited by incomplete source code samples. Key concerns include: (1) truncated Dockerfile preventing full build security assessment, (2) missing dependency lock file specifications, (3) unscanned vendored third-party libraries, and (4) lack of container image scanning in CI/CD pipelines. The project would benefit from stricter base image pinning, automated vulnerability scanning of all dependencies including vendored code, and enhanced container image security scanning before releases. No hardcoded secrets, SQL injection risks, or XSS vulnerabilities were apparent in the provided file structure.

• Medium · Incomplete Dockerfile snippet - Security validation impossible — Dockerfile (build stage). The provided Dockerfile is truncated at a critical point (ARG X11=ye...), making it impossible to fully analyze build security. The conditional logic based on the X11 argument is cut off, potentially hiding misconfigurations or insecure build steps. Fix: Provide complete Dockerfile content for full security analysis. Review the full conditional build logic for X11 support to ensure no insecure configurations are present.
• Low · No dependency lock file provided — Project root / dependency management. The analysis lacks a package dependency file (package.json, requirements.txt, CMakeLists.txt dependencies section, etc.). Without locked versions of dependencies, the project may be vulnerable to supply chain attacks or use outdated vulnerable versions. Fix: Implement and commit dependency lock files (e.g., package-lock.json, Pipfile.lock). Use CMake's FetchContent with specific commit hashes or versions for external dependencies. Regularly audit dependencies with tools like 'dependabot' (which is already configured in .github/dependabot.yml).
• Low · Third-party dependency vendoring lacks security scanning — 3rdparty/Vc/. The 3rdparty/Vc directory contains vendored SIMD library code. While vendoring provides reproducibility, there's no evidence of security scanning or updates for vulnerabilities in these included libraries. Fix: Implement automated scanning of vendored dependencies using tools like 'Snyk' or 'OWASP Dependency-Check'. Create a process for regularly updating vendored libraries and auditing them for known vulnerabilities. Document the vendored library versions and their vulnerability status.
• Low · Docker image uses Ubuntu base without specific version pinning — Dockerfile (FROM statement). The Dockerfile uses 'FROM ubuntu:noble' without a digest hash. This allows for subtle changes in the base image that could introduce vulnerabilities or unexpected behavior. Fix: Pin the base image to a specific digest: 'FROM ubuntu:noble@sha256:...' instead of just the tag. This ensures reproducible builds and prevents supply chain attacks via base image updates.
• Low · No apparent container security scanning in CI/CD — .github/workflows/ (docker.yaml, publish-appimage.yml). While CodeQL workflow is present for code analysis, there's no visible evidence of container image scanning (Trivy, Snyk Container, etc.) in the GitHub workflows for Docker builds. Fix: Add container image scanning to the Docker build pipeline. Use tools like 'Trivy' or 'Snyk' to scan built images before publishing. Include SBOM (Software Bill of Materials) generation for supply chain visibility.

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.