# kstack

> A skill pack for Claude Code and other AI agents that enables intelligent monitoring, troubleshooting, and auditing of Kubernetes clusters using natural language.

Kstack is an open-source skill pack for Claude Code and compatible AI agents that brings AI-powered Kubernetes operations to your terminal. Built by the Kubetail organization and released under the Apache License 2.0, it installs a set of slash-command skills that let you monitor cluster health, investigate failures, fetch logs, and run security and cost audits — all through natural language. The project reached its initial v0.1.0 release in May 2026.

## What It Is

Kstack is a collection of agent skills — structured prompt-plus-script bundles — that extend AI coding agents like Claude Code, OpenAI Codex CLI, Cursor, and others with Kubernetes-specific capabilities. Rather than asking a general-purpose AI to reason about raw `kubectl` output, kstack pre-processes cluster data using purpose-built tools (Kubetail, Helm, Trivy, Pluto, Cilium, Istio integrations) and sends compact, structured results to the model. This keeps responses fast and token-efficient while giving the agent richer context than raw shell output would provide.

## Skills and Capabilities

Kstack organizes its skills into four categories:

- **Monitoring**: `/cluster-status` delivers a dense health snapshot covering node conditions, pod aggregates, and a ranked top-issues list; `/events` surfaces recent cluster events grouped by reason and ranked by severity, collapsing chatty normal events into summary lines.
- **Troubleshooting**: `/investigate` runs a root-cause analysis bundle across events, logs, and related resources; `/logs` opens a shared tmux session where natural language is translated into Kubetail queries; `/metrics` fetches CPU, memory, and resource metrics from metrics-server or Prometheus; `/exec` provides an AI-powered `kubectl exec` with support for ephemeral debug containers and privileged node shells.
- **Audits**: `/audit-security` reviews RBAC, pod security posture, and privilege tightening; `/audit-network` checks NetworkPolicy, Service, Ingress, Gateway API, DNS, and encryption; `/audit-cost` identifies over-provisioned and idle workloads; `/audit-outdated` scans for version drift, known CVEs (with CISA KEV status), and available upgrades.
- **Miscellaneous**: `/cleanup` removes all kstack-owned cluster resources; `/forget` wipes local cache and learned state.

All skills are read-only by default — any mutation requires explicit user confirmation. Skills with destructive potential (`/exec`, `/cleanup`, `/forget`) ship with `disable-model-invocation: true`, meaning the agent cannot invoke them autonomously.

## Multi-Agent Support

Although kstack is marketed primarily for Claude Code, the curl-based installer auto-detects which agent CLIs are present on `$PATH` and installs skills for each. Supported agents include OpenAI Codex CLI, OpenCode, Cursor, Factory Droid, Slate, Kiro, Hermes, and Pi. Both global (`~/.config/kstack/`) and project-local installs are supported, and the `--agent` flag lets users target a specific agent.

## Architecture and Design Tradeoffs

Kstack's core design principle is token efficiency: instead of piping full `kubectl` JSON through the model, each skill runs a shell script that fans out API calls in parallel, writes results to a per-context cache, and passes only the aggregated summary to the AI. Follow-up questions are answered by reading the cache with `jq` rather than re-querying the cluster. This approach reduces latency and cost but means some answers reflect cached state — skills expose `--refresh` and `--ttl` flags to control staleness. RBAC checks in `/audit-security` are explicitly documented as static (what roles grant, not what subjects actually use), and the audit-cost skill always states its data source and lookback window so users can calibrate confidence.

## Update: v0.1.0 Initial Release

The project was created on May 6, 2026, and published its first release, v0.1.0, on May 8, 2026. The repository is primarily written in Shell, hosted under the `kubetail-org` GitHub organization, and lists agents, AI, Claude Code, Kubernetes, monitoring, observability, and troubleshooting as its topic tags. The project notes inspiration from Garry Tan's `gstack`. Active development is ongoing, with CI running the full test suite on Ubuntu, macOS, and Windows for every pull request.

## Features
- Cluster health snapshot with ranked issue list
- Event monitoring grouped by severity
- Root-cause investigation across events, logs, and resources
- AI-powered log fetching via natural language with tmux session sharing
- CPU, memory, and resource metrics from metrics-server or Prometheus
- AI-powered kubectl exec with ephemeral debug container support
- RBAC and pod security posture audit
- NetworkPolicy, Service, Ingress, and DNS audit
- Cost and resource waste analysis
- Outdated components and CVE scanning with CISA KEV status
- Multi-agent support (Claude Code, Codex CLI, Cursor, OpenCode, and more)
- Global and project-local install modes
- Per-context caching with configurable TTL
- Read-only by default with explicit confirmation for mutations
- Auto-upgrade notifications and one-command upgrade

## Integrations
kubectl, Kubetail, Helm, Trivy, Pluto, Cilium, Istio, Prometheus, metrics-server, CoreDNS, tmux, Claude Code, OpenAI Codex CLI, Cursor, OpenCode, Factory Droid, Kiro

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
v0.1.0

## Links
- Website: https://kstack.sh
- Documentation: https://kstack.sh/concepts/installation
- Repository: https://github.com/kubetail-org/kstack
- EveryDev.ai: https://www.everydev.ai/tools/kstack