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/wtfutil/wtf 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 1w ago
• 8 active contributors
• MPL-2.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 71% of recent commits
• ⚠ 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 wtfutil/wtf repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/wtfutil/wtf.

What it runs against: a local clone of wtfutil/wtf — 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 wtfutil/wtf | Confirms the artifact applies here, not a fork | | 2 | License is still MPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch trunk exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 38 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is MPL-2.0" \\
  || miss "license drift — was MPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify trunk >/dev/null 2>&1 \\
  && ok "default branch trunk exists" \\
  || miss "default branch trunk no longer exists"

# 4. Critical files exist
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "app/wtf_app.go" \\
  && ok "app/wtf_app.go" \\
  || miss "missing critical file: app/wtf_app.go"
test -f "app/widget_maker.go" \\
  && ok "app/widget_maker.go" \\
  || miss "missing critical file: app/widget_maker.go"
test -f "cfg/config_files.go" \\
  && ok "cfg/config_files.go" \\
  || miss "missing critical file: cfg/config_files.go"
test -f "app/scheduler.go" \\
  && ok "app/scheduler.go" \\
  || miss "missing critical file: app/scheduler.go"

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

WTF (wtfutil) is a Go-based terminal dashboard that aggregates personal productivity and infrastructure data (GitHub, Jira, Docker, Kubernetes, weather, crypto, sports scores, etc.) into a single customizable information display. It solves the problem of context-switching between multiple web dashboards and CLIs by bringing key metrics into your terminal via YAML configuration files. Modular monolith: /app contains the core dashboard engine (app_manager.go, scheduler.go, widget_maker.go), /cfg handles configuration parsing (config_files.go, common_settings.go), and individual modules live in peer directories (not shown in file list but implied by the module plugin architecture). The TUI uses rivo/tview, and the scheduler coordinates concurrent module refreshes.

Developers, DevOps engineers, and tech professionals who spend time in the terminal and want at-a-glance access to their GitHub PRs, deployment status, Docker containers, Kubernetes clusters, and other real-time metrics without switching browser tabs.

Production-ready and actively maintained. The project has thousands of users (per README), comprehensive CI/CD via GitHub Actions (golangci-lint, CodeQL, goreleaser, pr-checks), structured issue/PR templates, and a clear governance model with sponsorship support. The Go version constraint is 1.26.2, indicating recent updates.

Low-to-moderate risk. The dependency graph is large (40+ external dependencies across cloud APIs, terminal UI, Docker, Kubernetes clients), which increases supply-chain surface area. The codebase depends on maintained third-party API clients (GitHub, Jira, PagerDuty, Asana, Trello, Spotify, DigitalOcean, Azure DevOps) that could have breaking changes. Single-maintainer risk is mitigated by community contributions and GitHub Sponsors model.

Active development with recent Go version bumps (1.26.2), ongoing dependabot updates (visible in .github/dependabot.yml), and a structured PR workflow. The repo maintains stale issue management (.github/stale.yml) and runs multi-step CI including static analysis (staticcheck.yml) and linting (golangci-lint.yml).

git clone https://github.com/wtfutil/wtf.git
cd wtf
make
./bin/wtf

Then edit or copy a sample config from _sample_configs/ to ~/.config/wtf/config.yml.

Daily commands: make builds the binary to ./bin/wtf. Run with ./bin/wtf or wtfutil if installed. Configuration via ~/.config/wtf/config.yml (YAML format with sample files in _sample_configs/).

• main.go — Entry point for the WTF dashboard application; every contributor must understand the startup flow and initialization sequence.
• app/wtf_app.go — Core application manager that orchestrates modules, scheduling, and event loop; critical to understanding how modules are loaded and executed.
• app/widget_maker.go — Factory responsible for instantiating all module widgets; essential for adding new modules or modifying module initialization.
• cfg/config_files.go — Configuration file parsing and loading logic; required reading for understanding how YAML configs are validated and applied.
• app/scheduler.go — Scheduling engine that manages refresh intervals and concurrent module updates; critical for understanding performance and update timing.
• modules/airbrake/widget.go — Representative module widget implementation showing the standard pattern all modules must follow for rendering and keyboard interaction.

Add a New External API Module

