Kimi-Code Coding Standards: TypeScript Best Practices for the MoonshotAI Agent Framework

The Kimi-Code repository maintains strict TypeScript coding standards enforced via strict mode compiler settings, oxlint validation, and the architectural rules defined in AGENTS.md, ensuring type-safe, modular agent development.

The MoonshotAI/kimi-code repository is a TypeScript monorepo that implements rigorous coding standards to maintain consistency across its AI agent framework. These standards govern everything from export patterns to constructor design, ensuring the codebase remains type-safe, performant, and easy to navigate for contributors.

TypeScript Strictness and Type Safety

The foundation of Kimi-Code's reliability lies in its uncompromising TypeScript configuration.

Strict Compiler Configuration

According to the tsconfig.json settings, the codebase operates with "strict": true enabled. This mandates explicit typing, strict null checks, and disables implicit any throughout the repository. All source files must adhere to these constraints, eliminating runtime type errors at compile time.

Optional Property Handling

Kimi-Code enforces specific patterns for optional values to reduce verbosity and prevent undefined behavior:

• Use the ? modifier instead of declaring properties as type | undefined
• Pass undefined directly rather than wrapping values in conditional spreads

// ✅ Correct: Pass undefined directly
function greet(opts: { name?: string }) {
  const payload = { name: opts.name };
}

// ❌ Incorrect: Conditional spread adds unnecessary complexity
const badPayload = { ...(opts.name ? { name: opts.name } : undefined) };

Module Exports and API Design

The repository maintains strict boundaries around how modules expose their functionality to prevent API surface creep.

Export Style Conventions

Only the package root index.ts may re-export a default export. Every other index.ts throughout the monorepo must use the export * from './module' pattern. As seen in packages/agent-core/src/index.ts, this approach keeps public APIs predictable and prevents accidental internal leakage.

// ✅ Preferred export style throughout the codebase
export * from './utils';
export * from './constants';

Agent Constructor Design

In packages/agent-core/src/agent/Agent.ts, the Agent class must remain usable as a standalone component. The constructor cannot require a Session instance or enforce an explicit agentId. While an optional sessionId hint is permitted, the class must never store session references, enabling flexible reuse of the core engine across different contexts.

// ✅ Valid standalone instantiation
import { Agent } from '@moonshot-ai/agent-core';
const myAgent = new Agent({ model: 'gpt-4o' });

Code Style and Linting

Automated tooling enforces consistency across the large distributed codebase.

Linting with oxlint and TypeScript ESLint

The project uses oxlint (configured in .oxlintrc.json) alongside @typescript-eslint rules to catch anti-patterns. You will find numerous eslint-disable comments throughout the source code, but these are reserved only for unavoidable low-level operations like dynamic property deletions or exhaustive switch checks where the rule would otherwise block valid functionality.

Prettier Formatting

Prettier integration runs through the lint pipeline, ensuring uniform code style across all files. Every commit must pass formatting validation before merging.

Object Construction Patterns

When building objects, the standards forbid unnecessary spreads. Developers should use direct property assignment like { user } instead of conditional spreading patterns that increase bundle size and reduce readability.

Monorepo Maintenance

Kimi-Code uses pnpm workspaces with strict synchronization requirements between build systems.

Workspace Configuration

Any addition or removal of a workspace package requires updates to both pnpm-workspace.yaml and flake.nix. According to the source configuration, missing entries in either file will silently break Nix builds, making this dual-update requirement critical for repository integrity.

Dependency Version Requirements

The package.json enforces specific runtime constraints:

• Node.js: >= 24.15.0
• pnpm: >= 10.33.0
• engine-strict: true (prevents installation with incorrect Node versions)

These restrictions prevent runtime incompatibilities that could affect the agent execution environment.

Feature Flags and Testing

Experimental Flags Registry

Feature flags live in packages/agent-core/src/flags/registry.ts and follow a specific naming convention. Flags are toggled via environment variables using the pattern KIMI_CODE_EXPERIMENTAL_<NAME> or the master KIMI_CODE_EXPERIMENTAL_FLAG variable. This system allows safe rollout of unfinished capabilities without destabilizing the main branch.

// ✅ Checking experimental features
import { flags } from '@moonshot-ai/agent-core';
if (flags.enabled('my-feature')) {
  // New behavior only when explicitly enabled
}

Testing Discipline

The AGENTS.md file specifies that new tests should augment existing test files rather than creating many new individual files. When a test fails after implementation changes, developers must fix the implementation first, changing the test only after proving the implementation contains a bug. This policy maintains high test reliability and prevents regression through specification drift.

Summary

• Strict TypeScript: "strict": true configuration eliminates runtime type errors across the monorepo.
• Export Patterns: Only root index.ts files may default export; all others use export * syntax.
• Agent Design: The Agent class must function standalone without requiring Session or agentId in its constructor.
• Linting Stack: oxlint and @typescript-eslint enforce quality, with Prettier handling formatting consistency.
• Workspace Sync: Changes to pnpm-workspace.yaml must always be mirrored in flake.nix to prevent build failures.
• Version Enforcement: Node >= 24.15.0 and pnpm >= 10.33.0 are mandatory via engine-strict.
• Feature Management: Experimental flags reside in packages/agent-core/src/flags/registry.ts and use KIMI_CODE_EXPERIMENTAL_* environment variables.

Frequently Asked Questions

What linting tools does Kimi-Code use?

The repository uses oxlint configured via .oxlintrc.json combined with @typescript-eslint rules. This dual approach provides fast linting performance while maintaining strict TypeScript-specific checks. Prettier runs within this pipeline to ensure consistent formatting across all TypeScript files.

How are experimental features managed?

Experimental capabilities are controlled through a centralized registry located at packages/agent-core/src/flags/registry.ts. Developers enable these features by setting environment variables prefixed with KIMI_CODE_EXPERIMENTAL_ followed by the feature name, allowing safe testing of unfinished functionality without affecting stable code paths.

What are the specific TypeScript strictness requirements?

The tsconfig.json file enforces "strict": true, which enables all strict type-checking options including strict null checks, no implicit any, and strict function types. Additionally, optional properties must use the ? modifier rather than union types with undefined, and conditional spreads are prohibited in favor of direct undefined assignment.

Why must the Agent constructor remain standalone?

As implemented in packages/agent-core/src/agent/Agent.ts, the Agent class must instantiate without requiring a Session object or explicit agentId. This design constraint ensures the core agent logic remains portable and reusable across different contexts, from testing environments to production sessions, without tight coupling to session management infrastructure.

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