How to Enable Kimi Code Experimental Feature Flags: A Complete Guide

Kimi Code experimental feature flags are boolean toggles defined in the source registry (flagRegistry.ts) and controlled via environment variables prefixed with KIMI_CODE_EXPERIMENTAL_ or the [experimental] section in the config file, with the current state exposed through the /api/v1/meta endpoint.

Kimi Code, MoonshotAI's open-source coding agent, ships with a flexible experimental feature flag system that allows developers to safely test in-development capabilities without affecting stable workflows. This guide explains where these flags are defined, which flags are currently available, and how to enable or disable them using multiple methods.

Where Experimental Flags Are Defined

The Kimi Code codebase uses a centralized FlagService architecture. Flag definitions are scattered across relevant subsystems but registered through a common registry pattern.

Core Registry Location

In packages/agent-core-v2/src/app/flag/flagRegistry.ts, the registerFlagDefinition() function collects all experimental flags into a runtime map. This registry merges values from three sources in priority order:

1. Built-in defaults (hardcoded per flag)
2. Environment variables (KIMI_CODE_EXPERIMENTAL_*)
3. [experimental] config section (highest priority, mutable at runtime)

Current Flag Definitions

Flag ID	Description	Default	Source File
tool-select	Enables dynamic tool selection UI where the model picks from available tools	false	packages/agent-core-v2/src/agent/toolSelect/flag.ts
search_worker	Runs search service in an out-of-process worker for isolation	false	packages/kap-server/src/search/searchService.ts
persistence_minidb_readmodel	Uses MiniDB backend for session persistence read models	true	packages/agent-core-v2/src/persistence/backends/minidb/flag.ts

The search_worker flag appears at line 32 of searchService.ts, where the service checks the flag before spawning the worker process. The persistence_minidb_readmodel flag at packages/agent-core-v2/src/persistence/backends/minidb/flag.ts controls whether MiniDB serves as the read-model backend for persistence operations.

Method 1: Enable Flags via Environment Variables

The fastest way to toggle a flag for a single session is setting an environment variable. The naming convention converts the flag ID to upper snake case prefixed with KIMI_CODE_EXPERIMENTAL_.

Bash Examples

# Enable tool-selection feature

export KIMI_CODE_EXPERIMENTAL_TOOL_SELECT=true

# Disable search worker (force in-process search)

export KIMI_CODE_EXPERIMENTAL_SEARCH_WORKER=false

# Start Kimi Code with flags applied

npm start

Docker Example

docker run -e KIMI_CODE_EXPERIMENTAL_TOOL_SELECT=true \
           -e KIMI_CODE_EXPERIMENTAL_SEARCH_WORKER=false \
           moonshotai/kimi-code:latest

Environment variables accept truthy values (1, true, yes, on) and falsy values (0, false, no, off). They take effect immediately on process startup without file modifications.

Method 2: Enable Flags via Config File

For persistent, cross-session configuration, use the [experimental] TOML section in the Kimi Code configuration file.

Static Config File (config.toml)

[experimental]
tool-select = true
search_worker = false
persistence_minidb_readmodel = true

The config file location follows standard XDG conventions:

• Linux/macOS: ~/.config/kimi-code/config.toml
• Windows: %APPDATA%\kimi-code\config.toml

Dynamic Runtime Updates via REST API

The packages/kap-server/src/routes/config.ts handler accepts POST requests to modify the [experimental] section without restarting the server:

# Enable tool-select live

curl -X POST http://localhost:3000/api/v1/config \
  -H "Content-Type: application/json" \
  -d '{"experimental":{"tool-select":true}}'

# Disable search_worker live

curl -X POST http://localhost:3000/api/v1/config \
  -H "Content-Type: application/json" \
  -d '{"experimental":{"search_worker":false}}'

Changes via the API are immediately effective—the FlagService re-evaluates the effective flag map on every configuration read.

Method 3: Programmatic Control in TypeScript

