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/GoogleCloudPlatform/kubectl-ai 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
• 16 active contributors
• Distributed ownership (top contributor 39% of recent commits)
• Apache-2.0 licensed
• CI configured
• ⚠ 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 GoogleCloudPlatform/kubectl-ai repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/GoogleCloudPlatform/kubectl-ai.

What it runs against: a local clone of GoogleCloudPlatform/kubectl-ai — 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 GoogleCloudPlatform/kubectl-ai | 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 main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 51 days ago | Catches sudden abandonment since generation |

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

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

# 4. Critical files exist
test -f "cmd/main.go" \\
  && ok "cmd/main.go" \\
  || miss "missing critical file: cmd/main.go"
test -f "gollm/interfaces.go" \\
  && ok "gollm/interfaces.go" \\
  || miss "missing critical file: gollm/interfaces.go"
test -f "gollm/factory.go" \\
  && ok "gollm/factory.go" \\
  || miss "missing critical file: gollm/factory.go"
test -f "cmd/mcp.go" \\
  && ok "cmd/mcp.go" \\
  || miss "missing critical file: cmd/mcp.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"

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

kubectl-ai is a Kubernetes CLI plugin written in Go that translates natural language user intent into precise kubectl commands and operations by leveraging LLM APIs (Gemini, VertexAI, OpenAI, Bedrock, Ollama, etc.). It makes Kubernetes management accessible to users who don't need to memorize complex kubectl syntax, handling interactive command execution and results interpretation through a TUI built with Bubble Tea. Monorepo using Go workspaces (go.work): cmd/ contains main.go and mcp.go entry points, gollm/ (referenced via local replace in go.mod) houses the shared LLM abstraction layer, docs/ contains deployment guides (gke-deployment.md, mcp-server.md), dev/tasks/ has deployment scripts (deploy-to-gke, deploy-to-kind). .github/actions/kind-cluster-setup and workflow scripts orchestrate testing against real K8s clusters.

DevOps engineers, platform engineers, and Kubernetes operators who want to query and manage their clusters using natural language instead of memorizing kubectl syntax. Also targets teams standardizing on GCP/Kubernetes infrastructure who want AI-assisted cluster navigation.

Actively developed and production-ready: lives in GoogleCloudPlatform org with structured CI/CD workflows (.github/workflows containing ci-presubmit.yaml, ci-periodic.yaml, release.yaml), comprehensive test coverage (cmd/mcp_test.go, mocking framework), and Krew distribution. Most recent activity involves MCP server/client modes and multi-model support (gemini, vertexai, azopenai, openai, grok, bedrock).

Moderate risk: depends on 10+ LLM provider SDKs (Azure OpenAI, AWS Bedrock, Anthropic, Google Cloud) creating wide attack surface and version mismatch potential; MCP server mode (mark3labs/mcp-go@0.41.1) is relatively new framework adoption. Single organization maintainer (GoogleCloudPlatform) means feature velocity depends on Google's resourcing, though codebase is well-organized with CI/CD preventing quick breakage.

Active expansion of LLM provider support (recent addition of bedrock.md docs, grok support in go.mod), MCP (Model Context Protocol) mode implementation as alternative to direct LLM calls (cmd/mcp.go with tests), and K8s evaluation benchmarking infrastructure (k8s-bench-evals.yaml workflow, dev/ci/periodics/analyze-evals.sh). Focus on making the tool work with any LLM backend.

Clone and build: git clone https://github.com/GoogleCloudPlatform/kubectl-ai && cd kubectl-ai && go build -o kubectl-ai ./cmd. Set API key: export GEMINI_API_KEY=your_key (or equivalent for other providers). Run: ./kubectl-ai or kubectl ai if installed via Krew. See CONTAINER.md for Docker build: make build-images (from dev/tasks/).

