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/derailed/k9s 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 3w ago
• 26+ active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 54% 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 derailed/k9s repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/derailed/k9s.

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

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.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"

# 4. Critical files exist
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f ".golangci.yml" \\
  && ok ".golangci.yml" \\
  || miss "missing critical file: .golangci.yml"
test -f ".goreleaser.yml" \\
  && ok ".goreleaser.yml" \\
  || miss "missing critical file: .goreleaser.yml"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f ".github/workflows/test.yml" \\
  && ok ".github/workflows/test.yml" \\
  || miss "missing critical file: .github/workflows/test.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 48 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~18d)"
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/derailed/k9s"
  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).

K9s is a terminal UI (TUI) for Kubernetes cluster management written in Go, providing real-time monitoring and interaction with Kubernetes resources (pods, deployments, logs, etc.) without leaving the terminal. It replaces kubectl commands with an interactive ncurses-style interface that continuously watches the cluster and offers navigable views with built-in search, filtering, and resource management capabilities. Monolithic Go application with clear separation: TUI rendering layer (github.com/derailed/tcell/v2 and github.com/derailed/tview), Kubernetes API client layer (k8s.io/client-go, k8s.io/cli-runtime), and interactive view components likely organized under internal packages. CLI entrypoint via Cobra (spf13/cobra v1.10.2). Config files in .github/workflows/, Makefile for build orchestration, Dockerfile for containerized distribution.

DevOps engineers, Kubernetes cluster administrators, and SREs who spend hours in terminals managing multiple Kubernetes clusters and want to observe pod states, stream logs, manage deployments, and troubleshoot issues faster than typing kubectl commands repeatedly.

K9s is production-ready and actively maintained—it has 25+ release versions in the changelog, comprehensive GitHub Actions CI/CD pipelines (lint.yml, test.yml, stale-issues.yml), golangci linting configured, and a goreleaser setup for automated releases. The project is well-established with clear governance (Apache 2.0 licensed, Dependabot enabled, Semaphore CI). Single maintainer (derailed) but community-driven with active sponsorship model.

The dependency tree is large and pulls in security scanning tools (grype, syft, clio from Anchore) plus Helm, all Kubernetes client libraries, and terminal UI stack (tcell, tview) which expands attack surface—requires active monitoring of transitive dependencies via Dependabot. Single maintainer creates bus-factor risk for critical fixes. Go 1.25.8 is bleeding-edge which may introduce compatibility issues.

Recent activity visible: Dependabot actively monitoring 50+ dependencies (go 1.25.8 is very recent), GitHub Actions workflows for linting and testing on each PR, stale-issue/stale-PR automation enabled, security scanning integrated (Anchore grype/syft), and Semaphore CI as secondary pipeline. No specific milestone visible in provided data but release cadence appears consistent.

git clone https://github.com/derailed/k9s.git
cd k9s
make build
./k9s

The Makefile will handle Go build. Ensure go 1.25.8 is installed and KUBECONFIG points to a valid Kubernetes cluster.

Daily commands:

make build
./k9s

Or directly: go run ./main.go. Requires active kubeconfig context. For Docker: docker build -f Dockerfile . && docker run -v ~/.kube:/root/.kube ... (mounts kubeconfig).

• main.go — Application entry point; every contributor must understand how k9s initializes and bootstraps the CLI and UI framework.
• .golangci.yml — Linting configuration that enforces code standards; contributors must comply with these rules in all submissions.
• .goreleaser.yml — Release pipeline configuration; critical for understanding versioning, artifact generation, and deployment strategy.
• Makefile — Build and development workflow; required reading for setting up local environment and running tests.
• .github/workflows/test.yml — CI/CD test pipeline definition; explains how code is validated and what tests must pass before merge.
• go.mod — Dependency manifest; critical for understanding third-party libraries, particularly Kubernetes client, tcell/tview UI, and security scanning tools.

• CLI Bootstrap (main.go) (Go, adrg/xdg (config paths), Kubernetes client-go) — Parse command-line flags, load kubeconfig, initialize Kubernetes client, create TUI app, and enter event loop
  • Failure mode: If kubeconfig is invalid or unreachable, app fails to start with clear error message
• Terminal UI Framework (derailed/tview + tcell) (derailed/tview, derailed/tcell/v2, fatih/color) — Render interactive tables, panels, and modals; handle keyboard/mouse input; update display on resource changes
  • Failure mode: Terminal corruption or unresponsive UI if rendering conflicts occur; graceful degradation for unsupported terminal types