For embedded deployments or custom clients, manipulate flags through the internal APIs.

Setting Flags Before Server Startup

// Set environment-style flags in process.env
process.env.KIMI_CODE_EXPERIMENTAL_TOOL_SELECT = 'true';
process.env.KIMI_CODE_EXPERIMENTAL_SEARCH_WORKER = 'false';

// Import and start server (flags read at initialization)
import { createServer } from '@moonshot-ai/kap-server';

const server = await createServer();
await server.listen(3000);

Runtime Flag Updates via Internal API

import { FlagService } from '@moonshot-ai/agent-core-v2/app/flag';

// Access the singleton flag service
const flags = FlagService.getInstance();

// Check current state
const toolSelectEnabled = flags.get('tool-select');
console.log(`Tool select: ${toolSelectEnabled}`);

// Update via config mutation (triggers re-evaluation)
await flags.updateConfigSection('experimental', {
  'tool-select': true,
  'search_worker': false
});

Verifying Flag State

The packages/kap-server/src/routes/meta.ts route exposes the resolved flag map through the /api/v1/meta endpoint.

CLI Verification

curl -s http://localhost:3000/api/v1/meta | jq '.experimental_flags'

Expected output:

{
  "tool-select": true,
  "search_worker": false,
  "persistence_minidb_readmodel": true
}

Programmatic Verification

import axios from 'axios';

const response = await axios.get('http://localhost:3000/api/v1/meta');
const flags = response.data.experimental_flags;

if (flags['tool-select']) {
  console.log('Tool selection UI is active');
}

Priority and Conflict Resolution

When the same flag is set through multiple channels, the highest-priority source wins:

Priority	Source	Mutable at Runtime?
1 (lowest)	Built-in default	No
2	Environment variable	No (requires restart)
3 (highest)	[experimental] config section	Yes

Example scenario: If KIMI_CODE_EXPERIMENTAL_TOOL_SELECT=false is set in the environment but the config file contains [experimental]\ntool-select = true, the config file value overrides and the flag is enabled.

Disabling Experimental Features

Disabling follows the same patterns as enabling—simply set the flag to false:

# Environment variable

export KIMI_CODE_EXPERIMENTAL_TOOL_SELECT=false

# Or in config

[experimental]
tool-select = false

To completely disable all experimental features, omit the [experimental] section from your config and unset all KIMI_CODE_EXPERIMENTAL_* environment variables. The system falls back to conservative built-in defaults (all flags false except persistence_minidb_readmodel).

Summary

• Three flags are currently implemented: tool-select, search_worker, and persistence_minidb_readmodel
• Two control methods: Environment variables (KIMI_CODE_EXPERIMENTAL_*) and the [experimental] config section
• One verification endpoint: GET /api/v1/meta returns the effective experimental_flags map
• Config overrides environment: Runtime config changes take precedence and apply without restart
• Source files to inspect: flagRegistry.ts for registration, individual flag.ts files for definitions, searchService.ts for usage examples

Frequently Asked Questions

What happens if I set an undefined flag name?

Undefined flags are silently ignored. The FlagService only recognizes flags explicitly registered via registerFlagDefinition(). No error is thrown, and the flag does not appear in /api/v1/meta responses. Check your spelling against the official flag IDs listed in this guide.

Do experimental flags persist across server restarts?

Only flags set through the config file persist across restarts. Environment variables must be re-exported in each new shell session. Runtime API changes persist in memory but are lost on restart unless explicitly saved to the config file.

Why is persistence_minidb_readmodel enabled by default?

The MiniDB read-model backend has proven stable in production workloads, so MoonshotAI enabled it by default while retaining the flag for emergency rollback capability. The other flags (tool-select, search_worker) guard newer architectural changes still under evaluation.

Can I use experimental flags in the Kimi Code CLI versus the server?

Yes. The same flag system applies to both. Set environment variables before invoking the CLI, or ensure your CLI config file includes the [experimental] section. The CLI reads from the same configuration sources as the server.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}