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/sqshq/sampler 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 2y ago

• 14 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 81% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ 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 sqshq/sampler repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sqshq/sampler.

What it runs against: a local clone of sqshq/sampler — 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 sqshq/sampler | 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 master exists | Catches branch renames | | 4 | Last commit ≤ 837 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "sqshq/sampler(\\.git)?\\b" \\
  && ok "origin remote is sqshq/sampler" \\
  || miss "origin remote is not sqshq/sampler (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 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 837 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~807d)"
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/sqshq/sampler"
  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).

Sampler is a Go-based terminal UI tool that executes shell commands at configurable intervals and visualizes their output as real-time charts, gauges, and text boxes. It reads a simple YAML configuration file to define commands and rendering options, then displays live-updating dashboards in the terminal using termui/v3—solving the problem of quick ad-hoc monitoring without spinning up Prometheus/Grafana infrastructure. Monolithic single-binary Go project organized by concern: component/ holds all UI rendering logic (runchart, barchart, gauge, sparkline, textbox), config/ handles YAML parsing and validation, console/ wraps termui/v3 primitives with palette/signal management, data/ manages command execution and output buffering, asset/ bundles audio files. Entry point is main.go (not listed but standard Go convention).

DevOps engineers, SREs, and developers who need to quickly monitor dynamic processes (database queries, message queue depths, deployment script progress) directly from the terminal during development or incident response, without the overhead of setting up a full monitoring stack.

Production-ready but not heavily maintained. The codebase is ~104KB of Go, has CI via Travis CI, includes unit tests in component/util/ and data/, and supports multiple platforms (macOS, Linux, Windows, Docker). However, go.mod pins Go 1.17 (released Sept 2021) and the repo shows signs of being stable rather than actively developed—it's mature and reliable for its scope, but not receiving frequent feature updates.

Low risk for stable usage, moderate risk for active contribution. Dependencies are minimal and well-established (termui/v3, yaml.v3, oto for audio)—no bloated dependency tree. Single maintainer (sqshq) is the primary risk factor; the repo appears lightly maintained with infrequent commits. No visible breaking changes in recent history, but the small test coverage in component/runchart (the most complex visualization) and textbox could hide edge cases.

The repo appears to be in maintenance mode—no active PR or issue activity is visible from the file listing. The .travis.yml indicates CI/CD was set up but likely outdated (Travis CI has evolved). Docker support and multi-platform releases suggest past effort to improve distribution, but no recent innovations are apparent.

git clone https://github.com/sqshq/sampler.git
cd sampler
go build -o sampler .
./sampler --config examples/config.yml

Daily commands:

go build -o sampler .
./sampler -c config.yml

