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/rcourtman/Pulse 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 today
• 2 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% 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 rcourtman/Pulse repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rcourtman/Pulse.

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

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

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

# 4. Critical files exist
test -f "cmd/pulse/main.go" \\
  && ok "cmd/pulse/main.go" \\
  || miss "missing critical file: cmd/pulse/main.go"
test -f "cmd/pulse-agent/main.go" \\
  && ok "cmd/pulse-agent/main.go" \\
  || miss "missing critical file: cmd/pulse-agent/main.go"
test -f "cmd/pulse-host-agent/main.go" \\
  && ok "cmd/pulse-host-agent/main.go" \\
  || miss "missing critical file: cmd/pulse-host-agent/main.go"
test -f "deploy/helm/pulse/values.yaml" \\
  && ok "deploy/helm/pulse/values.yaml" \\
  || miss "missing critical file: deploy/helm/pulse/values.yaml"
test -f "docker-compose.yml" \\
  && ok "docker-compose.yml" \\
  || miss "missing critical file: docker-compose.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/rcourtman/Pulse"
  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).

Pulse is a unified real-time monitoring dashboard that consolidates metrics, alerts, and AI-powered insights from Proxmox VE/PBS/PMG, Docker/Podman, and Kubernetes clusters into a single web interface. It features auto-discovery, smart multi-channel alerts (Discord, Slack, Telegram, Email), persistent metrics history, and optional AI-powered chat and patrol health checks, solving the 'single pane of glass' problem for homelabs and sysadmins without enterprise monitoring complexity. Monorepo architecture: Go backend in cmd/ and core package structure, TypeScript/SolidJS frontend under web/ (SolidJS 1.8.0, Vite build), shell scripts for installation/agents, Kubernetes manifests likely in a k8s/ or helm/ directory, and .devcontainer/ for Docker-based dev environment. State management is SolidJS reactive stores; backend likely gRPC or REST API served by Go server.

Systems administrators, homelab operators, and managed service providers (MSPs) who run heterogeneous infrastructure across Proxmox, Docker, and Kubernetes and need unified visibility without deploying Prometheus/Grafana/AlertManager stacks. Also relevant to DevOps engineers managing multi-platform deployments who want encrypted credential storage and privacy-focused monitoring.

Production-ready and actively maintained. The repo shows 15MB+ of Go code, comprehensive CI/CD workflows (build-and-test.yml, test-e2e.yml, publish-docker.yml), semantic versioning in VERSION file, and active Helm chart support. Recent workflow files and extensive documentation (ARCHITECTURE.md, CONTRIBUTING.md) indicate mature infrastructure; likely 50+ GitHub stars based on feature richness and deployment options.

Single maintainer (rcourtman) risk is present, but mitigated by comprehensive GitHub Actions workflows and Helm chart automation. The dependency surface is broad (SolidJS frontend, Go backend, multiple integration points), but no obvious abandoned dependencies visible. Watch for breaking changes across Proxmox/Kubernetes API versions—the repo explicitly supports Proxmox 9.1+ OCI containers, suggesting active maintenance of upstream compatibility.

Active development on AI-powered features (Chat Assistant, Patrol health checks, Alert Analysis), Helm chart improvements (separate helm-ci.yml and helm-pages.yml workflows), automated demo server updates (deploy-demo-server.yml, update-demo-server.yml), and Docker/Kubernetes integration expansion. Release automation is mature with create-release.yml and promote-floating-tags.yml.

Clone and use the dev container (fastest):

git clone https://github.com/rcourtman/Pulse.git
cd Pulse
code . # Opens in VS Code with devcontainer
# Or manually: docker build -f .devcontainer/Dockerfile -t pulse-dev . && docker run -it pulse-dev

For bare metal: bash .devcontainer/start-pulse-dev.sh after setup.

Daily commands: Frontend: cd web && npm install && npm run dev (Vite dev server on port 5173 likely). Backend: inferred from Makefile and Go structure—make build && ./bin/pulse or go run ./cmd/pulse. Full stack: bash .devcontainer/start-pulse-dev.sh or Docker: docker-compose up (if docker-compose.yml exists).

• cmd/pulse/main.go — Main entry point for the Pulse server; initializes the monitoring dashboard, API routes, and infrastructure collectors.
• cmd/pulse-agent/main.go — Entry point for the distributed agent that collects metrics from Docker, Kubernetes, and Proxmox endpoints.
• cmd/pulse-host-agent/main.go — Host-level agent for system metrics collection; critical for node-level monitoring across infrastructure.
• deploy/helm/pulse/values.yaml — Helm chart configuration; essential for understanding how Pulse is deployed in Kubernetes environments.
• docker-compose.yml — Development and deployment compose file; defines how all Pulse services interconnect and communicate.
• ARCHITECTURE.md — High-level system design and component interactions; required reading for understanding module responsibilities.
• .env.example — Configuration template showing all required environment variables for integrating Proxmox, Docker, Kubernetes, and AI providers.

