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

> Learn how to enable Kimi Code experimental feature flags. Discover how these boolean toggles control features via environment variables and config files for MoonshotAI kimi-code.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Kimi Code experimental feature flags are boolean toggles defined in the source registry ([`flagRegistry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/persistence/backends/minidb/flag.ts) |

The `search_worker` flag appears at **line 32** of [`searchService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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

```bash

# 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

```bash
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`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml))

```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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/routes/config.ts) handler accepts POST requests to modify the `[experimental]` section without restarting the server:

```bash

# 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

```typescript
// 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

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/routes/meta.ts) route exposes the resolved flag map through the **/api/v1/meta** endpoint.

### CLI Verification

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

```

**Expected output:**

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

```

### Programmatic Verification

```typescript
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`:

```bash

# 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`](https://github.com/MoonshotAI/kimi-code/blob/main/flagRegistry.ts) for registration, individual [`flag.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/flag.ts) files for definitions, [`searchService.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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.