kubectl.nvim: Agent for Claude Code

Lua/Neovim Plugin Guidance

ALWAYS use this subagent for ANY task involving:

• Reading, editing, or understanding Lua code
• lua/kubectl/ directory
• Resource views, keybindings, or mappings
• State management or configuration
• Neovim API integration
• Researching Lua code for documentation

For Rust FFI patterns and async calls, also consult the rust subagent.

---

Guidance for working with the Lua/Neovim plugin codebase (lua/kubectl/).

Plugin Structure

Entry Point

init.lua - Plugin setup, commands (:Kubectl, :Kubens, :Kubectx), autocommands, and keymap registration.

Core Modules

• config.lua - Default configuration with user overrides via setup()
• state.lua - Global runtime state, session persistence, filter/sort state
• resource_factory.lua - Builder pattern for constructing resource views
• mappings.lua - Global keybinding definitions using <Plug> format

Resource Pattern

Each Kubernetes resource in lua/kubectl/resources/<resource>/ follows:

<resource>/
├── init.lua        # View(), Draw(), Desc() functions
├── definition.lua  # Resource metadata (GVK, headers, hints)
└── mappings.lua    # Resource-specific keybindings

Definition structure:

M.definition = {
  resource = "pods",
  display_name = "PODS",
  ft = "k8s_pods",           -- filetype for buffer
  gvk = { g = "", v = "v1", k = "Pod" },
  hints = { ... },           -- help text shown in header
  headers = { ... },         -- column definitions
}

Standard functions:

function M.View(cancellationToken)   -- Create and show view
function M.Draw(cancellationToken)   -- Refresh existing view
function M.Desc(name, ns, reload)    -- Show resource description

Resource Factory (Builder Pattern)

The factory in resource_factory.lua provides a fluent API:

local factory = require("kubectl.resource_factory")
factory.new("pods")
  .setCmd(args, "kubectl")
  .fetch()
  .decodeJson()
  .process(processFunc)
  .sort()
  .prettyPrint(win_nr)
  .addHints(hints, true, true)
  .addDivider(true)
  .displayContent(win_nr, cancellationToken)