Add a new infrastructure collector (e.g., new cloud provider)

1. Define collector configuration schema in cmd/pulse/config.go under the appropriate collector type section (cmd/pulse/config.go)
2. Implement collector initialization and metric scraping logic, following the pattern of existing collectors (referenced in bootstrap.go) (cmd/pulse/bootstrap.go)
3. Add environment variables to .env.example for the new collector's credentials and endpoints (.env.example)
4. Export metrics to the Prometheus-compatible endpoint via metrics_server.go (cmd/pulse/metrics_server.go)
5. Add collector documentation to ARCHITECTURE.md describing its responsibility and integration points (ARCHITECTURE.md)

Add agent health check or monitoring capability

1. Define health check logic in cmd/pulse-agent/main.go or cmd/pulse-host-agent/main.go (cmd/pulse-agent/main.go)
2. Write test cases validating health check response in cmd/pulse-agent/health_test.go (cmd/pulse-agent/health_test.go)
3. Update docker-healthcheck.sh to include the new health check endpoint (docker-healthcheck.sh)
4. Configure health check in docker-compose.yml for local testing (docker-compose.yml)

Update Kubernetes deployment configuration

1. Modify Helm values in deploy/helm/pulse/values.yaml to add new deployment parameters (deploy/helm/pulse/values.yaml)
2. Update Helm templates in deploy/helm/pulse/templates/ (e.g., deployment.yaml) to reference new values (deploy/helm/pulse/templates/deployment.yaml)
3. Update Chart.yaml with new version and dependency information (deploy/helm/pulse/Chart.yaml)
4. Document deployment changes in deploy/helm/pulse/README.md (deploy/helm/pulse/README.md)

Add a new command-line utility (e.g., configuration validator)

1. Create new cmd directory entry with main.go (e.g., cmd/pulse-validator/main.go), following patterns from cmd/hashpw/ (cmd/hashpw/main.go)
2. Add unit tests alongside the utility in cmd/pulse-validator/main_test.go (cmd/hashpw/main_test.go)
3. Update Makefile with build target for the new utility (Makefile)
4. Document the utility in CONTRIBUTING.md or docs/ directory (CONTRIBUTING.md)

• Go (Backend) — Fast compilation, single binary deployment, excellent concurrency with goroutines for multi-collector polling; ideal for resource-constrained infrastructure monitoring
• React/Vite (Frontend) — Modern type-safe UI with real-time metric visualization; Vite provides fast HMR for dashboard development and optimized production builds
• Helm + Kubernetes templates — Standard cloud-native deployment model; enables GitOps workflows and multi-environment configuration management
• Docker Compose — Local development and quick-start experience; mirrors production architecture for easy onboarding
• Prometheus metrics format — Industry-standard metrics protocol; enables integration with existing monitoring stacks and tools
• Distributed agents (pulse-agent, pulse-host-agent) — Decoupled architecture allows monitoring of systems without direct API access; reduces central server load and improves fault isolation

• Central server + distributed agents vs. fully decentralized peer-to-peer

  • Why: Central aggregation simplifies unified dashboard, alerting, and AI analysis; agents communicate only with central server for operational simplicity
  • Consequence: Central server becomes critical point of failure; requires HA setup in production. Agents must maintain connectivity to primary server.

• AI-powered insights as integrated feature vs. separate microservice

  • Why: Simpler deployment model; reduces operational overhead for single-pane-of-glass experience
  • Consequence: AI provider dependencies (latency, cost) directly impact core dashboard responsiveness; requires circuit breakers and graceful degradation

• Multi-infrastructure support (Proxmox, Docker, Kubernetes) in single agent vs. specialist agents

  • Why: Simplified agent deployment; single binary to manage across all infrastructure types
  • Consequence: Agent binary size and memory footprint larger; configuration complexity increases; selective disabling of unneeded collectors recommended

• Metrics-first architecture (Prometheus export) vs. custom time-series database

  • Why: Reduces complexity; integrates with existing monitoring ecosystems and TSDB options (Prometheus, Grafana, etc.)
  • Consequence: Custom retention policies and advanced analytics require external storage; no built-in long-term metrics storage in core

• Does not provide persistent time-series database; metrics aggregation is in-memory/short-lived unless persisted externally
• Does not handle user authentication/RBAC in open-source version; proxy-based auth (nginx, Keycloak) required for production
• Does not provide workload orchestration or auto-scaling; monitors infrastructure only, does not execute remediation actions
• Does not support Windows Kubernetes nodes; Linux-focused infrastructure monitoring
• Not a replacement for Prometheus/Grafana; complements existing stacks rather than displacing them

