An experiment in building a two-panel Kubernetes TUI entirely with AI. Inspired by Midnight Commander, powered by Go 1.27, Bubble Tea v2, and controller-runtime informers.
⚠️ Vibe-coded warning: this project is 100 % AI-authored. No human has reviewed the code, so expect sharp edges, missing affordances, and sudden regressions. SeeTODO.mdfor the evolving plan.
- Kubectl-compatible startup intents:
kc get ...andkc logs ...parse familiar CLI syntax and launch directly into the matching folders, multi-selecting objects and opening manifest/log viewers when requested (docs/designs/cli-intents.md). - Hierarchy-first navigation: resource groups → object folders → virtual subfolders (pod containers, ConfigMap/Secret keys, etc.). Every row is keyed by full
group/version/resource. - Child object hierarchies: drill from parents into their children (e.g., Deployments → ReplicaSets → Pods, Services → EndpointSlices) via per-object child folders so related resources stay discoverable in the tree.
- Live data via informers: controller-runtime caches back all folders; add/update/delete events keep selections and scroll offsets stable.
- CPU and memory usage: when the cluster serves
metrics.k8s.io(metrics-server), pod lists showCPU,MEM,%CPU/R(of requests) and%MEM/L(of limits), and node lists showCPU,%CPU,MEMand%MEM(of allocatable). Wide mode adds%CPU/Land%MEM/Rfor pods andCPU/AandMEM/Afor nodes. kc reads the metrics every 15 seconds, only while such a list is on screen and no dialog is open.n/ameans no metrics for the object yet, no request or limit to compare with, or metrics kc may not read. - Two synchronized panels: each panel can render lists or manifest viewers, supports multi-selection, per-panel options (columns/order/modes), and an integrated function-key bar. A 2-line terminal lives underneath for quick kubectl work.
- Rich viewers: YAML/text viewer with syntax highlighting, wrap toggle, and an mc-style search dialog (
F7: normal, regular expression or wildcard search, case sensitive, backwards, whole words;n/Shift+F7for the next match). Logs viewer streamskubectl logswith follow mode, search, and End-to-follow shortcuts;F2sets tail lines, the since window, timestamps and the previous container instance, and restarts the stream. A container that restarted also gets alogs (previous)row. - Container internals: each pod container exposes
/logsplus a/rootbrowser so you can inspect container filesystems from kc. When images lack shell tooling, kc can spin up a debug helper automatically. - Local exports: any resource that supports
F3viewing (YAML, logs, ConfigMap/Secret data, pod filesystem files, etc.) can be saved locally viaF5with an inline directory+path picker. kc writes the export to a temporary file next to the destination and replaces the destination only when the whole content arrived, so a failed export leaves an existing file as it was. New files are created with mode 0600; a replaced file keeps its owner permissions and loses group and other access. kc refuses to write through a symbolic link. Binary ConfigMap and Secret keys show their size, detected content type and a hex dump inF3;F5saves the original bytes. - Config + persistence:
~/.kc/config.yamlcontrols viewer theme, panel widths, table modes, discovery TTL, mouse preferences, and more. In the option dialogs,Enterapplies a change to the current session andC-ssaves it as the default.
go run ./cmd/kcPrefer a compiled binary?
go build -o kc ./cmd/kc
./kcbrew tap sttts/homebrew-kc
# macOS (notarized GUI build)
brew install --cask sttts/homebrew-kc/kc
# Linux / CLI-only formula
brew install sttts/homebrew-kc/kcBinaries are published by the maintainers via GitHub Releases and the Homebrew tap. Push a v* tag to trigger the Goreleaser workflow, which builds/signed binaries, publishes the GitHub Release, notarizes the macOS artifacts, and refreshes the Homebrew tap. See docs/RELEASING.md for the Apple signing credentials required for CI.
Kubernetes Commander accepts a subset of kubectl syntax so you can jump straight to the desired view:
kc get pods– focuses the Pods list for the current/flagged namespace.kc get deploy myapp -o yaml– highlightsmyapp, opens the manifest viewer in the opposite panel.kc get pods/nginx pods/api svc/frontend– multi-selects rows across resources.kc logs payments-0 -c worker --follow– drills down to the pod → container → logs row and opens the streaming viewer.
All commands honor -n/--namespace; when omitted, kc uses the kubeconfig’s default.
| Key | Action |
|---|---|
F1 |
Help – opens the README.md markdown viewer (windowed modal). |
F2 |
Options – context-aware panel options or viewer theme dialog. |
F3 |
View – YAML viewer, ConfigMap/Secret key viewer, pod logs viewer, etc. Closes the viewer again. |
F4 |
Edit – launches kubectl edit for the selected Kubernetes object. |
F5 |
Copy – download the current YAML/log/log/file to the local filesystem. |
F7 |
Create namespace (panels) / Search dialog (viewers/logs). |
F8 |
Delete – confirms the object and its context, then deletes that instance only (UID precondition); a replaced or already deleted object is reported and left alone. |
F9 |
Menu – Built-in object actions and custom commands. |
F10 |
Quit (Esc+0 alternative; C-q also exits). |
Tab |
Switch panels. |
C-o |
Toggle the integrated terminal. |
C-s |
Quick search, as in mc: type to jump to the first row whose name starts with the text (case-insensitive); C-s again goes to the next match, Backspace removes a character, Esc ends the search, and any other key ends it and does its usual job (Enter opens the found row). M-s and Esc s do the same. |
M-a |
In viewers: copy the whole content. |
M-c |
Copy the kubectl command shown above the shell line (the command that lists the active panel). Esc c does the same where Option does not act as Meta. Locally kc uses pbcopy, wl-copy, xclip or xsel; over SSH it sends OSC 52 (allow clipboard access in your terminal); inside tmux it also fills the tmux buffer. |
C-c |
Quit. |
Viewers show the kubectl command that prints the same content on their last line; M-c or the clipboard button copies it. Drag with the left mouse button to select text; releasing copies the selection, a click or Esc clears it.
Function keys are also reachable via Esc+<digit> (e.g., Esc+3 for F3). In viewers, F3, F10 and Esc close the viewer; a lone Esc closes it once the Esc timeout expires, so Esc+<digit> keeps working. Unimplemented slots (F6) are hidden/disabled until their workflows land.
Each panel has a namespace scope, shown at the left of its bottom border next to the context (mba : default). The panel root lists the resource types of that scope, then namespaces and the cluster-scoped types. Click the namespace to pick another one, or "All namespaces" (like kubectl -A). Lists across all namespaces get a Namespace column; resource counts are skipped there, because counting would watch every object in the cluster. /namespaces/<name> still works for browsing a namespace without changing the scope. Click the context name to switch kc to another kubeconfig context; both panels then show that cluster, starting in the context's namespace. The scope and the context are kc state only; kubeconfig is never changed.
Everything kc starts runs against the context and identity the panels show: the integrated shell, F4 (kubectl edit) and custom commands. --as, --as-uid and --as-group are applied on top of the context's own credentials (token, client certificate or exec plugin). F4 passes them as kubectl flags. The shell and custom commands get KUBECONFIG pointing at a kubeconfig that kc generates in a private temp directory (mode 0600) and removes on exit. With terminal.mode: overlay (the default) that file only sets the current context, the namespace and, when you impersonate, the user entry, and your own kubeconfig files follow it in KUBECONFIG; with terminal.mode: copy it is a full copy of the file that defines the context. The shell keeps the same KUBECONFIG path for its whole life, so it follows context and namespace changes from its next command on. terminal.follow: false leaves the shell's environment alone.
With nodeShell.enabled: true (optionally limited to nodeShell.contexts), entering a node shows Start a node shell... under /pods. Enter opens a red confirmation that names the context, node, namespace, pod and image and shows a similar kubectl debug node/... command. After Start, kc creates a privileged pod on the node (nodeName, host PID, network and IPC namespaces, tolerating every taint) and opens a root shell in the host namespaces (nsenter -t 1 -m -u -i -n -p) full screen. exit or C-] ends the shell; kc then deletes the pod, and also when kc quits. While the shell is open kc keeps a second exec stream as a heartbeat; if kc dies, the pod stops about a minute later, and after nodeShell.maxDuration in any case. A stopped pod stays as a Completed object; leftovers carry the label app.kubernetes.io/component=kc-node-shell. Pod security admission must allow privileged pods in nodeShell.namespace (pod-security.kubernetes.io/enforce=privileged); otherwise the create fails and kc shows the error.
The F9 menu starts with built-in actions for the selected object, above the custom commands. Each action opens a red confirmation dialog that names the context, namespace and object and shows the equivalent kubectl command.
For CronJobs (batch/v1):
- Run now... creates a Job from the CronJob's job template, like
kubectl create job --from=cronjob/<name>. The Job is named<cronjob>-manual-<suffix>, carries thecronjob.kubernetes.io/instantiate: manualannotation and is owned by the CronJob. The other panel then shows the new Job. - Suspend/Resume... sets
spec.suspend. The dialog says which of the two it does.
An action is hidden when the resource does not offer the API verb it needs (patch for Suspend/Resume).
You can define custom shell commands in ~/.kc/config.yaml and execute them via the F9 menu. Commands run in a terminal panel and can use templates to reference the selected item.
By default, kc ships with Top Nodes (global) and Top Pods (namespace-scoped) until you define your own commands.
commands:
- name: "Top Pods"
command: "kubectl top pods -n {{.Namespace}}"
type: "namespace" # Sticky for the current namespace
watchInterval: 5s
showFor:
resources: ["pods"]
- name: "Top Nodes"
command: "kubectl top nodes"
type: "global" # Independent of selection
watchInterval: 5s
- name: "Shell ($SHELL)"
command: "$SHELL"
type: "global"
interactive: true
onExit: "restore" # Return to previous panel mode when the shell exits
- name: "Describe Resource"
command: "kubectl describe {{.Resource}} {{.Name}} -n {{.Namespace}}"
type: "selector" # Reruns when selection changes
location: "panel"
onExit: "keep-open"- selector: Triggered by selection, reruns on change. Good for
describe,get -o yaml, etc. - sticky: Starts with current selection but keeps running.
- namespace: Sticky for the current namespace, restarts on namespace change.
- global: Independent of selection. Good for cluster-wide commands like
top nodes.
Available variables: {{.Name}}, {{.Namespace}}, {{.Kind}}, {{.Group}}, {{.Version}}, {{.Resource}}.
The execution context is available as {{.Context}}, {{.As}}, {{.AsUID}} and {{.AsGroups}} (a list), for tools that do not read KUBECONFIG. Commands already run with KUBECONFIG set to kc's selected context and the namespace of the selected item (else the panel's), so kubectl needs no extra flags. Commands without a selected item are run as written, without template expansion.
~/.kc/config.yaml stores all user preferences. Key sections:
viewer.theme,viewer.mode– chroma theme and wrap mode for YAML/text/log viewers.viewer.logs.tail,viewer.logs.since,viewer.logs.timestamps– the options a logs viewer opens with.F2in the viewer changes them for that viewer;C-sthere saves them as the defaults.panel.table.mode,panel.scrolling.horizontal.step– object-table rendering and panning behavior.resources.showNonEmptyOnly,resources.order,resources.favorites– resource-group listing controls (leavefavoritesempty to follow discovery'sallcategory).objects.order,objects.columns– server-side Table ordering and wide/normal column display. Lists that span namespaces (all namespaces, the pods of a node) are grouped by namespace first; the order applies inside each namespace.kubernetes.discovery.refresh,kubernetes.clusters.ttl– discovery invalidation, and how long a cluster cache stays running after the last open folder that uses it is closed.input.mouse.doubleClickTimeout– double-click threshold for Enter events.nodeShell.enabled,nodeShell.contexts,nodeShell.image,nodeShell.namespace,nodeShell.maxDuration– the node shell (off by default); see below.
Run kc once to materialize defaults or inspect config-default.yaml.
C-s ("Save as defaults") in an option dialog reads the file again and writes only the settings that dialog shows, so custom commands and keys kc does not know stay as they are. The file is replaced atomically and keeps its permissions; a symbolic link is written through to its target. The command line says whether the settings were saved or apply to this session only.
If the file cannot be read or parsed, kc starts with the defaults and shows the file path and the error on the command line. It never writes over that file: C-s is refused until the file loads again. Fix the file (or move it away to start from scratch) and press C-s again, or restart kc to load it.
Copy/paste into ~/.kc/config.yaml to start customizing:
viewer:
theme: dracula
mode: scroll
logs:
# Recent lines fetched before following; -1 fetches the whole log.
tail: 200
# Only lines newer than this; 0s means no limit.
since: 0s
# Prefix every line with its timestamp.
timestamps: false
panel:
scrolling:
horizontal:
step: 4
width:
leftPercent: 50
rightPercent: 50
input:
# How long kc waits for the key after Esc (Esc c, Esc 3, Esc s). A lone
# Esc in a viewer closes it after this time.
escTimeout: 1s
mouse:
doubleClickTimeout: 300ms
kubernetes:
clusters:
ttl: 2m
discovery:
refresh: 30s
resources:
# Default behavior: hide resources with zero objects
showNonEmptyOnly: true
# How often to re-peek hidden resources for changes when showNonEmptyOnly is true
peekInterval: 10s
# Default ordering: alphabetic by resource plural
order: alpha
# Favorites are used when order=favorites; leave empty to use discovery's "all" category.
favorites: []
objects:
# Object list ordering: name | -name | creation | -creation
order: name
# Columns mode for server-side Tables:
# - normal: show priority 0 columns (kubectl default)
# - wide: show all server-provided columns (like `kubectl get -o wide`)
columns: normal
nodeShell:
# Off by default. "Start a node shell..." inside a node creates a
# privileged pod with the host PID, network and IPC namespaces on that
# node and opens a root shell in the host namespaces.
enabled: false
# Limit the node shell to these kube contexts; empty means all contexts.
# contexts: [kind-dev]
# The image needs sh and nsenter.
image: docker.io/library/busybox:1.36.1
# Namespace of the shell pod; pod security admission must allow
# privileged pods there.
namespace: default
# activeDeadlineSeconds of the pod: it stops after this time even in use.
maxDuration: 8hThis repo is intentionally vibe-coded. If you want to peek behind the curtain—or help civilize it—see CONTRIBUTING.md and AGENTS.md for expectations, logging conventions, and build/test commands.