Daily commands: Presubmit validation: dev/ci/presubmits/go-build.sh, dev/ci/presubmits/go-vet.sh, dev/ci/presubmits/verify-format.sh. Local dev: go run ./cmd -h after setting GEMINI_API_KEY env var. Periodic evals: dev/ci/periodics/run-evals.sh against KIND cluster (spawned via .github/actions/kind-cluster-setup/action.yaml). Docker: build via .goreleaser.yaml config or manual docker build -f Dockerfile.

• cmd/main.go — Entry point for the kubectl-ai CLI tool; defines the command structure and orchestrates the AI-powered Kubernetes interaction flow.
• gollm/interfaces.go — Defines the LLM abstraction layer that all AI providers (OpenAI, Anthropic, Bedrock, Gemini, etc.) must implement; critical for supporting multiple AI backends.
• gollm/factory.go — Factory pattern implementation for instantiating the correct LLM provider based on configuration; essential for provider selection and initialization.
• cmd/mcp.go — Implements the Model Context Protocol server mode, enabling kubectl-ai to act as an MCP server for AI-powered tool integration.
• go.mod — Declares all external dependencies and module structure; required for understanding how gollm submodule and Kubernetes client-go are integrated.
• gollm/schema.go — Defines core request/response data structures for LLM interactions; foundational for understanding message formatting across all providers.

Add Support for a New LLM Provider

1. Create a new provider file in gollm/ (e.g., gollm/newprovider.go) that implements the Client interface from gollm/interfaces.go (gollm/interfaces.go)
2. Implement required methods: CreateMessage, GetChatCompletions, and any provider-specific initialization logic (gollm/openai.go)
3. Register the new provider in the factory by adding a case statement in gollm/factory.go with the provider name and instantiation logic (gollm/factory.go)
4. Add configuration environment variables and documentation in docs/mcp-server.md and docs/tools.md for users to configure the new provider (docs/mcp-server.md)
5. Create unit tests in gollm/newprovider_test.go following the pattern in gollm/openai_test.go (gollm/openai_test.go)

Add a New Kubernetes Tool or Command

1. Define the tool's schema and behavior in kubectl-utils/pkg/kube/client.go by adding a new method that wraps Kubernetes client-go calls (kubectl-utils/pkg/kube/client.go)
2. Create a tool definition file in docs/tool-samples/ (e.g., docs/tool-samples/mytool.yaml) documenting the tool's parameters and expected outputs (docs/tool-samples/gcloud.yaml)
3. Register the tool in the MCP server implementation (cmd/mcp.go) so it is exposed as an available tool to the LLM (cmd/mcp.go)
4. Update docs/tools.md with documentation and usage examples for the new tool (docs/tools.md)

Deploy kubectl-ai to a Kubernetes Cluster

1. Choose the appropriate manifest: use k8s/kubectl-ai.yaml for standard clusters, or k8s/kubectl-ai-gke.yaml for Google GKE (k8s/kubectl-ai.yaml)
2. Configure LLM provider credentials by editing the ConfigMap or Secret in the manifest to set environment variables like OPENAI_API_KEY (k8s/kubectl-ai-gke.yaml)
3. For sandbox/isolated deployments, use k8s/sandbox/ manifests which include RBAC configuration for restricted permissions (k8s/sandbox/cluster_role.yaml)
4. Apply the manifest using kubectl apply -f and verify deployment with kubectl logs to check for provider authentication errors (k8s/kubectl-ai.yaml)

• Go — Type-safe, compiled language ideal for CLI tools with minimal runtime dependencies; fast startup and cross-platform compilation via goreleaser
• gollm (custom abstraction layer) — Provides multi-provider LLM support without vendor lock-in; allows switching between OpenAI, Anthropic, Bedrock, Gemini, etc. with minimal code changes
• Kubernetes client-go — Official Go client for Kubernetes API; required for cluster discovery, resource queries, and executing kubectl commands programmatically
• Charmbracelet (bubbletea, lipgloss, glamour) — Modern TUI framework for rendering interactive terminal UI and markdown; provides responsive, accessible CLI experience with streaming output
• Model Context Protocol (MCP) — Standardized protocol enabling kubectl-ai to integrate with Claude and other MCP-compatible clients as a server; decouples kubectl-ai from specific AI provider UI
• Cobra — Industry-standard Go CLI framework used by kubectl and Docker; provides consistent command parsing, help generation, and flag management

