Kata

AI integration

Wire Kata to your AI CLI

Kata never asks for its own AI API key. You point it at a local CLI you already use — Claude Code or Codex CLI — and Kata drives it on your behalf, with a scoped prompt built from the diagram surface. Your subscription pays. Your privacy terms apply. Kata is not in the middle.

What you'll be able to do

  • Pick the AI CLI (Claude Code or Codex CLI) and the model identifier Kata should invoke on your behalf.
  • Configure the CLI binary — via PATH or an environment variable — so Kata finds it.
  • (Pro) Turn on AI Puppet Mode so Kata replays the AI-driven refactor dialogs automatically end-to-end.
  • Understand what Kata sends to the CLI and what stays on your machine.

Supported CLIs

  • Claude Code — invoked with -p --output-format stream-json --verbose; Kata reads NDJSON events from stdout.
  • Codex CLI (OpenAI) — invoked with its exec subcommand.

Cursor and other MCP-compatible clients don't drive Kata through the AI CLI pane; they attach to Kata's MCP server instead. See the MCP API page for that direction.

Configure Preferences → AI

Open Preferences → AI. The pane exposes:

  • Claude model identifier — the model name Kata passes to Claude Code (for example the current Opus or Sonnet identifier). Kata appends it to the invocation as --model <id>.
  • Codex model identifier — the corresponding model name for Codex CLI.
  • AI Puppet Mode (Pro) — when on, Kata replays the AI diff preview dialog automatically: apply the diff, re-index, re-check smells, and move on. Off by default; every apply is manual.
Kata does not take an executable path in the Preferences pane. It resolves the CLI from PATH. If your Claude Code binary lives outside PATH, set the environment variable KATA_CLAUDE_CLI to its full path before launching Kata.

Verify the wiring

There is no dedicated test button — instead, run one real refactor:

  1. Open any solution that has at least one 💩 smell badge on the diagram.
  2. Right-click the badge and choose Ask AI.
  3. Watch the AI diff preview dialog appear within a few seconds with a PolicyCheck banner at the top and a QualityDelta panel below it.
  4. If nothing happens, check the Kata output log — the invocation, the exit code, and the first bytes of stdout are all logged there.

Data flow — what leaves your machine

When you invoke Ask AI, Kata writes a scoped prompt as plain text to the CLI's stdin and reads back NDJSON events on stdout. The prompt contains:

  • The target class or member's source, verbatim.
  • The surrounding context Kata deems necessary — usually immediate callers and callees, plus any types the target depends on.
  • The smell name or Fowler intent you invoked.
  • An instruction to return a unified diff and nothing else.

Once the CLI receives the prompt, wherever it sends it is governed by your agreement with the CLI vendor — Kata is not in the middle. Kata's MCP server, by contrast, binds to localhost only; see the MCP API page for that side of the story.

Troubleshooting

CLI not found

Kata reports "CLI unavailable" when the binary isn't on PATH. Either put it on PATH or set KATA_CLAUDE_CLI (or the corresponding Codex variable) to its absolute path, then relaunch Kata.

CLI runs but returns "not signed in"

Each CLI has its own auth flow. Run the CLI once from a normal terminal with its login command (claude login, codex login, etc.) so it caches credentials. Kata inherits the same credential store.

Ask AI produces nothing / times out

The CLI is usually asking for interactive confirmation (a permission prompt, rate-limit acknowledgment) that a non-interactive stdin cannot answer. Both Claude Code and Codex CLI have per-vendor mechanisms for non-interactive use; check their documentation and set them up in your shell profile so Kata inherits the environment.

Next steps