1. Create module directory and client: mkdir -p modules/newservice and add modules/newservice/client.go with API authentication and data fetching (modules/newservice/client.go)
2. Define module settings and validation: create modules/newservice/settings.go extending cfg.CommonSettings with service-specific config fields (modules/newservice/settings.go)
3. Implement widget interface: create modules/newservice/widget.go implementing Refresh(), Focusable(), and HandleKeyboardEvent() methods (modules/newservice/widget.go)
4. Register module in widget factory: add case statement to app/widget_maker.go in MakeWidget() function mapping config type to NewWidget constructor (app/widget_maker.go)
5. Add keyboard handlers (optional): create modules/newservice/keyboard.go for custom key bindings and interactions (modules/newservice/keyboard.go)

Add a Configuration Option to All Modules

1. Add field to shared config struct: edit cfg/common_settings.go adding new field with YAML struct tags (cfg/common_settings.go)
2. Add validation rule (if needed): add validation function in cfg/validations.go checking the new setting (cfg/validations.go)
3. Update color theme if visual: modify cfg/default_color_theme.go if the setting affects colors or appearance (cfg/default_color_theme.go)
4. Document in example config: update _sample_configs/sample_config.yml with the new setting and description (_sample_configs/sample_config.yml)

Modify Module Refresh Behavior

1. Understand current scheduling: review app/scheduler.go to see how RefreshInterval is used and how goroutines are spawned (app/scheduler.go)
2. Adjust refresh logic in target module: edit modules/yourmodule/settings.go to change RefreshInterval or add conditional refresh rules (modules/airbrake/settings.go)
3. Implement custom refresh in widget: override refresh timing in modules/yourmodule/widget.go Refresh() method with conditional logic (modules/airbrake/widget.go)
4. Test scheduler interactions: verify in app/scheduler_test.go that timing behaves correctly with your changes (app/scheduler_test.go)

• Go 1.26.2 — Compiled binary provides fast startup and low memory footprint ideal for terminal dashboards; goroutines enable lightweight concurrent module refreshing
• YAML configuration — Human-readable format allows non-technical users to customize dashboard layout and module settings without code changes
• tcell/termbox library (implicit via dependencies) — Cross-platform terminal rendering with support for colors, positioning, and keyboard events
• Module plugin architecture — Decoupled module system allows independent development and testing of integrations with external services (Airbrake, Asana, Docker, etc.)
• Goroutine-based scheduler — Enables non-blocking concurrent refresh of multiple API-backed modules without blocking the UI event loop

• Synchronous module refresh with optional stale data display

  • Why: Simpler implementation and predictable UI updates without complex async state management
  • Consequence: Module latency is bounded by slowest API; no streaming updates, but acceptable for dashboard use case

• Grid-based layout with fixed positioning instead of responsive layout

  • Why: Simpler coordinate calculation and no reflow logic needed when terminal is resized
  • Consequence: Dashboard must be manually reconfigured for different terminal sizes; some modules may go off-screen if terminal is too small

• Per-module settings inheritance from CommonSettings rather than global defaults

  • Why: Allows fine-grained control per module while reducing boilerplate
  • Consequence: Configuration complexity increases; users must understand which settings apply globally vs. per-module

• No built-in caching layer for API responses

  • Why: Keeps architecture simple; each module manages its own cache if needed
  • Consequence: Repeated API calls if refresh interval is short; modules must implement rate-limiting independently

• Web-based dashboard interface (terminal-only)
• Real-time streaming updates (polling-based)
• Multi-user authentication or session management
• Data persistence or historical analytics
• Customizable module rendering (fixed widget types per module)
• Windows native support (Go cross-compilation assumed)

1. Each module requires specific API credentials (GitHub tokens, Jira URLs, PagerDuty keys, etc.) in the config file — missing credentials will silently fail module initialization unless caught by module_validator. 2) The scheduler respects refresh rates per module (config-driven), so slow APIs can block the display. 3) Terminal resizing requires specific tcell/tview handling in the display code. 4) Go 1.26.2 is a high version; check if your system supports it.