• Single gollm abstraction layer for all LLM providers

  • Why: Reduces code duplication and avoids duplicating schemas, error handling, and request/response logic per provider
  • Consequence: Some provider-specific features (e.g., Claude's extended thinking, OpenAI's vision) must be either normalized into common schema or excluded; increases initial provider integration effort

• MCP server mode as separate from CLI mode

  • Why: Allows kubectl-ai to function both as a standalone CLI tool and as a backend service for other AI clients without architectural compromise
  • Consequence: Code paths for CLI vs. MCP mode are somewhat parallel; shared logic must be carefully extracted to avoid duplication

• Charmbracelet TUI libraries instead of custom rendering

  • Why: Leverages mature, well-tested libraries for terminal rendering, reducing bugs and maintenance burden; provides consistent styling across components
  • Consequence: Adds runtime dependency overhead and limits terminal compatibility to environments supporting the libraries' feature set

• kubectl-ai deployed as sidecar/pod in Kubernetes vs. local CLI

  • Why: Supports both local development (CLI mode) and cluster-integrated workflows (K8s deployment mode); flexible deployment options
  • Consequence: Must manage RBAC, service accounts, and permissions for both scenarios; increases operational complexity

• Does not provide real-time monitoring or alerting; focus is on query-response AI assistance
• Does not implement its own authentication/authorization; relies on Kubernetes RBAC and cluster credentials
• Does not support non-English languages in core functionality (documentation may reference i18n but implementation is primarily English)
• Does not handle persistent state or workflow orchestration; stateless request-response model
• Does not provide a web UI; TUI and MCP server are the primary interfaces

LLM API keys required at runtime (GEMINI_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_, AWS_ for Bedrock) — missing keys cause silent failures unless MCP mode is used. kubectl must be pre-installed and configured (kubeconfig in standard location). KIND cluster setup is required for CI tests but not documented for local dev (see .github/actions/kind-cluster-setup/action.yaml). Shell execution via mvdan.cc/sh parses but doesn't validate kubectl syntax before execution — bad LLM output may produce confusing K8s errors. MCP server mode requires external client support (Claude Desktop documented in docs/mcp-client.md) — doesn't work standalone.

• Model Context Protocol (MCP) — kubectl-ai implements both direct API mode and MCP server mode (cmd/mcp.go) to integrate with Claude Desktop; understanding MCP is necessary for maintaining the server implementation and extending protocol support
• Kubernetes Client-Go Library — Uses k8s.io/client-go (v0.34.2) for programmatic cluster interaction; needed to understand how kubectl-ai queries cluster state and submits operations beyond shell command execution
• Bubble Tea TUI Framework — Powers the interactive terminal UI (charmbracelet/bubbletea v1.3.5) for command preview, execution, and result display; required for implementing responsive CLI improvements
• Provider Strategy Pattern (LLM Abstraction) — gollm/ package abstracts LLM providers (Gemini, OpenAI, Bedrock, Ollama) behind common interface; critical architectural pattern for adding new LLM backends without changing cmd/main.go
• Shell AST Parsing (mvdan.cc/sh) — Uses mvdan.cc/sh v3.11.0 to parse and validate generated shell commands before execution; understanding AST validation prevents malformed kubectl commands from reaching the cluster
• Go Workspaces (go.work) — Repository uses Go 1.24 workspaces with local replace directive for gollm/ package; essential for local development without publishing intermediate packages to registries
• Cobra CLI Framework — cmd/main.go structures all CLI flags, subcommands, and provider selection via spf13/cobra v1.9.1; needed for adding new command-line features or provider options

