Kimchi CLI

Configure your AI coding tools to use open-source models in seconds.

Overview

The CLI configures your favorite AI coding assistants to use open-source models hosted by Cast AI. No API keys from Anthropic or OpenAI needed, just your Cast AI API key.

Supported Models

Quick Start

One-Line Install

curl -fsSL https://github.com/getkimchi/kimchi/releases/latest/download/install.sh | bash

This downloads and installs the CLI, then launches the setup wizard automatically.

Manual Install

Download the latest release for your platform:

Download and extract:

curl -fsSL https://github.com/getkimchi/kimchi/releases/latest/download/kimchi_linux_amd64.tar.gz | tar xzf -

Make executable and move to PATH:

chmod +x kimchi

sudo mv kimchi /usr/local/bin/

Getting Started

Supported Tools

Usage

Launch the harness:

kimchi

Launch in plan mode (read-only exploration and structured planning):

kimchi --plan

Run initial setup (auth, RTK, telemetry):

kimchi setup

Configure coding tools:

kimchi setup-tools

This launches an interactive wizard to select and configure coding tools (Cursor, OpenCode, Claude Code, OpenClaw, GSD2) in one pass.

Manage session tags (from within the harness):

/tags                        # list all active tags
/tags add key:value ...      # add one or more tags
/tags remove tag ...         # remove one or more user-defined tags
/tags clear                  # remove all user-defined tags

Tags added with /tags add are saved to ~/.config/kimchi/tags.json and persist across sessions until removed. Static tags set via the KIMCHI_TAGS environment variable cannot be modified with /tags. See Tags for tag format rules and analytics integration.

Log in (from within the harness):

/login

This presents an authentication method selector with three options:

• Use a Kimchi account — opens your browser to authenticate. On success, your API key is saved and the active model is set automatically.
• Use a Kimchi API key — prompts you to enter an API key and an endpoint (defaults to https://llm.kimchi.dev). The key is validated against the endpoint before saving.
• Use a subscription — routes to upstream OAuth providers.

Show version:

kimchi version

Manage resources (hooks, tools, extensions, plugins):

kimchi resources list
kimchi resources enable <resource-id>
kimchi resources disable <resource-id>
kimchi resources reset <resource-id>

Set a session name:

kimchi --name "my task"

Enable experimental features:

kimchi --enable-experimental-features

Use this flag to access models and capabilities that are still under active development. Experimental features may change or be removed without notice and are not recommended for production use. The flag is not persisted — you need to pass it each time you launch Kimchi.

Enable debug output:

kimchi --debug

Generate shell completion:

  kimchi completion bash > /etc/bash_completion.d/kimchi

How It Works

The CLI configures each tool to use the inference endpoint:

Your AI Tool ──► CLI Config ──► Inference Endpoint ──► Open-Source Models
                                        │
                                        ▼
                               https://llm.kimchi.dev

Configuration Example (OpenCode)

{
  "provider": {
    "kimchi": {
      "name": "Kimchi",
      "options": {
        "baseURL": "https://llm.kimchi.dev/openai/v1",
        "apiKey": "your-api-key"
      },
      "models": {
        "kimi-k2.6": { "reasoning": false },
        "minimax-m3": { "reasoning": false }
      }
    }
  }
}

Configuration

Global Config

The global configuration file lives at ~/.config/kimchi/config.json. It stores your API key and other settings that apply to all projects by default.

Per-Project Config

You can override global settings on a per-project basis by creating a .kimchi/config.json file in your project root:

mkdir -p .kimchi
cat > .kimchi/config.json <<'EOF'
{
  "apiKey": "project-specific-key",
  "llmEndpoint": "https://custom-endpoint.example.com",
  "skillPaths": ["/project/skills"],
  "mcpSearch": {
    "strategy": "bm25"
  }
}
EOF

All fields are optional — only include the settings you want to override.

Config Precedence

Configuration is resolved in the following order (highest to lowest):

1. KIMCHI_API_KEY environment variable
2. Project .kimchi/config.json (in the current working directory)
3. Global ~/.config/kimchi/config.json

Merge Behavior

Empty strings in the project config are ignored and the global value is used instead. Malformed JSON in the project config is silently ignored, falling back to the global config.

Context Files

You can provide custom instructions that are injected into the system prompt on every session. Kimchi discovers two kinds of context files:

Global — applied to every session, regardless of project:

~/.config/kimchi/harness/AGENTS.md

Place rules that apply everywhere (e.g., your name, code style preferences, or global tool defaults) in this file. It is loaded before any project-level files.

Project-level — applied when working in a specific directory tree. Kimchi walks from the working directory up to the filesystem root and collects one context file per directory:

AGENTS.md
CLAUDE.md

Per directory, AGENTS.md takes priority over CLAUDE.md. A .local.md variant (e.g. AGENTS.local.md) is appended to its primary file for user-specific, gitignored overrides.

When both global and project files exist, global instructions appear first in the prompt, followed by ancestor directories, and finally the working directory. This means project-level rules can refine or override global ones.

Built-in Superpowers Skills

Kimchi ships with the obra/superpowers skill library — a set of 14 methodology skills that guide the agent through structured workflows like test-driven development, systematic debugging, code review, and planning.

How it works

Superpowers skills are packaged with each Kimchi release and available immediately after installation.

Included skills

Manual install deduplication

If you already have superpowers manually installed in ~/.config/kimchi/harness/skills/, Kimchi detects this and skips the vendor path to avoid duplicate skills.

Version pinning

The superpowers version is pinned to each Kimchi release. When you update Kimchi, the bundled superpowers skills are updated automatically. The version only changes when you update Kimchi itself.

Plan Mode

Plan mode is a read-only planning workflow. Launch it with kimchi --plan. The agent explores the codebase, asks clarifying questions, and produces a structured plan — all without making any changes. You review and approve the plan before execution begins.

How it works

kimchi --plan
↓
1. Agent explores the codebase (read-only)
2. Agent asks clarifying questions via structured prompts
3. Agent produces a structured plan
4. Approval menu appears
5. You choose: Execute / Start as ferment / Rework
↓
Plan saved → mode switches → agent executes with full access

In plan mode, the agent has read-only access: it can read files, search, list directories, and run read-only shell commands. It cannot edit, write, or run commands that change state.

Structured plan format

The agent follows a consistent plan template:

Clarifying questions

When the request is ambiguous — missing a technology choice, scope boundary, or performance target — the agent asks 1–3 focused questions using a structured questionnaire before committing to a plan. Open questions within the plan must be resolved with you before the plan is finalized.

Approval gate

When the plan is complete, an approval menu appears with three options:

Plan persistence

Approved plans are saved to .kimchi/plans/ as timestamped markdown files (e.g., plan-1719849600000.md). The executing agent receives the saved file path and the full plan text as immediate context, so it can begin work without scanning conversation history.

Footer Customization

The footer bar shows your permission mode, active model, context usage, and other status at a glance. Some segments — like agent count or current phase — hide themselves when inactive. If you'd rather keep certain segments visible at all times, you can pin them.

Run /footer-settings during a session to choose which segments to pin:

/footer-settings

Navigate with ↑/↓ (or j/k), toggle with Space or Enter, and close with Esc. The following segments can be pinned:

Permissions and Model are always visible and cannot be toggled.

Your pinning choices are saved automatically to ~/.config/kimchi/harness/settings.json and persist across sessions.

Tips

Kimchi displays contextual tips above the editor to help you discover features and shortcuts. You can manage tips using the /tips command during a session:

/tips              # show all available tips
/tips disable      # hide the tips widget
/tips enable       # show the tips widget again

The preference is saved to your global config file (~/.config/kimchi/config.json) under preferences.hideTips and persists across sessions.

Token Optimization (RTK)

RTK compresses command output (git, cargo, npm, docker, etc.) by 60–90%, significantly reducing LLM context usage. Kimchi automatically installs and manages RTK for you.

How it works: Before every bash tool execution, kimchi calls rtk rewrite "<command>". If RTK returns a rewritten command (e.g. git status becomes rtk git status), the rewritten version is executed instead. The agent receives compact, filtered output without any workflow changes.

Automatic installation: RTK is installed automatically on first session start. The binary is placed at ~/.config/kimchi/harness/rtk and symlinked into ~/.local/bin/rtk (macOS/Linux). The setup wizard also offers an RTK installation step. Kimchi checks for updates once every 24 hours.

To disable automatic installation, set the environment variable before launching:

KIMCHI_RTK_AUTO_INSTALL=0 kimchi

Manual installation:

brew install rtk    # macOS / Linux

If RTK is already on your PATH, kimchi uses it directly.

Disabling RTK rewriting:

Disable via the resource system:

kimchi resources disable hooks.rtk-rewrite

Or disable for a single session with an environment variable:

KIMCHI_RTK=0 kimchi

Set KIMCHI_RTK to 0, false, or off to disable rewriting even when RTK is installed.

Prompt History

Kimchi automatically loads prompts from previous sessions into the editor's up/down arrow history. When you start a session, the harness scans past sessions in the current project's .kimchi/ directory, extracts user prompts, and makes them available for navigation — so you can reuse previous prompts without retyping.

Behavior:

• Prompts are loaded from all past sessions in the current project directory
• The current session's own prompts are excluded
• Forked and subagent sessions are skipped (their prompts are synthetic)
• System-generated messages (annotations, orchestrator instructions) are filtered out
• Duplicate prompts are deduplicated across sessions
• Prompts are ordered most-recent first, up to 100 entries

No configuration is needed — prompt history is always active.

Resource Management

Kimchi provides a centralized resource system for controlling which hooks, tools, extensions, and plugins are active. Resources can be managed from the CLI or from within a chat session.

CLI

kimchi resources list                        # show all resources and their status
kimchi resources enable <resource-id>        # enable a resource
kimchi resources disable <resource-id>       # disable a resource
kimchi resources reset <resource-id>         # reset to default

In-Chat Commands

Use /resources during a session to open an interactive settings overlay, or pass subcommands directly:

/resources              # open the resource manager UI
/resources list         # print resource status
/resources enable <id>  # enable a resource
/resources disable <id> # disable a resource
/hooks                  # open the resource manager filtered to hooks
/plugins                # open the resource manager filtered to plugins

Available Resources

In addition to the static resources above, Kimchi discovers bash hook scripts placed in ~/.config/kimchi/harness/hooks/bash/ (global) and .kimchi/hooks/bash/ (project-level). Global hooks are enabled by default; project-level hooks are disabled by default. Installed Pi packages also appear as plugin resources (e.g. plugins.package.npm-context-mode) and can be toggled like any other resource. Disabling a package resource requires a restart to take effect.

Resource Settings

Resource overrides are persisted in ~/.config/kimchi/harness/settings.json under the resources key:

{
  "resources": {
    "hooks.rtk-rewrite": true,
    "tools.web_search": false
  }
}

Bash Hooks

Bash hooks are shell scripts that intercept commands before execution. They can rewrite commands or block them entirely. The entire bash hook subsystem can be disabled with kimchi resources disable hooks.bash.

Hook locations:

• Global: ~/.config/kimchi/harness/hooks/bash/ — enabled by default
• Project: .kimchi/hooks/bash/ — disabled by default

Hook scripts receive a JSON payload on stdin with the tool name, command, and working directory. They can output a JSON response with a decision (allow or block) and optionally a rewritten command, or simply print a rewritten command as plain text.

Discovered hooks appear as resources (e.g. hooks.bash.global.my-hook-sh) and can be toggled like any other resource.

Claude Code Hook Adapter

If you already have hooks configured for Claude Code (in a .claude/settings.json or ~/.claude/settings.json file), you can reuse them in Kimchi without rewriting them. The Claude Code hook adapter is a disabled-by-default extension that reads your existing Claude Code hook configuration and runs those hooks during Kimchi sessions.

To enable it:

kimchi resources enable extensions.claude-code-hook-adapter

Restart Kimchi after enabling. Discovered Claude Code hook commands also appear under the Hooks tab in /resources, where they can be enabled or disabled individually.

The adapter reads hooks from the user config and the nearest ancestor project config:

• ~/.claude/settings.json (user)
• .claude/settings.json (project)
• .claude/settings.local.json (local project)

To disable all hooks from Claude Code config files at once, set "disableAllHooks": true at the top level of any of those files.

What hooks can do

Hooks can run on the following events: PreToolUse, PostToolUse, SessionStart, PreCompact, PostCompact, UserPromptSubmit, Stop, and SessionEnd.

PreToolUse hooks can inspect or rewrite tool input before it runs. A hook that exits with code 2 blocks execution of that tool call. Other hooks run for side effects (logging, notifications, etc.) and do not affect execution.

Example

A PreToolUse hook that runs a script before every Bash command:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/pre_tool_use.py"
          }
        ]
      }
    ]
  }
}

