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, superpowers skills):

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.

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-m2.7": { "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.

📘

The project config file is only read from the exact working directory — Kimchi does not walk up the directory tree to find it.

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.

📘

For full documentation on skills — including the skill file format, directory layout, how to install and create custom skills, and project rules — see Skills and Project Rules.

How it works

On first launch, Kimchi automatically downloads the pinned superpowers release and extracts it to `~/.config/kimchi/vendor/superpowers/`. Subsequent launches skip the download entirely (a version file check takes ~0ms). If you're offline on first launch, the download is silently skipped and retried on the next launch.

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 Kimchi updates, it automatically re-downloads the matching superpowers version if needed. There is no auto-update mechanism — 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 / Convert to 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.

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.

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

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. Skills that already exist in native skill directories (e.g. .agents/skills/) are automatically deduplicated and not loaded twice.

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.

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., Ollama, vLLM, LM Studio) are also preserved across CLI restarts.

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.

📘

For the latest releases and source code, visit the GitHub repository.