The frontend generates types from backend Go code via npm run generate-types (calls ../scripts/generate-types.go)—must run after any Go API changes or TypeScript will fail type-check. Credentials are encrypted at rest (per README); ensure ENCRYPTION_KEY env var is set in production. The devcontainer assumes Docker and VS Code; Windows users may hit path issues. Agent installation uses /install.sh endpoint served from Pulse server—verify network access before deploying agents. Proxmox and Kubernetes client libraries have version-specific APIs; check docs for your Proxmox/K8s version compatibility.

• API Credential Encryption at Rest — Pulse encrypts stored API credentials (Proxmox tokens, K8s service accounts, Docker certs) in the database; understanding the encryption layer is critical for secure features and audit compliance
• Server-Sent Events (SSE) for Real-time Metrics — Pulse likely streams real-time metrics updates to the frontend via SSE rather than polling; efficient for dashboard latency and reduces backend load
• Auto-Discovery via Network Scanning — Core feature of Pulse is auto-discovering Proxmox nodes on the network without manual registration; involves mDNS, ARP scanning, or API enumeration
• Agent vs Agentless Monitoring — Pulse supports both deployment modes—agentless (queries APIs directly) and agent-based (agents installed on targets send data); understanding when to use each affects scalability and latency
• OIDC/SSO Authentication Flow — Pulse integrates Single Sign-On via OIDC providers; critical for multi-user deployments and enterprise security posture
• LLM Integration Pattern (BYOK) — Pulse's Chat Assistant and Patrol use 'Bring Your Own Key' (BYOK) pattern—users provide their own LLM API keys; design avoids vendor lock-in and data leakage to Pulse servers
• Persistent Metrics Storage with Retention Policies — Pulse stores historical metrics with configurable retention (e.g., 30 days raw, 1 year aggregated); impacts database schema design and query efficiency

• prometheus/prometheus — Industry-standard time-series metrics collection; Pulse complements by adding a simpler UI and infra-specific integrations, but could potentially use Prometheus as a backend
• grafana/grafana — Enterprise-grade dashboard platform; Pulse's direct competitor but optimized for heterogeneous infra (Proxmox/Docker/K8s) rather than generic metrics
• portainer/portainer — Docker/Kubernetes container management UI; overlaps on Docker/K8s visibility; Pulse extends with Proxmox and AI features
• proxmox/pve-docs — Official Proxmox VE documentation and API specs; essential reference for understanding Proxmox integration points in Pulse
• kubernetes/kubernetes — K8s upstream repository; Pulse likely uses client-go for cluster monitoring; useful for understanding K8s API patterns in the codebase

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 aiChatUtils.ts with 100% coverage

The repo has a script 'test:coverage:ai' that enforces 100% coverage specifically for src/components/AI/aiChatUtils.ts, but there's no evidence of a corresponding test file in the structure. This is a high-value PR because: (1) it's explicitly called out in package.json as a coverage requirement, (2) AI chat utilities are critical for the 'AI-powered insights' feature mentioned in the repo description, and (3) it sets a strong precedent for test quality in the codebase.

• [ ] Create src/components/AI/aiChatUtils.test.ts or aiChatUtils.test.tsx
• [ ] Write unit tests covering all exported functions and edge cases in aiChatUtils.ts
• [ ] Run 'npm run test:coverage:ai' to verify 100% line, branch, and function coverage
• [ ] Ensure tests cover integration with DOMPurify (dependency for sanitization) and marked (Markdown parsing)
• [ ] Add test cases for error handling and null/undefined inputs

Add GitHub Actions workflow for frontend type safety and linting validation

The repo has a comprehensive set of CI workflows (.github/workflows/) including build-and-test.yml, test-e2e.yml, and helm-ci.yml, but there's no dedicated workflow for frontend TypeScript type checking and ESLint validation before merge. Given that the project uses 'type-check', 'lint', and 'format:check' npm scripts, this is valuable because: (1) it prevents type errors and style violations from reaching main, (2) the frontend is explicitly 'type-safe' per package.json description, and (3) it complements existing Go-focused CI.

• [ ] Create .github/workflows/frontend-checks.yml
• [ ] Add job to run 'npm run type-check' on src/ directory
• [ ] Add job to run 'npm run lint' with failure on warnings
• [ ] Add job to run 'npm run format:check' to enforce Prettier consistency
• [ ] Configure workflow to trigger on PR changes to 'src/', 'package.json', and '.eslintrc.*'
• [ ] Set workflow to be required status check before merge

Add integration tests for Solid.js components with @solidjs/testing-library

The repo has @solidjs/testing-library and testing-library/jest-dom in devDependencies, indicating intention to test Solid.js components, but the file structure shows no test files in src/components/. This is high-value because: (1) Solid.js components are the UI foundation for the 'beautiful unified dashboard' feature, (2) the testing infrastructure is already configured but unused, and (3) testing monitoring dashboard components (alerts, metrics displays) prevents regressions in critical UI functionality.