Place this in any of the settings files listed above. The "matcher": "Bash" field limits the hook to Bash tool calls; omit it to run on all tools.

If your hooks depend on Claude Code skills, enable the separate skill compatibility extension:

kimchi resources enable extensions.claude-code-skills

Claude Code Skills

The Claude Code skills extension loads skills from ~/.claude/skills and the nearest project .claude/skills directory into Kimchi's native available-skills prompt. It also contributes them through Pi resource discovery so /skill:name works, and provides a Claude-compatible Skill tool for hooks that invoke Skill("name").

To enable it:

kimchi resources enable extensions.claude-code-skills

Restart Kimchi after enabling.

Pi Package Extensions

Pi packages that ship native hooks can be installed and managed through the CLI:

kimchi install npm:<package-name>
kimchi list

Installed packages subscribe to native Pi events such as tool_call, tool_result, session_start, and session_shutdown. Each installed package appears as a plugin resource (e.g. plugins.package.npm-context-mode) and can be enabled or disabled from the resource manager or CLI. Package resource changes require a restart to take effect.

Updating Packages

The kimchi update command handles both Kimchi self-updates and Pi package updates:

kimchi update                          # update packages and Kimchi
kimchi update --extensions             # update installed packages only
kimchi update --extension <name>       # update a single package
kimchi update --self                   # update Kimchi only
kimchi update <package-name>           # update a single package by name