• Kubernetes Resource Sync (Kubernetes client-go (informers/watchers), fsnotify (for config) — Watch Kubernetes API for resource changes (Pods, Deployments, etc.); maintain in-memory cache; trigger UI updates

Add a New Kubernetes Resource View

1. Define a new resource type handler following the k9s view pattern (inherits from base View) (main.go)
2. Register the view in the router/dispatcher during app initialization (main.go)
3. Implement Kubernetes client calls using official client-go library (specified in go.mod) (go.mod)
4. Add keyboard keybindings and event handlers for view interactions (main.go)

Add a Security Scanning Feature

1. Import grype and syft libraries from anchore (already in go.mod dependencies) (go.mod)
2. Implement scanning logic to analyze images or manifests (main.go)
3. Add UI view component to render vulnerability findings (main.go)
4. Update linting rules in .golangci.yml if introducing new patterns (.golangci.yml)

Release a New Version

1. Update version in go.mod or version constant in code (go.mod)
2. Create changelog entry in change_logs/ directory (change_logs/release_0.12.0.md)
3. Commit and tag release following semantic versioning (Makefile)
4. goreleaser automatically publishes binaries to GitHub releases (.goreleaser.yml)
5. Verify CI pipeline (lint, test) passes in GitHub Actions (.github/workflows/test.yml)

Modify Code Quality Standards

1. Update golangci-lint rules to enforce new linting checks (.golangci.yml)
2. Update CodeBeat thresholds if changing quality metrics (.codebeatsettings)
3. Run local lint checks via Makefile target (Makefile)
4. Ensure all contributions pass automated linting in CI (.github/workflows/lint.yml)

• Go 1.25.8 — Cross-platform compilation to single binary; fast execution and minimal dependencies for CLI tooling
• derailed/tview and derailed/tcell — Terminal UI libraries enabling rich interactive dashboards and keyboard-driven navigation in the terminal
• Kubernetes client-go — Official Kubernetes API client; enables cluster communication, resource watching, and CRUD operations
• anchore/grype and anchore/syft — Container image vulnerability scanning and software bill of materials (SBOM) generation for security features
• itchyny/gojq — JQ query support for filtering and transforming Kubernetes resource JSON output interactively
• fsnotify — File system watching for configuration changes (kubeconfig, skin files) without polling

• Terminal-based UI instead of web dashboard

  • Why: Faster, zero-dependency deployment; works over SSH; direct keyboard control without browser overhead
  • Consequence: Limited to terminal-capable environments; no multi-user shared dashboard; rendering complexity tied to terminal capabilities

• Pull-based resource watching via client-go instead of custom webhooks

  • Why: Leverage official Kubernetes API; no webhook infrastructure required; works with all clusters
  • Consequence: Slightly higher API server load; eventual consistency model rather than push notifications

• In-process vulnerability scanning (Grype) versus external SaaS

  • Why: Air-gap compatibility; no credential sharing; full data privacy; part of the k9s binary
  • Consequence: Scanning performance depends on local resources; vulnerability database must be bundled or synced

• Single-user local binary instead of cluster-installed service

  • Why: No cluster-level installation; works from any machine with kubeconfig; minimal RBAC surface
  • Consequence: Each user runs their own instance; no shared audit logs or centralized control

• Multi-user centralized dashboard (k9s is a single-user terminal tool)
• Web-based UI (terminal-only tool by design)
• Cluster installation as a service (runs as a client binary)
• Custom authentication/RBAC enforcement (delegates to Kubernetes cluster RBAC)
• Real-time event streaming API (uses Kubernetes watch API polling)
• Persistent state/history across sessions (stateless CLI invocation model)

1. XDG Base Directory Compliance: K9s uses adrg/xdg (v0.5.3) so config lives in ~/.config/k9s, not ~/.k9s—environment variables XDG_CONFIG_HOME, XDG_CACHE_HOME, XDG_DATA_HOME affect paths. 2) Kubeconfig requirement: Must have valid kubectl context configured; K9s won't bootstrap—ensure KUBECONFIG env var points to accessible cluster. 3) Keyboard input: TUI heavily keyboard-driven with vim keybindings likely—mouse interaction may be limited despite tcell support. 4) Goreleaser signing: .goreleaser.yml may require GPG keys for signing releases; local builds skip this but CI expects it. 5) Go version pin: go 1.25.8 is cutting-edge; older toolchains will fail module resolution.