• Plugin/Module Architecture — wtfutil's extensibility comes from treating each integrated service (GitHub, Jira, Docker, etc.) as a pluggable module; understanding how modules are instantiated, configured, and scheduled is essential to adding new integrations
• Event-Driven Scheduling — The scheduler (scheduler.go) uses goroutines and channels to refresh modules concurrently on intervals; critical to understanding how the dashboard stays responsive while polling external APIs
• Configuration as Code (YAML) — All dashboard layout, modules, and API settings are defined declaratively in YAML files; understanding config parsing (cfg/config_files.go) is required to enable users to customize their dashboards
• Cross-Platform TUI Rendering (tcell) — wtfutil abstracts away terminal-specific rendering details via rivo/tview, which sits atop gdamore/tcell; understanding terminal cell-based layout is essential for layout bugs
• Factory Pattern (Widget Maker) — widget_maker.go instantiates the correct module type from config; a common pattern in wtfutil for decoupling module creation from application logic
• Goreleaser for Multi-Platform Distribution — wtfutil's .goreleaser.yml automates building and releasing binaries for macOS, Linux, Windows; understanding this is essential for maintainers but useful context for all contributors
• API Credential Management & Secrets — wtfutil stores sensitive API tokens in config files; understanding how to safely handle credentials (environment variable interpolation, config file permissions) prevents security issues

• avelino/awesome-go — Community-curated list of Go projects; wtfutil is featured as a prominent TUI/dashboard tool in the Go ecosystem
• rivo/tview — The underlying terminal UI library used by wtfutil for rendering richly formatted dashboards in the terminal
• cjbassi/ytop — Alternative terminal dashboard for system monitoring; shares similar architecture goals (single-view aggregation) but focuses on system metrics rather than external APIs
• nicolargo/glances — Python-based system monitoring dashboard; wtfutil's Go equivalent that extends to external service integrations beyond local system stats
• FelicianoTech/resume — Maintained by the same author; related to understanding the maintainer's broader work in the Go community

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 cfg/parsers.go

The cfg/parsers.go file handles critical configuration parsing logic but currently only has cfg/parsers_test.go. Given the complexity of parsing YAML configs across multiple modules and the variety of data types supported (colors, positions, durations, secrets), expanding test coverage would catch regressions early. This is especially important for a dashboard tool where misconfigured widgets can break the entire UI.

• [ ] Review cfg/parsers.go and cfg/parsers_test.go to identify untested parsing functions
• [ ] Add test cases for edge cases: invalid color formats, out-of-bounds positions, malformed duration strings, empty/null config values
• [ ] Add tests for secret parsing in cfg/secrets.go integration with parsers
• [ ] Run go test ./cfg -cover to verify coverage increase to >80%
• [ ] Update cfg/parsers_test.go with Table-Driven Tests pattern for maintainability

Add integration tests for app/scheduler.go in GitHub Actions workflow

The scheduler.go file manages widget refresh timing and is critical to WTF's core functionality, but only has unit tests in app/scheduler_test.go. The pr-checks.yml workflow doesn't include integration tests that verify scheduler behavior under realistic conditions (concurrent module updates, missed refresh windows, focus changes). This would catch race conditions and timing bugs that only surface in production.

• [ ] Review app/scheduler.go and app/scheduler_test.go to understand scheduling logic
• [ ] Create app/scheduler_integration_test.go with tests for: (1) concurrent module refresh, (2) scheduler pause/resume during focus changes, (3) rapid refresh interval changes
• [ ] Add a new GitHub Actions job to .github/workflows/pr-checks.yml that runs go test ./app -tags=integration -race
• [ ] Verify tests pass locally with go test -race ./app before committing
• [ ] Document test requirements in CONTRIBUTING.md

Add missing validation tests for cfg/position_validation.go with all module types

The cfg/position_validation.go file validates widget positioning (top, left, height, width), and while cfg/position_validation_test.go exists, it likely doesn't test against the full matrix of module configurations. Given the file structure shows many modules (_sample_configs/ has kubernetes, bargraph, dynamic_sizing examples), position validation should be tested with real module configs to prevent layout bugs where widgets overlap or exceed terminal bounds.

• [ ] Review cfg/position_validation.go and cfg/position_validation_test.go
• [ ] Identify all unique position configuration patterns in _sample_configs/ (bargraph_config.yml, kubernetes_config.yml, dynamic_sizing.yml, uniconfig.yml)
• [ ] Add parameterized tests in cfg/position_validation_test.go testing: (1) overlapping widget detection, (2) boundary violations, (3) dynamic resizing with child modules
• [ ] Run tests against all sample configs: go test ./cfg -v and verify coverage >85%
• [ ] Add regression test for any position-related bug reports from issues