Alternatively with Docker: ```bash docker build -t sampler . docker run -it -v $(pwd)/config.yml:/root/config.yml sampler --config /root/config.yml

• component/component.go: Defines the Component interface that all UI elements (runchart, barchart, gauge, sparkline, textbox) implement; central abstraction.
• config/config.go: Parses and validates the YAML configuration structure; defines what commands and visualization options users can specify.
• component/runchart/runchart.go: The most complex component—renders time-series line charts with grid, legend, and multi-line support; handles buffering and scaling logic.
• data/consumer.go: Core polling loop that executes shell commands at intervals, captures output, buffers results, and notifies components of new data.
• console/console.go: Wraps termui/v3 and manages the overall terminal UI event loop, screen rendering, and palette application.
• component/util/format.go: Shared formatting logic for numbers, units, and timestamps across all components; critical for consistent visualization.
• asset/bindata.go: Embeds alert sound files (compiled binary assets) into the final executable so users don't need external audio files.

Start in config/config.go and config/validator.go to understand YAML schema. For new chart types, copy component/barchart/ as a template and register in component/component.go. To modify rendering, edit component/runchart/runchart.go (the main time-series chart) or the corresponding component file. Tests are minimal—add test cases in component/util/*_test.go as a model.

1. Shell command execution uses kr/pty (pseudo-terminal), not plain os/exec—this means interactive/TTY-aware commands work, but setup can be Unix-specific and Windows support is experimental. 2) The YAML schema in config/ is strict and must match exactly—typos silently fail with minimal error messages (see config/validator.go for limited validation). 3) Alert sounds require libasound2-dev on Linux (noted in README), which is not auto-installed; Windows audio via oto may need MinGW headers. 4) Component layout and size adjustments are interactive (resized in UI at runtime), but are not persisted—no config save-back on exit.

• Pseudo-terminal (PTY) I/O — Sampler uses kr/pty to execute shell commands in pseudo-terminals rather than standard pipes; this is critical to understand because it affects which commands work, how signals propagate, and why Windows support is experimental.
• Ring buffer / circular buffer data structure — data/consumer.go buffers command output in a fixed-size rolling window; understanding this pattern is essential to modifying how much history is kept and how old data is discarded.
• Termbox / low-level terminal control — termui/v3 depends on termbox-go for raw terminal input/output; sampler's rendering relies on this—knowing termbox concepts (cells, attributes, event polling) helps debug display issues.
• ASCII art rendering / Figlet fonts — component/statusbar.go uses figlet4go to render large ASCII text headers; relevant if you want to customize UI labels or add splash screens.
• Rate limiting / polling intervals — data/consumer.go polls commands at user-defined intervals; understanding interval arithmetic, jitter, and drift is critical to avoiding command execution pileups or missed samples.
• YAML schema validation — config/validator.go enforces structure on user-provided YAML; knowing how this validation works helps debug cryptic config rejection errors.
• Goroutine-safe channels for event signaling — console/signal.go and the overall event loop use Go channels to coordinate between command execution, UI rendering, and user input—critical to understanding how Sampler stays responsive.

• gizak/termui — Direct dependency—sampler's entire UI rendering is built on top of this Go terminal UI library; understanding termui/v3 architecture is essential for UI modifications.
• prometheus/prometheus — The 'heavyweight' alternative sampler explicitly acknowledges in README; Prometheus+Grafana is the production-grade solution for the same observability problem.
• nicolaka/netshoot — Complementary Docker-based troubleshooting tool; both sampler and netshoot are designed for rapid terminal-first diagnostics without full monitoring stack setup.
• httpie/httpie — Similar philosophy of a CLI tool designed for developer ergonomics and quick ad-hoc tasks (HTTP requests) instead of infrastructure—appeals to same user base.
• grafana/k6 — Load testing tool that also emphasizes scriptability via YAML/JavaScript and real-time terminal visualization; targets same DevOps workflow.

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 data/consumer.go and data/int.go

The data package handles command execution and output parsing (consumer.go, int.go, int_basic.go, int_pty.go). Currently only data/consumer_test.go exists. The int*.go files lack test coverage despite handling platform-specific PTY logic. This is critical for reliability across macOS/Linux/Windows, especially given int_pty_windows.go handling.

• [ ] Create data/int_test.go with tests for integer parsing edge cases (negative numbers, large values, invalid inputs)
• [ ] Create data/int_basic_test.go testing fallback integer parsing logic
• [ ] Create data/int_pty_test.go with mocked PTY tests for Unix-like systems
• [ ] Create data/int_pty_windows_test.go with Windows-specific PTY logic tests
• [ ] Ensure >80% code coverage for data package

Add GitHub Actions workflow for multi-platform builds and releases

.travis.yml exists but Travis CI is legacy. The repo has Dockerfile and cross-platform code (int_pty.go, int_pty_windows.go, data/signal.go) but no modern GitHub Actions. New maintainers need automated builds for Linux, macOS, and Windows to ensure quality releases.

• [ ] Create .github/workflows/build.yml with matrix strategy for ubuntu-latest, macos-latest, windows-latest
• [ ] Add Go version matrix (1.17+) matching go.mod
• [ ] Include go test, go build, and go vet steps
• [ ] Add artifact upload for compiled binaries
• [ ] Create .github/workflows/release.yml for tagged releases using GoReleaser

Add integration tests for component rendering in component/*_test.go

The component package has multiple visualization types (gauge, runchart, sparkline, barchart, textbox) but only gauge/gauge_test.go and sparkline/sparkline_test.go exist. Rendering logic in component/runchart/runchart.go, component/barchart/barchart.go, and component/textbox/textbox.go lack tests despite containing complex coordinate/layout calculations.

• [ ] Create component/runchart/runchart_test.go testing grid rendering, legend positioning, and data point plotting
• [ ] Create component/barchart/barchart_test.go testing bar height calculations and scaling
• [ ] Create component/textbox/textbox_test.go testing text wrapping and overflow handling
• [ ] Create component/asciibox/asciibox_test.go testing border rendering
• [ ] Add tests using mock termui components to verify render output dimensions

• Add unit tests to component/runchart/runchart.go covering edge cases: empty data, single-point series, values exceeding axis range, and grid scaling with very large/small numbers. Current test coverage is minimal despite this being the most complex component.
• Extend component/util/format_test.go to test the number formatting with international locales (French comma decimals, Arabic-Indic numerals) and very large exponent values (1e20, -1e-10) to catch locale-specific rounding bugs.
• Add missing input validation and error messages to config/validator.go: reject configs with duplicate command names, negative refresh intervals, and out-of-range component dimensions, with clear error text instead of silent failures.

• High · Outdated Go Version — go.mod. The project targets Go 1.17, which reached end-of-life in August 2022. This version no longer receives security updates, leaving the application vulnerable to known Go runtime and standard library vulnerabilities. Fix: Update to a supported Go version (1.21 or later). Rebuild and test the application thoroughly with the newer version.
• High · Outdated Vulnerable Dependencies — go.mod. Multiple dependencies have known vulnerabilities and outdated versions: gopkg.in/yaml.v3 (v3.0.0-20190709130402 - very old), github.com/hajimehoshi/oto (v0.1.1), github.com/hajimehoshi/go-mp3 (v0.1.1), and github.com/gizak/termui/v3 (v3.0.0). These versions predate critical security fixes. Fix: Update all dependencies to their latest stable versions. Run 'go get -u' and 'go mod tidy'. Test thoroughly after updates, especially for audio-related packages.
• High · Command Injection Risk in Shell Execution — data/int_pty.go, data/consumer.go, config/. The tool is designed to execute arbitrary shell commands configured via YAML files. If YAML configuration files are sourced from untrusted locations or can be modified by unauthorized users, this creates a command injection vulnerability. The data/int_pty.go and data/consumer.go files likely handle command execution. Fix: Implement strict validation and sanitization of YAML configuration files. Use allowlists for permitted commands when possible. Enforce proper file permissions on configuration files (e.g., chmod 600). Document security implications clearly in README.
• High · Insecure Docker Base Image — Dockerfile. The Dockerfile uses 'ubuntu:focal' without specifying a digest hash. Ubuntu Focal (20.04 LTS) reached end-of-life in April 2025. The image could be updated without the developer's knowledge, potentially introducing vulnerabilities. Fix: Pin the Ubuntu base image to a specific digest (e.g., 'ubuntu:focal@sha256:...'). Consider upgrading to ubuntu:jammy or ubuntu:noble (24.04 LTS). Use 'docker pull --digest' to get the SHA256 hash.
• High · Insufficient Container Hardening — Dockerfile. The Dockerfile runs with default privileges and does not specify security options. The container lacks USER directive, capability dropping, and read-only filesystem constraints. Combined with arbitrary command execution, this increases attack surface. Fix: Add 'USER sampler' (create non-root user), use '--cap-drop=ALL' flags, make filesystem read-only where possible, and add security_opt settings. Use multi-stage builds to reduce image size and attack surface.
• Medium · Missing YAML Schema Validation — config/config.go, config/validator.go. YAML configuration parsing via gopkg.in/yaml.v3 without apparent schema validation could allow malformed or malicious configurations to cause DoS or unexpected behavior. Fix: Implement comprehensive schema validation for all YAML configurations. Define strict types and validate against expected structures. Use a schema validation library if available.
• Medium · No Input Sanitization for Display Output — component/textbox/textbox.go, component/util/format.go. The component visualization modules (textbox, runchart, gauge, etc.) may display untrusted command output without proper sanitization, potentially causing terminal injection attacks (ANSI escape sequences, terminal control characters). Fix: Sanitize all command output before displaying. Strip or escape ANSI control sequences and terminal control characters. Use libraries like 'lunixbochs/vtclean' (already included) more comprehensively.
• Medium · No Rate Limiting on Command Execution — data/sampler.go, data/consumer.go. The tool executes shell commands at configured intervals without apparent rate limiting. Malicious YAML configurations could spawn resource exhaustion or DoS attacks. Fix: Implement rate limiting and resource constraints (CPU, memory, timeout limits per command). Add configurable execution limits and validation for command frequency

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.