Kat

<p align="center"> <a href="#"><img src="docs/assets/logo.svg" width="200px"></a> <h1 align="center">kat</h1> </p> <p align="center"> <a href="https://pkg.go.dev/github.com/macropower/kat"><img alt="Go Reference" src="https://pkg.go.dev/badge/github.com/macropower/kat.svg"></a> <a href="https://goreportcard.com/report/github.com/macropower/kat"><img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/macropower/kat"></a> <a href="https://codecov.io/gh/macropower/kat"><img src="https://codecov.io/gh/macropower/kat/graph/badge.svg?token=4TNYTL2WXV"/></a> <a href="#-installation"><img alt="GitHub Downloads" src="https://img.shields.io/github/downloads/macropower/kat/total"></a> <a href="#-installation"><img alt="Latest tag" src="https://img.shields.io/github/v/tag/macropower/kat?label=version&sort=semver"></a> <a href="https://github.com/macropower/kat/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/macropower/kat"></a> </p>

kat automatically invokes manifest generators like helm or kustomize, and provides a persistent, navigable view of rendered resources, with support for live reloading, integrated validation, and more.

It is made of two main components, which can be used together or independently:

1. A rule-based engine for automatically rendering and validating manifests
2. A terminal UI for browsing and debugging rendered Kubernetes manifests

Together, these deliver a seamless development experience that maintains context and focus while iterating on Helm charts, Kustomize overlays, and other manifest generators.

<p align="center"> <img src="./docs/assets/demo.gif"> </p> <p align="center"> ❤️ Made with <a href="https://github.com/charmbracelet/bubbletea">bubble tea</a>, <a href="https://github.com/alecthomas/chroma/">chroma</a>, and <a href="#-dependencies">other amazing libraries</a>. </p>

✨ Features

🔍️ Manifest browsing

• Navigate hundreds of resources with fuzzy search and filtering
• View individual resources in your terminal with syntax highlighting

⚡️ Live reload

• Monitor source files with --watch for automatic re-rendering
• Maintain your current context between reloads so you don't lose your place
• Highlight changes with diff visualization between renders

🐛 Error handling

• Surface rendering and validation errors as overlays
• Works with reload; fix source files and watch errors disappear instantly

🧪 Tool integration

• Define profiles for any manifest generator (Helm, Kustomize, CUE, KCL, Jsonnet, etc.)
• Run tools like kubeconform or kyverno automatically on rendered manifests
• Chain multiple tools together with pre and post-render hooks

🎯 Project detection

• Select your defined profiles automatically using CEL expressions
• Match projects based on file contents, structure, or naming patterns
• Support for project-specific runtime configs via .katrc.yaml files

🔌 Plugin system

• Add custom keybind-triggered commands for your specific workflows
• Execute dry-runs, deployments, or any custom tooling without leaving kat

🤖 MCP server (Experimental)

• Limit access to irrelevant context, improving performance and reducing cost
• Force your AI to always follow the same rendering and validation pipeline
• Enable iterative testing without handing over cluster or command-line access

🎨 Fully customizable

• Choose from any available Chroma themes, or define your own
• Remap any keybinding to match your preferences

📦 Installation

<details> <summary><strong>Homebrew</strong></summary>

You can install kat using my tap.

With brew:

brew install macropower/tap/kat --cask

With your Brewfile:

tap "macropower/tap"
cask "kat"

</details> <details> <summary><strong>Go</strong></summary>

go install github.com/macropower/kat/cmd/kat@latest

</details> <details> <summary><strong>Docker</strong></summary>

Docker images are published to ghcr.io/macropower.

All images are configured with WORKDIR=/data, so you can mount your current directory there to run kat against your local files.

Run the latest alpine image:

docker run -it -v .:/data -e TERM=$TERM ghcr.io/macropower/kat:latest-alpine

The default config is located at /config/kat/config.yaml, and you can override it by mounting your own configuration file at that path.

There is also a scratch image that contains only the kat binary, which is useful when you want to build your own image (which I generally recommend doing):

FROM alpine:latest
COPY --from=ghcr.io/macropower/kat:latest /kat /usr/local/bin/kat
# Add whatever customization you need here.
ENTRYPOINT ["/usr/local/bin/kat"]

