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

> Discover Kimi-Code coding standards for MoonshotAI Agent Framework. Learn TypeScript best practices for type-safe and modular agent development with oxlint and strict mode.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: best-practices
- Published: 2026-07-29

---

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

```typescript
// ✅ 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`](https://github.com/MoonshotAI/kimi-code/blob/main/index.ts) may re-export a default export. Every other [`index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/index.ts) throughout the monorepo must use the `export * from './module'` pattern. As seen in [`packages/agent-core/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/index.ts), this approach keeps public APIs predictable and prevents accidental internal leakage.

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

```

### Agent Constructor Design

In [`packages/agent-core/src/agent/Agent.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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.

```typescript
// ✅ 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`](https://github.com/MoonshotAI/kimi-code/blob/main/.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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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.

```typescript
// ✅ 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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/.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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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.