Use --dry-run and --canary for Kimchi self-update checks only.

Local Ollama Models

Kimchi automatically discovers models running on a local Ollama server and makes them available in the model picker and multi-model role pools — no manual configuration required.

How it works

On every startup, Kimchi probes the Ollama API (/api/tags and /api/show) to discover installed models. Discovered models are:

• Persisted into models.json under an ollama provider
• Exposed in the /model picker as ollama/<model-name> (e.g. ollama/llama3:8b)
• Added to the explorer, reviewer, and builder role pools

The probe is silent on failure — if Ollama is not running or unreachable, startup continues normally with no errors or warnings. When Ollama goes offline between runs, any previously discovered models are automatically removed from models.json.

Configuring the Ollama host

By default, Kimchi probes http://localhost:11434. To point to a different Ollama server, set one of these environment variables:

OLLAMA_HOST=http://gpu-box.lan:11434 kimchi

Role pool rules

Ollama models are added to the explorer, reviewer, and builder role pools only. They are never assigned to the orchestrator, planner, or judge roles.

Capabilities

The probe detects model capabilities automatically:

• Vision — models with vision capability accept image inputs
• Reasoning — models with thinking capability are marked as reasoning models
• Tools — tool-calling support is detected and preserved

These are expressed in models.json via the input array and reasoning flag:

{
  "id": "llava:7b",
  "name": "llava:7b",
  "reasoning": false,
  "input": [
    "text",
    "image"
  ]
}

Because inference runs locally, Kimchi reports zero cost for all Ollama models. No API usage is metered or billed. This is reflected in models.json as:

{
  "cost": {
    "input": 0,
    "output": 0,
    "cacheRead": 0,
    "cacheWrite": 0
  }
}

FAQ

Will this break my existing config?

No. The CLI preserves your existing tool configurations and only adds its provider settings. Custom providers you add to models.json (e.g., vLLM, LM Studio) are also preserved across CLI restarts. Ollama models are discovered and injected automatically — see Local Ollama Models.

Clipboard image pasting doesn't work on WSL or headless Linux

Kimchi disables clipboard image pasting on WSL and headless Linux because these environments typically lack a display server. Without one, the clipboard feature would crash on startup.

If you have an X server running in WSL (e.g. VcXsrv, X410), opt back in by setting an environment variable before launching:

export KIMCHI_CLIPBOARD_FORCE=1
kimchi

On non-WSL Linux, clipboard image pasting requires a running display server. If it isn't working, check that $DISPLAY or $WAYLAND_DISPLAY is set in the shell where you launch Kimchi.

Can I switch back?

Yes. Simply remove the kimchi provider from your tool's config file, or re-run the tool's original setup.

Where is my API key stored?

• Global config file: ~/.config/kimchi/config.json (permissions: 600)
• Per-project config file: .kimchi/config.json (in your project root)
• Environment variable: KIMCHI_API_KEY

Reporting Bugs

Use /bug during a harness session to open a pre-filled GitHub issue form:

/bug Something is broken

The command auto-fills the bug report template with your harness version and any description you provide. In TUI mode it opens your browser; in headless mode it prints the URL to stdout. If the browser fails to open, the full URL is displayed so you can copy it manually.