</details> <details> <summary><strong>Nix (NUR)</strong></summary>

You can install kat using my NUR.

With nix-env:

nix-env -iA kat -f https://github.com/macropower/nur-packages/archive/main.tar.gz

With nix-shell:

nix-shell -A kat https://github.com/macropower/nur-packages/archive/main.tar.gz

With your flake.nix:

{
  inputs = {
    macropower.url = "github:macropower/nur-packages";
  };
  # Reference the package as `inputs.macropower.packages.<system>.kat`
}

With devbox:

devbox add github:macropower/nur-packages#kat

</details> <details> <summary><strong>GitHub CLI</strong></summary>

gh release download -R macropower/kat -p "kat_$(uname -s)_$(uname -m).tar.gz" -O - | tar -xz

And then move kat to a directory in your PATH.

</details> <details> <summary><strong>Curl</strong></summary>

curl -s https://api.github.com/repos/macropower/kat/releases/latest | \
  jq -r ".assets[] |
    select(.name | test(\"kat_$(uname -s)_$(uname -m).tar.gz\")) |
    .browser_download_url" | \
  xargs curl -L | tar -xz

And then move kat to a directory in your PATH.

</details>

Or, download a binary from releases.

Note: The default kat configuration contains references to helm, kustomize, and yq. If you want to use kat with these tools, you will need to install them separately.

🔏 Verification

You can verify the authenticity and integrity of kat releases.

See verification for more details.

🚀 Usage

Show help:

kat --help

Render a project in the current directory:

kat

Render a project and enable watch (live reloading):

kat -w

Render a project in a specific directory:

kat ./example/helm

Render a project in a specific directory using the ks profile:

kat ./example/kustomize ks

Render a project with custom profile arguments:

kat ./example/helm -- -g -f prod-values.yaml

kat ./example/kustomize ks -- --enable-helm

Render a project with command passthrough:

kat ./example/helm task -- helm:render

Read from stdin (disables rendering engine):

cat ./example/kustomize/resources.yaml | kat -

Send output to a file (disables TUI):

kat ./example/helm > manifest.yaml

You can optionally start kat with an MCP server by using the --serve-mcp flag:

kat --serve-mcp :50165

See MCP Server for more details.

⚙️ Configuration

When you first run kat, it will attempt to add default configuration files to $XDG_CONFIG_HOME/kat/ (or ~/.config/kat/). This configuration allows you to customize the behavior of kat, such as the UI style, keybindings, rules for project detection, and profiles for rendering different types of projects.

Note that JSON schemas are also included in the configuration directory, which can be used by your editor's YAML language server.

Some of the default behavior around loading configuration can be overridden with command line flags or environment variables. See kat --help for details.

Over time, the default configuration may change, and the schema is currently still evolving. If you want to reset your configuration to the latest defaults, you can use kat --write-config, which will move your existing configuration to a backup file and generate a new default configuration.

You can find the default configuration file as well as JSON schemas in api.

🛠️ Rules and Profiles

You can customize how kat detects and renders different types of projects using rules and profiles in the configuration file. This system uses CEL (Common Expression Language) expressions to provide flexible file matching and processing.

🎯 Rules

Rules determine which profile should be used. Each rule contains:

• match (required): A CEL expression that returns true if the rule should be applied
• profile (required): The name of the profile to use when this rule matches

Rules use boolean CEL expressions with access to:

• files (list<string>): All file paths in the directory
• dir (string): The directory path being processed

rules:
  - # Select the Helm profile if any Helm chart files exist
    match: >-
      files.exists(f, pathBase(f) in ["Chart.yaml", "Chart.yml"])
    profile: helm

  - # Select the Kustomize profile if any Kustomization files exist
    match: >-
      files.exists(f, pathBase(f) in ["kustomization.yaml", "kustomization.yml"])
    profile: ks

  - # Fallback: select the YAML profile if any YAML files exist
    match: >-
      files.exists(f, pathExt(f) in [".yaml", ".yml"])
    profile: yaml

🎭 Profiles

Profiles define how to render projects. They can be automatically selected by rules, or manually specified when kat is invoked. Each profile contains:

• command (required): The command to execute
• args: Arguments to pass to the command
• extraArgs: Arguments that can