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

Kimi Code provides a runtime feature-flag system that lets you toggle experimental capabilities via environment variables, 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 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 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, 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 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:

# 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:

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

Settings in 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:

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:

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) defines all experimental features with metadata including defaults and surface categories.
• Flag Resolver (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, 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 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. 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.

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