A coding agent CLI powered by kimchi. Built on the pi-mono coding agent SDK, kimchi gives you an AI-powered development assistant in your terminal that connects to kimchi's LLM infrastructure.
Install the latest release:
Homebrew (macOS / Linux):
brew tap castai/tap
brew install castai/tap/kimchi-devInstall script:
curl -fsSL https://github.com/castai/kimchi-dev/releases/latest/download/install.sh | bashThen configure your API key and tools, and launch:
kimchi setup # one-time interactive setup
kimchi # launch the coding harnessRun kimchi --help to see all available subcommands and flags.
The API key is resolved in this order:
KIMCHI_API_KEYenvironment variable (takes precedence)~/.config/kimchi/config.jsonfieldapi_key
Run kimchi setup for an interactive first-time configuration.
kimchi stores its own configuration (settings, sessions, models) under:
~/.config/kimchi/harness/
On first run, kimchi-code looks for an existing Claude Code or OpenCode installation on your machine and offers to migrate its MCP servers and report any user-level skills it finds. If anything is migratable you'll see a one-shot prompt:
┌ Claude Code + OpenCode configuration found
│
│ MCP servers: filesystem, github, ripgrep
│ Claude Code skills: 4 in ~/.claude/skills
│ OpenCode skills: 2 in ~/.config/opencode/skills
│
◇ Migrate MCP servers to Kimchi?
│ ● Migrate now
│ ○ Skip this time
│ ○ Never ask again
When you accept, the discovered MCP servers are merged into ~/.config/kimchi/harness/mcp.json. Existing Kimchi entries always win on name collisions, so re-running the migration is safe — your hand-edited Kimchi config is never overwritten.
The prompt is only shown when something is actually worth migrating (at least one MCP server, or at least one skill subdirectory). If neither agent is installed, or both are installed but empty, the wizard skips the migration step silently and never asks again.
| Agent | Config files (read in order, results merged) | Skills directory |
|---|---|---|
| Claude Code | ~/.claude.json (top-level mcpServers + per-project projects[*].mcpServers) |
~/.claude/skills/ |
| OpenCode | $OPENCODE_CONFIG, then ~/.config/opencode/opencode.json, opencode.jsonc, config.json, ~/.opencode.json |
~/.config/opencode/skills/ (with skill/ as a fallback) |
For OpenCode, both the modern (mcp block, type: "local" \| "remote", command: string[], environment, enabled) and legacy Go-binary (mcpServers block, type: "stdio" \| "sse", env as either an object or a KEY=VAL array) schemas are supported. Servers with enabled: false are skipped. Files that don't exist are silently ignored; files that fail to read or parse emit a warning and the wizard moves on.
If the same MCP server name shows up in more than one place, the first one wins, deduplicated at the server-name level rather than the file level:
- Within one agent: earlier files in the agent's path list win over later files; within a single Claude Code config, project-level entries win over top-level; within a single OpenCode config, the modern
mcpblock wins over the legacymcpServersblock. - Across agents: Claude Code wins over OpenCode (same default as the historical migration).
- Against your existing Kimchi config: your existing entries in
~/.config/kimchi/harness/mcp.jsonalways win.
Kimchi remembers your choice in ~/.config/kimchi/config.json (migrationState: "skip-forever") and won't prompt again on future runs, even if you later install another supported agent. To re-trigger the prompt, delete that field from the config file.
Adding support for another coding agent (Cursor, Cline, Aider, Cody, ...) is a small change — drop a new AgentDefinition into src/agent-discovery/agents/ and append it to AGENT_DEFINITIONS; the wizard, merging, prompt gating, and migration write all pick it up automatically.
The supported model list is fetched at startup from the kimchi metadata service.
Use /model in the interactive CLI to switch between available models.
By default, kimchi runs in multi-model mode: the main agent classifies each task, executes what it can directly, and delegates the rest to specialised subagents picked from the available model roster.
To disable orchestration and run as a single, direct coding assistant:
kimchi --multi-model=falseYou can also toggle the mode at any time during a session with the option/alt+tab keyboard shortcut. The current state is shown in the footer (multi-model: on / multi-model: off).
When multi-model is off the agent uses a single-model system prompt: environment, tools, research rules, guidelines, and phase tagging are all active, but task classification and delegation logic are disabled. The subagent tool is still available if you explicitly ask the agent to delegate a task.
kimchi respects HTTP_PROXY / HTTPS_PROXY environment variables for network requests.
Every subagent invocation writes its own persistent session file alongside the parent's, in the same session directory. The child's session header back-references its parent, and the parent's tool-result records the child's session id and file path. Nested subagents (sub-subagents) follow the same rule at any depth — all descendants land next to the original top-level parent.
This means subagent runs are fully recoverable from disk: open the parent's .jsonl, follow the sessionFile on any subagent tool-result to the child, and replay it like any other session. In pi's session-selector, children render under their parent as a tree. Deleting the parent's session directory removes its children automatically.
kimchi supports tagging LLM requests for usage tracking and cost attribution. Tags are automatically included with every LLM request and displayed in the footer of the interactive UI.
| Command | Description |
|---|---|
/tags |
List all active tags |
/tags add key:value ... |
Add one or more tags (e.g., /tags add project:myapp team:backend) |
/tags remove tag ... |
Remove one or more user-defined tags |
/tags clear |
Remove all user-defined tags |
Use /tags without arguments to see help and current static tag configuration.
Tags use key:value format with these rules:
- Must start and end with alphanumeric characters
- Middle characters can include hyphens (
-), underscores (_), and dots (.) - Key and value must each be 64 characters or less
- Maximum 10 tags total (including static tags and the auto-added model tag)
Valid examples: project:myapp, team:backend
Static tags are set via the KIMCHI_TAGS environment variable (comma-separated):
export KIMCHI_TAGS="team:backend,project:api"Static tags are read-only within the session and cannot be added, removed, or cleared via /tags commands. They are displayed with a [static] marker when listing tags.
User-defined tags (those added via /tags add) are automatically persisted to:
~/.config/kimchi/tags.json
These tags persist across sessions. Static tags from KIMCHI_TAGS are not persisted and must be set via environment variable each session.
Active tags are displayed in the footer, grouped by key with color coding for visual distinction. Tags with the same key are shown together (e.g., project:api,web).
A model:{model_id} tag is automatically added to every LLM request (e.g., model:kimi-k2.5). This tag does not count toward the 10 tag limit and cannot be removed.
A phase:{phase} tag is automatically added since kimchi supports phase tracking for usage analytics and cost attribution. Phases represent the high-level type of work being done (exploration, planning, building, reviewing, or researching).
| Phase | Description |
|---|---|
explore |
Exploring/navigating the codebase, reading files to understand structure |
plan |
Planning, designing, breaking down tasks, writing specs |
build |
Writing, modifying, or refactoring code |
review |
Code review, analyzing output, verifying correctness |
research |
Researching documentation, investigating issues |
Use the set_phase tool to set the current phase:
set_phase({"phase": "explore"})
Important: Only the orchestrator (main agent) can set phases. Subagents receive the current phase from the orchestrator but cannot change it.
- The orchestrator sets the phase at the start of work and when transitioning between activities
- The phase is displayed in the footer (e.g.,
↳ explore) - The phase is included as a
phase:{name}tag in all LLM requests for analytics - When delegating to subagents, the current phase is passed automatically
User: "Add user authentication"
→ set_phase({"phase": "explore"}) # Understand existing auth code
→ set_phase({"phase": "plan"}) # Design auth flow
→ set_phase({"phase": "build"}) # Implement the auth code
→ set_phase({"phase": "review"}) # Verify the implementation
- Node.js 22 (LTS)
- Bun (used for dev server and binary compilation)
- corepack enabled (
corepack enable) - pnpm (installed automatically via corepack)
Use the dev startup script to automatically set up the environment and start the harness:
./scripts/dev-startup.shThis script will:
- Check and install node, pnpm, and bun (if missing)
- Install dependencies with
pnpm install - Copy necessary resources
- Start the harness with
pnpm run dev
git clone git@github.com:castai/kimchi.git
cd kimchi
corepack enable
pnpm install| Command | Description |
|---|---|
pnpm run build |
Compile TypeScript to dist/ and copy theme assets |
pnpm run dev |
Run the CLI locally via Bun |
pnpm run check |
Biome lint + TypeScript type check |
pnpm run lint |
Biome lint only |
pnpm run lint:fix |
Biome lint with auto-fix |
pnpm run test |
Run tests with vitest |
Run the folling script to propagate all necessary resources:
node ./scripts/copy-resources.js --dev
Run the CLI directly via Bun:
pnpm run devOr build a standalone binary and run it:
pnpm run build:binary
./dist/bin/kimchisrc/
cli.ts — Entry point
config.ts — Auth & config loading
env.ts — Environment variable helpers
models.ts — Default model definitions
extensions/ — Agent extensions (orchestration, web-fetch)
modes/ — Interactive mode & theme assets
Standalone binaries are built automatically by GitHub Actions when a version tag is pushed (v*). Binaries are compiled with bun build --compile and require no runtime on the user's machine.
Supported platforms:
- macOS (amd64, arm64)
- Linux (amd64, arm64)
Release assets follow the naming convention kimchi_{os}_{arch}.tar.gz with a checksums.txt (SHA256) for verification.
MIT