• [ ] Identify 2-3 core Solid.js components in src/components/ that lack test files (e.g., dashboard, alert display, metric cards)
• [ ] Create corresponding .test.tsx files using @solidjs/testing-library render() and testing-library queries
• [ ] Write tests for component rendering, user interactions (clicks, inputs), and prop variations
• [ ] Ensure tests verify integration with dompurify-rendered content (sanitized alerts/messages)
• [ ] Run 'npm run test' to verify all tests pass and update coverage thresholds in vitest config if needed

• Add TypeScript tests for web/src/components/AI/aiChatUtils.ts—the test script test:coverage:ai expects 100% coverage but file may have gaps; identify missing branches and add test cases
• Document the type generation pipeline in CONTRIBUTING.md with a 'Modifying the API' section explaining the npm run generate-types workflow and common pitfalls for newcomers modifying Go types
• Create missing integration test for agent auto-discovery—check .github/workflows/test-e2e.yml for current scope and add a scenario that spins up a mock Proxmox host and verifies discovery without manual registration

• High · Potential XSS via marked markdown parsing — frontend-modern/package.json, src/components/AI/aiChatUtils.ts (likely). The dependency 'marked' (v17.0.1) is used in the frontend for rendering markdown. Without proper sanitization before rendering, user-supplied markdown content could lead to XSS attacks. While 'dompurify' is included as a dependency, it's critical that it's used to sanitize marked output before DOM insertion. Fix: Ensure all markdown output from 'marked' is passed through 'dompurify' before rendering. Implement strict CSP headers. Verify aiChatUtils.ts properly sanitizes all user input and marked output.
• High · SSH key storage in containerized deployments — SECURITY.md, cmd/pulse-host-agent/main.go, cmd/pulse-agent/main.go. SECURITY.md explicitly documents that SSH private keys should not be stored in Docker containers due to container compromise risks. However, the codebase appears to support SSH-based temperature monitoring. If not properly restricted, users may inadvertently store SSH keys in container images, creating critical infrastructure compromise risks. Fix: Enforce runtime checks that block SSH key loading in containerized environments. Implement clear warnings and documentation. Use external secret management (Kubernetes secrets, Docker secrets) instead of baked-in keys. Add validation in bootstrap.go to prevent SSH auth in containers.
• High · Potential hardcoded credentials in environment configuration — .env.example, cmd/pulse/config.go. .env.example shows API_TOKENS and PULSE_AUTH_PASS can be stored in environment files. If .env files are accidentally committed or improperly permissioned, credentials exposure is likely. The .env.example comment mentions 'Keep the file out of version control' but relies on user compliance. Fix: Implement pre-commit hooks (already using .husky) to prevent .env file commits. Use gitignore verification. Consider forcing secrets to be read from mounted volumes or secret management systems only. Add warnings if credentials are detected in config during startup.
• Medium · DOMPurify configuration not visible — frontend-modern/src/components/AI/ (likely), frontend-modern/package.json. While dompurify is included as a dependency (v3.4.0), the codebase structure doesn't show explicit configuration. DOMPurify has configurable settings that could impact security (e.g., ALLOWED_TAGS, ALLOWED_ATTR). Default configuration may not be optimal for the application's needs. Fix: Explicitly configure DOMPurify with a whitelist approach. Review all dompurify().sanitize() calls and ensure they use strict configurations. Document the security requirements and test against common XSS payloads.
• Medium · Solid.js SSR potential information disclosure — frontend-modern/package.json, cmd/pulse/main.go (frontend embedding). @solidjs/router and solid-js are SSR-capable frameworks. If server-side rendering is used, sensitive data could be exposed in HTML source if not properly filtered. No evidence of API response filtering in visible code. Fix: Sanitize all API responses before SSR. Implement strict data filtering. Review cmd/pulse/metrics_server.go for any sensitive data exposure. Use Content Security Policy headers to mitigate XSS from SSR injection points.
• Medium · Kubernetes and Docker API exposure — cmd/pulse/main.go, cmd/pulse-agent/main.go. The application monitors Docker and Kubernetes, which means it requires API credentials to these systems. No evidence in visible structure of how these credentials are managed, rotated, or secured. Fix: Use read-only service accounts with minimal permissions for Kubernetes monitoring. Implement credential rotation policies. Use in-cluster authentication for Kubernetes agents. Document RBAC requirements clearly.
• Medium · Missing security headers configuration — Dockerfile, cmd/pulse/main.go. No visible CSP, X-Frame-Options, X-Content-Type-Options, or other security headers in the Dockerfile or application configuration shown. Critical for preventing XSS and clickjacking attacks. Fix: Add comprehensive security headers (CSP, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security). Implement in the Go HTTP server middleware. Consider Helmet-like

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.