• Watch API and client-go Informers — K9s's continuous cluster monitoring relies on Kubernetes Watch API; understanding client-go's Informer pattern is essential for adding new resource types or optimizing sync logic
• Terminal Control Sequences (ANSI escape codes) — The tcell/v2 and tview libraries wrap ANSI codes for color, cursor positioning, and widget rendering; understanding this is critical when debugging TUI rendering issues or customizing themes
• Kubeconfig Context and RBAC — K9s respects RBAC policies from the active kubeconfig context; visibility and permissions depend on the authenticated user's cluster roles—critical for multi-tenant environments
• XDG Base Directory Specification — K9s uses adrg/xdg to conform to XDG standard for config/cache/data paths; understanding this explains where K9s config, skins, and state files live vs traditional ~/.k9s
• Container Image Scanning with Syft/Grype — K9s integrates Anchore's syft (SBOM generator) and grype (vulnerability scanner) for image inspection; understanding this enables the vulnerability scanning view
• Fuzzy String Matching — K9s search uses sahilm/fuzzy library for fast substring matching across resources; understanding this algorithm improves search relevance and filtering logic
• Helm Chart Metadata and Repositories — K9s can list and interact with Helm releases; understanding Helm chart structure and the Helm client API (helm.sh/helm/v3) is needed for the Helm view