• kubernetes/kubectl — Official kubectl binary that kubectl-ai wraps and executes; understanding kubectl plugin architecture is essential context
• openai/gpt-4-turbo-plugin-starter — Demonstrates plugin pattern for LLM-powered tools; similar multi-provider backend abstraction pattern
• jpmorganchase/cloud-blockchain-ethereum — Alternative Google Cloud integration example; shares GCP/Kubernetes deployment patterns (GKE focus in docs/gke-deployment.md)
• charmbracelet/bubbletea — Upstream TUI framework dependency (v1.3.5); understanding Bubble Tea architecture is critical for UI modifications
• modelcontextprotocol/servers — Official MCP server implementations reference; kubectl-ai's mcp.go implements same protocol for Claude integration

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 integration tests for MCP server functionality (cmd/mcp_test.go)

The repo has cmd/mcp_test.go but only cmd/mcp.go exists as the main MCP implementation. Given that docs/mcp-server.md and docs/mcp-client.md exist, there's clear MCP functionality that needs comprehensive testing. The current test file appears minimal. New contributors could add integration tests covering MCP server initialization, tool registration, and request/response handling.

• [ ] Review cmd/mcp.go to understand MCP server implementation details
• [ ] Review docs/mcp-server.md to understand expected MCP behavior
• [ ] Add unit tests for MCP server initialization and configuration
• [ ] Add tests for tool registration and discovery via MCP
• [ ] Add tests for error handling in MCP request processing
• [ ] Ensure tests use go.uber.org/mock for dependency mocking (already in go.mod)

Add provider-specific integration tests for gollm LLM providers

The gollm package contains implementations for multiple LLM providers (anthropic.go, openai.go, bedrock.go, gemini.go, grok.go, llamacpp.go, ollama.go, azopenai.go). Only anthropic_test.go and openai_test.go exist. Contributors could add comprehensive test coverage for the untested providers (Bedrock, Gemini, Grok, LlamaCpp, Ollama, AzOpenAI) to improve reliability across all LLM backends.

• [ ] Add gollm/bedrock_test.go with tests for AWS Bedrock initialization and API calls
• [ ] Add gollm/gemini_test.go with tests for Google Gemini API integration
• [ ] Add gollm/grok_test.go with tests for Grok API functionality
• [ ] Add gollm/llamacpp_test.go with tests for local LlamaCpp model handling
• [ ] Add gollm/ollama_test.go with tests for Ollama model API
• [ ] Add gollm/azopenai_test.go with tests for Azure OpenAI provider
• [ ] Use gollm/factory.go pattern to ensure factories are tested

Add workflow for testing against multiple Kubernetes versions