• Add unit tests for app/display.go (visible in file list but not shown to have corresponding _test.go) to increase test coverage of the display rendering logic
• Improve error messages in app/module_validator.go to provide more actionable feedback when API credentials are misconfigured (e.g., which field is missing from config)
• Add example configs for popular use cases (e.g., a 'Kubernetes DevOps' template, 'GitHub-focused developer' template) to _sample_configs/ with inline YAML comments explaining each module's purpose

• High · Outdated Go Version in go.mod — go.mod. The project specifies 'go 1.26.2' which is not a valid Go version (Go versioning does not reach 1.26 as of the analysis timeframe). This likely indicates the go.mod file is corrupted or misconfigured, which could lead to unpredictable build behavior and potential security implications. Fix: Update go.mod to specify a valid Go version (e.g., 'go 1.21' or the appropriate current stable version). Run 'go mod tidy' to ensure consistency.
• High · Incomplete Dependency Declaration — go.mod (last line). The go.mod file ends with an incomplete dependency: 'github.com/zorkian/go-data' without a version specified. This incomplete entry could cause build failures and dependency resolution issues. Fix: Complete the zorkian/go-data dependency declaration with a proper version string and run 'go mod tidy' to validate all dependencies.
• High · Weak Security Vulnerability Reporting Process — SECURITY.md. The SECURITY.md file states security issues should be opened as regular Issues in the Issues tab. This is inadequate and exposes security vulnerabilities to public disclosure before they can be fixed. Best practices recommend a private disclosure process (e.g., security@domain.com or GitHub Security Advisory). Fix: Implement a responsible disclosure policy with a private security contact email or use GitHub's Security Advisory feature. Do not encourage public issue reporting for security vulnerabilities.
• Medium · Multiple Outdated and Potentially Vulnerable Dependencies — go.mod - Dependencies section. Several dependencies have known security issues or are significantly outdated: docker v28.5.2 (incompatible version marker), github.com/google/go-github/v32 (v32 is outdated), github.com/shirou/gopsutil v2.21.11 (incompatible, outdated from 2021), and others. These may contain known CVEs. Fix: Run 'go list -u -m all' to identify outdated packages. Update to the latest compatible versions. Use 'go mod graph' to identify transitive dependencies. Consider using GitHub Dependabot or Snyk for continuous vulnerability monitoring.
• Medium · Unvalidated External API Integration — Various modules importing external APIs (github.com/PagerDuty/go-pagerduty, github.com/zmb3/spotify, etc.). The codebase integrates with multiple external services (PagerDuty, Spotify, GitHub, Azure DevOps, DigitalOcean, Docker, Asana, etc.) through their APIs. Without visible authentication validation and certificate pinning, the application may be vulnerable to man-in-the-middle (MITM) attacks. Fix: Implement certificate pinning for critical external API calls. Validate all TLS certificates. Use environment-based credential management (never hardcode). Implement request signing where available. Add request/response logging for audit trails.
• Medium · Sensitive Configuration Handling — cfg/secrets.go. The presence of 'cfg/secrets.go' suggests the application handles secrets, but the security strategy is unclear. If secrets are logged or stored insecurely in configuration files, this poses a risk. Fix: Ensure secrets are never logged or printed. Use secure credential storage mechanisms. Implement secret rotation policies. Use environment variables or secure vaults (HashiCorp Vault, AWS Secrets Manager) instead of file-based storage. Add secret scanning in CI/CD.
• Medium · Missing Input Validation Framework — cfg/ directory. While 'cfg/validatable.go' and 'cfg/validations.go' exist, there is no evidence of comprehensive input validation across all modules. The application accepts configuration from users and external APIs without clear sanitization. Fix: Implement comprehensive input validation for all user-supplied configuration. Add schema validation for YAML config files. Sanitize all external API responses. Implement allowlisting where possible rather than blocklisting.
• Low · Using Incompatible Version Markers — undefined. Multiple dependencies use '+incompatible' version markers (e.g., github.com/docker/docker v28.5.2+incompatible), which bypass Go module versioning constraints Fix: undefined

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.