# How to Use Experimental Flags to Enable New Features in Kimi Code

> Unlock Kimi Code experimental features using environment variables, config files, or programmatic overrides. Leverage runtime flags to test new capabilities effortlessly.

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

---

**Kimi Code provides a runtime feature-flag system that lets you toggle experimental capabilities via environment variables, [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml), or programmatic overrides without modifying source code.**

The MoonshotAI/kimi-code repository ships with a lightweight, type-safe feature-flag system located in `packages/agent-core/src/flags/` that manages experimental functionality at runtime. This architecture allows you to activate bleeding-edge features for specific sessions or globally across your installation using a hierarchical resolution mechanism that prioritizes environment variables over configuration files.

## Architecture of the Experimental Flag System

Kimi Code’s flag system consists of three core components that work together to provide compile-time safety and runtime flexibility.

### Flag Registry

The **flag registry** in [`packages/agent-core/src/flags/registry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/flags/registry.ts) declares all experimental capabilities as a compile-time constant. Each registry entry specifies an identifier (`id`), human-readable title, description, environment variable name, default boolean state, and surface designation (`'core'`, `'tui'`, or `'both'`). The registry uses TypeScript’s `as const satisfies` construct to generate a union type (`FlagId`) that enables autocomplete and prevents invalid flag references during development.

### Flag Resolver

The `FlagResolver` class in [`packages/agent-core/src/flags/resolver.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/flags/resolver.ts) implements the resolution algorithm that determines whether a flag is active. This pure, synchronous class evaluates the current process environment against registry defaults on every call, meaning changes to `process.env` reflect immediately without requiring application restarts. The resolver exposes diagnostic methods including `explain()` and `explainAll()` that reveal which source (environment, config, or default) determined a flag’s current state.

A global singleton `flags` is exported for convenience, though individual `KimiCore`, `Session`, and `Agent` instances maintain their own scoped resolvers for isolated behavior.

### Type Definitions

Static typing contracts reside in [`packages/agent-core/src/flags/types.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/flags/types.ts), defining interfaces for `FlagId`, surface categories, and the resolver’s public API. These types ensure that flag identifiers referenced in code exist in the registry and that surface annotations correctly categorize where features are consumed.

## Flag Resolution Precedence

The resolver applies a strict hierarchy when determining flag state, reading sources from highest to lowest priority:

1. **Master switch**: The `KIMI_CODE_EXPERIMENTAL_FLAG` environment variable forces every experimental flag to `true` when set to a truthy value.
2. **Per-flag environment variables**: Individual variables like `KIMI_CODE_EXPERIMENTAL_TOOL_SELECT` override the registry default for specific flags only.
3. **Configuration file**: Values in the `[experimental]` section of [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml) provide project-level persistence across runs.
4. **Registry defaults**: The `default` field in the registry entry serves as the fallback when no other source applies.

## Enabling Experimental Flags

### Using Environment Variables

Set the appropriate variable before launching the Kimi Code process to activate features without touching configuration files:

```bash

# Enable a specific experimental feature

export KIMI_CODE_EXPERIMENTAL_TOOL_SELECT=1

# Or enable all experimental flags at once (useful for CI/CD)

export KIMI_CODE_EXPERIMENTAL_FLAG=1

pnpm start

```

For containerized deployments, inject these variables into your Docker runtime configuration or `.env` file (the repository respects standard dotenv loading).

### Using config.toml

For persistent, project-level overrides that survive across sessions, add flag declarations to your configuration file:

```toml
[experimental]
tool-select = true
another-feature = false

```

Settings in [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml) yield to environment variables but override registry defaults, making them ideal for team-wide feature rollouts.

### Programmatic Control

Instantiate a custom `FlagResolver` for scoped behavior in tests or isolated agent sessions:

```typescript
import { FlagResolver } from '#/flags/resolver';
import { registry } from '#/flags/registry';

// Create a resolver with custom environment and config overrides
const testResolver = new FlagResolver(
  { KIMI_CODE_EXPERIMENTAL_TOOL_SELECT: '1' }, // simulated env
  registry,                                    // flag definitions
  { 'tool-select': false }                    // config.toml override
);

// Resolution respects the precedence: config > env > default
console.log(testResolver.enabled('tool-select')); // → false

```

## Practical Code Examples

Access the global resolver to conditionally execute experimental code paths:

```typescript
import { flags } from '#/flags';

// Check if progressive tool disclosure is active
if (flags.enabled('tool-select')) {
  // Execute experimental tool selection logic
}

// Debugging: Inspect how a flag was resolved
const state = flags.explain('tool-select');
console.log(
  `Flag ${state?.id} (${state?.title}) is ${state?.enabled ? 'ON' : 'OFF'} via ${state?.source}`
);

// Audit all experimental flags currently enabled
const allFlags = flags.explainAll();
allFlags.forEach(flag => {
  if (flag.enabled) console.log(`${flag.id}: ${flag.title}`);
});

```

## Summary

- **Flag Registry** ([`packages/agent-core/src/flags/registry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/flags/registry.ts)) defines all experimental features with metadata including defaults and surface categories.
- **Flag Resolver** ([`packages/agent-core/src/flags/resolver.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/flags/resolver.ts)) implements precedence logic (master switch → env → config → default) and provides the `enabled()` API.
- **Environment variables** offer the highest precedence control, with `KIMI_CODE_EXPERIMENTAL_FLAG` acting as a global master switch for all experimental features.
- **Type Safety** is enforced via `FlagId` union types generated from the registry, preventing references to undefined flags during compilation.
- **Scoped Instances** allow tests and individual sessions to override flag behavior without affecting the global state.

## Frequently Asked Questions

### What is the fastest way to enable all experimental features in Kimi Code?

Set the `KIMI_CODE_EXPERIMENTAL_FLAG=1` environment variable before starting the application. This master switch short-circuits the resolver and returns `true` for every registered experimental flag, useful for debugging or CI pipelines that need comprehensive feature coverage.

### How do I check which source activated a specific experimental flag?

Call the `explain()` method on any resolver instance (such as the global `flags` object). This returns metadata including the `source` field, which indicates whether the flag state was determined by the master switch, a specific environment variable, [`config.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml), or the registry default.

### Can I override experimental flags for a single session without affecting global settings?

Yes. Create a new `FlagResolver` instance in [`packages/agent-core/src/flags/resolver.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/flags/resolver.ts) and pass custom environment variables or configuration objects to its constructor. Each `KimiCore`, `Session`, and `Agent` maintains its own resolver instance, allowing scoped flag behavior that does not interfere with the global `flags` singleton.

### Where are the experimental flags defined in the Kimi Code source?

All experimental flags are declared in [`packages/agent-core/src/flags/registry.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/flags/registry.ts). This file contains the compile-time list of available features, their environment variable names, default states, and surface designations indicating whether they affect core logic, the TUI, or both.