{"id":51110551,"url":"https://github.com/lucasepe/kctx","last_synced_at":"2026-06-24T17:01:48.614Z","repository":{"id":363277015,"uuid":"1252021413","full_name":"lucasepe/kctx","owner":"lucasepe","description":"A Kubernetes context engine for humans and AI agents.","archived":false,"fork":false,"pushed_at":"2026-06-22T07:51:26.000Z","size":9932,"stargazers_count":16,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T09:29:43.730Z","etag":null,"topics":["agent-workflows","cloud-native","context-engineering","developer-experience","golang","kubernetes","platform-engineering","sre"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lucasepe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["lucasepe"],"custom":["https://paypal.me/lucasepe71"]}},"created_at":"2026-05-28T05:51:13.000Z","updated_at":"2026-06-17T11:20:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lucasepe/kctx","commit_stats":null,"previous_names":["lucasepe/kctx"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/lucasepe/kctx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasepe%2Fkctx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasepe%2Fkctx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasepe%2Fkctx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasepe%2Fkctx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucasepe","download_url":"https://codeload.github.com/lucasepe/kctx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasepe%2Fkctx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34741320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-workflows","cloud-native","context-engineering","developer-experience","golang","kubernetes","platform-engineering","sre"],"created_at":"2026-06-24T17:01:47.658Z","updated_at":"2026-06-24T17:01:48.606Z","avatar_url":"https://github.com/lucasepe.png","language":"Go","funding_links":["https://github.com/sponsors/lucasepe","https://paypal.me/lucasepe71"],"categories":[],"sub_categories":[],"readme":"# kctx\n\n\u003e A small read-only Kubernetes context engine for humans, scripts, and AI agents.\n\n`kctx` turns Kubernetes API state into structured operational context.\n\nInstead of asking every operator, script, dashboard, or agent to reconstruct relationships from raw YAML, `kctx` exposes a compact model of:\n\n- **entities**: Pods, Services, workloads, Nodes, PVCs, ConfigMaps, Secrets, CRDs\n- **relations**: ownership, selection, scheduling, service routing, dependencies\n- **signals**: factual observations such as unhealthy Pods, missing endpoints,\n  warning Events, failed readiness, or degraded workloads\n- **graphs**: dependency and ownership views around supported resources\n- **dumps**: deterministic namespace snapshots for machines and incident review\n\nThe tool is intentionally conservative: it reads cluster state, normalizes facts, and avoids speculative root-cause claims.\n\nThe motivation, philosophy, and design argument behind `kctx` are covered in longer form here:\n\n- Leanpub book: [**Kubernetes Context Engineering**](https://leanpub.com/kubernetes-context-engineering)\n\n\n## What It Is For\n\nUse `kctx` when you want to answer questions like:\n\n- What owns this Pod?\n- Which Services route to these backends?\n- Why does this namespace look unhealthy?\n- What resources and signals should I attach to an incident?\n- What compact Kubernetes context should an AI agent receive before reasoning?\n- What does this supported CRD mean operationally right now?\n\n`kctx` is useful for SREs, platform teams, Kubernetes operators, CI/CD\ndiagnostics, internal tooling, MCP tools, and AI SRE workflows.\n\n## What It Is Not\n\n`kctx` is not:\n\n- a monitoring platform\n- a logging or metrics system\n- a dashboard suite\n- a remediation engine\n- a Kubernetes cluster manager\n- a graph database\n- an AI assistant\n- a replacement for `kubectl`\n\nIt does not mutate resources, restart workloads, apply manifests, or guess root cause.\n\n## Data Safety\n\n`kctx` avoids raw manifests, Secret data, ConfigMap data, raw environment variables, logs, and workload metrics. Metadata and Kubernetes messages that are returned by supported outputs pass through a small redaction policy for common secret-bearing keys and text patterns.\n\n## Quick Start\n\nInstall the CLI:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/lucasepe/kctx/main/install.sh | bash\n```\n\nThen run it against your current Kubernetes context:\n\n```bash\nkctx health namespace default\nkctx explain pod \u003cpod-name\u003e --namespace default\nkctx trace service \u003cservice-name\u003e --namespace default\nkctx graph pod \u003cpod-name\u003e --namespace default\nkctx dump namespace default\n```\n\n\n### Install `kctx serve` With Helm\n\nInstall the in-cluster read-only HTTP server from a packaged release chart:\n\n```bash\nVERSION=0.3.0\nhelm upgrade --install kctx \\\n  \"https://github.com/lucasepe/kctx/releases/download/v${VERSION}/kctx-${VERSION}.tgz\" \\\n  --namespace kctx-system \\\n  --create-namespace\n```\n\nThen expose it locally:\n\n```bash\nkubectl -n kctx-system port-forward svc/kctx 8080:8080\ncurl http://localhost:8080/health/namespace/default\n```\n\nSee [chart/README.md](chart/README.md) for chart values, local kind setup, and NodePort examples.\n\n### MCP/SSE release test guide\n\nThere is also an MCP/SSE release test guide for anyone who wants to try this with a local kind cluster, the released Helm chart, Online Boutique, ngrok, Codex, Claude Code, or ChatGPT Developer Mode:\n\nhttps://github.com/lucasepe/kctx/tree/main/docs/kctx-mcp-sse-release-test-guide.pdf\n\n## Commands\n\n`kctx explain`\n\nResolve structured context around one resource. Native Pod context is supported, and registered CRD adapters can provide ecosystem-specific context.\n\n```bash\nkctx explain pod api-xyz --namespace payments\nkctx explain applications.argoproj.io guestbook --namespace argocd\n```\n\n`kctx graph`\n\nBuild a graph around a supported resource. JSON is the default output; Mermaid and DOT renderers are available for graph-oriented views.\n\n```bash\nkctx graph pod api-xyz --namespace payments\nkctx graph pod api-xyz --namespace payments --render mermaid\nkctx graph applications.argoproj.io guestbook --namespace argocd --render dot\n```\n\n`kctx trace service`\n\nTrace a Service to EndpointSlices, endpoints, Pods, owners, Nodes, and factual service health signals.\n\n```bash\nkctx trace service payments-api --namespace payments\n```\n\n`kctx health namespace`\n\nProduce a compact namespace health snapshot.\n\n```bash\nkctx health namespace payments\n```\n\n`kctx dump namespace`\n\nExport a deterministic namespace context snapshot for automation, incident review, or AI-agent grounding.\n\n```bash\nkctx dump namespace payments \u003e payments-dump.json\n```\n\n`kctx serve`\n\nExpose the same context engine through a lightweight read-only HTTP API.\n\n```bash\nkctx serve\ncurl http://localhost:8080/health/namespace/default\n```\n\nRun the same engine as a local MCP server for AI agents:\n\n```bash\nkctx serve --mode mcp\n```\n\nRun it as an MCP HTTP/SSE server for controlled in-cluster or internal testing:\n\n```bash\nkctx serve --mode mcp-sse\n```\n\nSee [MCP.md](MCP.md) for tool details and [docs/mcp-sse](docs/mcp-sse/01-overview.md)\nfor the release-chart test guide with kind, Helm, ngrok, Codex, and Claude Code.\n\n## CRD Adapters\n\n`kctx` can fetch arbitrary Kubernetes resources through discovery, but it does not pretend that every custom resource can be understood generically.\n\nEcosystem-specific semantics belong in explicit adapters. An adapter can turn a CRD into the same core contract used everywhere else: resource identity, compact status, related entities, relations, signals, and optionally graph nodes and edges.\n\nThe current adapter set covers Argo CD `Application`, Argo CD `AppProject`, and cert-manager `Certificate` resources.\n\n## Documentation\n\nThe long-form documentation is organized as a [PDF eBook](docs/kctx.pdf).\n\n## Support\n\nIf `kctx` saves you time when debugging Kubernetes workloads, consider supporting\nits maintenance:\n\n- GitHub Sponsors: \u003chttps://github.com/sponsors/lucasepe\u003e\n- PayPal: \u003chttps://paypal.me/lucasepe71\u003e\n\nSupport helps fund release work, compatibility testing, documentation, and\nongoing Kubernetes, Argo CD, and cert-manager integration maintenance.\n\n## Project Status\n\n`kctx` is under active development. It is already useful as a read-only Kubernetes context tool, but production hardening is still in progress.\n\nSee [ROADMAP.md](ROADMAP.md) for current production-readiness work, planned features, and open design areas.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucasepe%2Fkctx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucasepe%2Fkctx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucasepe%2Fkctx/lists"}