• kubernetes/kubernetes — The upstream Kubernetes project; K9s depends on k8s.io/* client libraries and must track API changes
• kubernetes-sigs/kubebuilder — Alternative Kubernetes-native development tool; solves CRD/operator definition vs K9s cluster management angle
• derailed/popeye — Sibling project by same maintainer; static Kubernetes cluster analyzer that K9s can invoke for security/best-practice audits (referenced in assets/popeye/)
• helm/helm — Kubernetes package manager that K9s integrates with (helm.sh/helm/v3 dependency); K9s provides TUI for Helm release inspection
• anchore/grype — Vulnerability scanner that K9s bundles for container image scanning; anchore/clio and anchore/syft are direct dependencies

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 k9s configuration loading and validation

The repo has extensive configuration handling (evidenced by .golangci.yml, .goreleaser.yml, go.mod with yaml support), but the test.yml workflow and test patterns appear minimal. k9s loads config from XDG directories (xdg dependency present) and manages multiple resource types. Adding unit tests for config parsing, validation, and merging would catch regressions in config handling across releases and improve maintainability for contributors.

• [ ] Identify config loading code in internal/config/ or cmd/ directories
• [ ] Create internal/config/*_test.go files with tests for YAML parsing, XDG path resolution, and config validation
• [ ] Add tests for edge cases: missing config files, malformed YAML, invalid kubeconfig paths
• [ ] Ensure tests are integrated into .github/workflows/test.yml and report coverage
• [ ] Document config testing patterns in CONTRIBUTING guide

Add GitHub Actions workflow for Go version compatibility testing

The go.mod specifies go 1.25.8, but the .github/workflows only include lint.yml and test.yml. There's no explicit workflow testing against multiple Go versions (1.21, 1.22, 1.25+) or checking for deprecation warnings. Given k9s' complexity with Kubernetes client-go and complex dependencies, adding a matrix test workflow would ensure compatibility and catch breaking changes early.

• [ ] Create .github/workflows/go-matrix-test.yml with Go version matrix (1.21, 1.22, 1.23, 1.24, 1.25)
• [ ] Configure workflow to run 'go test ./...' and 'go vet ./...' across versions
• [ ] Add 'go mod tidy' validation to catch dependency drift
• [ ] Configure to run on pull requests and scheduled daily basis (reference .github/workflows/test.yml structure)
• [ ] Document in README.md or CONTRIBUTING.md minimum supported Go version

Add integration tests for k9s resource viewers (pods, deployments, helm charts)

The assets/ and change_logs/ suggest k9s has many resource view types (k9s_helm.png, k9s_popeye.png indicate multiple viewers), but there's no dedicated integration test suite. The codebase depends heavily on k8s.io/client-go and k8s.io/metrics, making integration tests against a kind cluster or mock Kubernetes API valuable. This would catch breaking changes in resource rendering and interaction logic.

• [ ] Create .github/workflows/integration-test.yml using kind (Kubernetes in Docker) to spin up test cluster
• [ ] Add internal/integration_test/ directory with tests for core resource viewers (pods, deployments, services)
• [ ] Test resource list rendering, filtering, and actions (delete, describe, logs) against mock K8s cluster
• [ ] Include tests for helm chart viewer (given helm.sh/helm/v3 dependency and k9s_helm.png asset)
• [ ] Configure workflow to run on pull requests and cache kind images for speed

• Add missing unit tests for internal view components—many TUI rendering functions in internal/ likely lack Go test coverage given the 1.6K lines of Go code; start by creating *_test.go files mirroring existing view handlers.
• Document xdg-config layout: Create a doc file explaining how K9s uses XDG Base Directory spec (where configs, caches, data go), since this is non-obvious for kubectl users expecting ~/.k9s.
• Add integration test for Helm view—go.mod includes helm.sh/helm/v3 but no visible helm-specific test file; create a test that mocks Helm API calls and verifies K9s can list/inspect Helm releases.

K9s has a moderate security posture with several areas requiring attention. The primary concerns are insecure artifact downloads in Docker builds, outdated base images, and version mismatches between build configuration and source. The project properly includes security scanning tools in dependencies but lacks evidence of active vulnerability scanning in CI/CD pipelines. The large dependency tree (especially Anchore tools) increases attack surface and requires robust dependency management. Recommended immediate actions: (1) Implement checksum verification for kubectl

• High · Insecure kubectl Download in Dockerfile — Dockerfile, line with 'curl -f -L https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/${TARGET_ARCH}/kubectl'. The Dockerfile downloads kubectl binary from dl.k8s.io using HTTP without verifying checksum or signature. An attacker on the network could perform MITM attacks to inject malicious kubectl binary. The curl command uses -f -L flags but lacks integrity verification. Fix: Verify the downloaded kubectl binary using SHA256 checksum or GPG signature. Example: Download the corresponding sha256 checksum file and validate before use.
• High · Outdated Alpine Base Image — Dockerfile, FROM alpine:3.23.3. The final stage uses Alpine 3.23.3 which may contain known vulnerabilities. Security patches are frequently released and older versions accumulate CVEs. Fix: Use the latest stable Alpine version and implement regular image updates. Consider using alpine:3.latest or establish a regular patching schedule.
• Medium · Go Version Mismatch — go.mod (go 1.25.8) vs Dockerfile (golang:1.25.5-alpine3.21). go.mod specifies go 1.25.8 but Dockerfile uses golang:1.25.5-alpine3.21. Version inconsistency between development and build can cause unexpected behavior or security issues. Fix: Align Go versions between go.mod and Dockerfile to ensure consistent builds. Use golang:1.25.8-alpine3.21 in Dockerfile.
• Medium · Missing SBOM and Vulnerability Scanning — .github/workflows/test.yml (if present, but not fully visible). While Anchore Syft and Grype are in dependencies (for internal use), there's no evidence of automated vulnerability scanning in CI/CD pipelines for the final Docker image or Go dependencies. Fix: Implement automated vulnerability scanning using tools like Trivy or Grype in GitHub Actions CI/CD pipeline. Add SBOM generation and scanning steps.
• Medium · No Explicit Security Headers in Docker Config — Dockerfile - missing security directives. The Dockerfile does not implement security best practices such as running as non-root user, using read-only filesystems, or setting resource limits. Fix: Add USER directive to run as non-root. Implement read-only root filesystem where possible. Document recommended security context for Kubernetes deployments.
• Low · Transitive Dependency Risk — go.mod - indirect dependencies. The project has numerous transitive dependencies (anchore/grype, anchore/syft with 0.110.0 and 1.42.3 versions). These represent a large attack surface that requires regular monitoring. Fix: Implement dependabot automated updates (.github/dependabot.yml exists). Run 'go mod tidy' and 'go list -u -m all' regularly. Consider using go mod graph analysis tools.
• Low · Public Repository Exposure — GitHub repository - github.com/derailed/k9s. As a public OSS project on GitHub, the repository is exposed to potential code analysis attacks. While transparency is valuable, sensitive patterns should be protected. Fix: Implement secret scanning using GitHub's native tools. Use pre-commit hooks to prevent credential commits. Regularly audit for accidentally committed secrets.
• Low · Missing License File Integration — Makefile and CI/CD configuration. While COPYING and LICENSE files exist, there's no evidence of license compliance checking for dependencies in the build process. Fix: Integrate license compliance tools (like go-license-detector or licensefinder) into CI/CD to ensure all dependencies comply with acceptable licenses.

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.