The repo uses k8s.io/* v0.34.2 (Kubernetes 1.34), but the .github/workflows only have ci-presubmit.yaml and ci-periodic.yaml without explicit K8s version compatibility testing. Given the KinD cluster setup action exists (.github/actions/kind-cluster-setup/action.yaml), contributors could create a new workflow testing kubectl-ai against multiple K8s versions (1.28, 1.29, 1.30, 1.31, 1.34) to ensure backward compatibility.

• [ ] Review .github/actions/kind-cluster-setup/action.yaml to understand cluster setup
• [ ] Create .github/workflows/k8s-compatibility.yaml (or extend existing workflow)
• [ ] Add matrix strategy testing against Kubernetes versions: 1.28, 1.29, 1.30, 1.31, 1.34
• [ ] Use kind-cluster-setup action with parameterized K8s version
• [ ] Run basic integration tests (similar to k8s-bench-evals.yaml) for each version
• [ ] Document results in contributing.md

• Add structured unit tests for gollm/bedrock.go provider implementation (currently only cmd/mcp_test.go has test coverage); model after OpenAI provider tests to ensure AWS Bedrock streaming and error handling work correctly
• Document the local development workflow for KIND cluster setup (currently only in .github/actions/); create dev/tasks/setup-kind-cluster.sh with reproducible steps and add to contributing.md with troubleshooting section
• Extend docs/tools.md with concrete examples for each tool (gcloud, gh, kustomize, argocd) showing how users can add custom tools; add validation/testing in dev/ci/presubmits/ to prevent tool definition regressions

• High · Outdated Go Toolchain Version — go.mod. The project specifies Go 1.24.0 with toolchain 1.24.3, which are very recent versions. However, the go.mod file should be regularly updated to use the latest stable Go version to ensure security patches are applied. Current specification may miss critical security updates in the Go runtime. Fix: Regularly update to the latest stable Go version. Implement automated dependency checking via Dependabot or similar tools to track Go version updates and security patches.
• High · Potential Credential Exposure in LLM Provider Integration — gollm/anthropic.go, gollm/openai.go, gollm/azopenai.go, gollm/bedrock.go, gollm/gemini.go, gollm/grok.go. The codebase integrates multiple LLM providers (OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Gemini, Ollama, Grok) through the gollm module. These integrations likely require API keys or credentials. The structure suggests potential for credential exposure if not properly handled via environment variables or secure secret management. Fix: Ensure all LLM provider credentials are exclusively managed through environment variables or secure secret management systems (e.g., Google Cloud Secret Manager, Kubernetes Secrets). Never hardcode API keys. Implement credential rotation policies and audit logging for credential access.
• High · Shell Execution via mvdan.cc/sh Package — go.mod (mvdan.cc/sh/v3 v3.11.0), cmd/main.go, cmd/mcp.go. The project depends on mvdan.cc/sh/v3 for shell script parsing. Combined with Kubernetes operations and tool execution capabilities, this could introduce shell injection vulnerabilities if user input is not properly sanitized before being passed to shell parsing or execution functions. Fix: Implement strict input validation and sanitization for all user-provided commands before they are processed by the shell parser. Use allowlists for permitted commands. Avoid shell execution where possible; use direct API calls instead. Audit all code paths that accept user input and pass it to shell operations.
• High · Kubernetes RBAC and Authentication Misconfiguration Risk — k8s/kubectl-ai-gke.yaml, k8s/kubectl-ai.yaml, k8s/sandbox/cluster_role.yaml. The project operates within Kubernetes clusters and manages kubectl operations. The k8s deployment manifests (k8s/*.yaml) may not enforce strict RBAC policies, network policies, or pod security standards, potentially allowing privilege escalation or unauthorized cluster access. Fix: Review and enforce strict RBAC policies with minimal required permissions. Implement Pod Security Standards (PSS), NetworkPolicies, and resource quotas. Use Pod Disruption Budgets. Audit and document all required permissions. Use least-privilege service accounts.
• Medium · Missing Input Validation on MCP Protocol Handler — cmd/mcp.go, cmd/mcp_test.go. The MCP (Model Context Protocol) implementation in cmd/mcp.go and cmd/mcp_test.go suggests handling external protocol messages. Without proper input validation, this could be vulnerable to protocol-based attacks or command injection through malformed MCP messages. Fix: Implement comprehensive input validation for all MCP protocol messages. Define strict schema validation using type assertions and bounds checking. Add rate limiting for MCP requests. Log and alert on malformed or suspicious messages.
• Medium · Potential HTTP Request Interception via gollm/http_journal.go — gollm/http_journal.go. The http_journal.go module likely logs HTTP requests/responses for LLM API interactions. This could inadvertently expose sensitive data such as API keys, user prompts, or response data in logs if proper filtering is not implemented. Fix: Implement strict filtering in HTTP journaling to exclude sensitive headers (Authorization, API keys) and potentially sensitive request/response bodies. Use log redaction techniques. Ensure logs are stored securely with appropriate access controls and retention policies.
• Medium · Dependency on Charmbracelet UI Libraries — undefined. The project uses charmbracelet libraries (bubbles, bubbletea, glamour, lipgloss) for terminal UI. These dependencies should be regularly audited, as terminal manipulation libraries can have security implications if they contain vulnerabilities that could affect user terminals or 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.