How Applications Are Organized Within the Kimi-Code Monorepo Structure

Kimi-Code uses a TypeScript monorepo layout that separates standalone applications in apps/ from reusable libraries in packages/, coordinated by pnpm-workspace.yaml and mirrored in flake.nix for reproducible builds.

The MoonshotAI/kimi-code repository follows a strict workspace-driven architecture that enables independent development of front-end applications while sharing a unified core engine. By partitioning runnable binaries from shared business logic, the project maintains clean dependency boundaries and supports multiple build targets—including both pnpm and Nix ecosystems.

Root-Level Workspace Configuration

Every monorepo member is declared in pnpm-workspace.yaml, which serves as the single source of truth for the Node.js package manager. This file defines the glob patterns that include all directories under apps/ and packages/, ensuring that inter-package dependencies are correctly linked during installation.

The repository also maintains a flake.nix at the root, which mirrors the pnpm-workspace.yaml definitions for Nix-based builds. Keeping these two files synchronized is critical; the repository includes scripts/check-nix-workspace.mjs to validate that every entry in the pnpm configuration has a corresponding entry in the Nix flake.

The Apps Directory Structure

The apps/ directory contains self-contained, runnable front-end applications. Currently, the primary entry point is the Visual Studio Code extension located at apps/vscode.

VS Code Extension Layout

The VS Code extension follows a two-part architecture:

• Extension Host: The Node.js back-end that interacts with the VS Code API
• Webview UI: A React-based front-end located in apps/vscode/webview-ui/, bootstrapped at src/main.tsx

This separation allows the extension to present a rich user interface while maintaining secure communication between the webview and the core extension logic. The application is buildable independently using workspace filters:

# Build only the VS Code extension in watch mode

pnpm --filter @moonshot-ai/kimi-code-vscode dev

To run the extension locally for development:

# Install dependencies for the entire workspace first

pnpm install

# Launch extension host with the development build

code --extensionDevelopmentPath=apps/vscode

Shared Packages Architecture

Reusable libraries live under packages/ and are published under the @moonshot-ai/* npm scope. These packages provide the core engine functionality consumed by all applications in the monorepo.

Key packages include:

• packages/tree-sitter-bash/: A pure-TypeScript Bash parser used by the agent engine, exposing its API via src/parser.ts
• packages/oauth/: Authentication utilities that handle Kimi service integration, located in src/oauth-manager.ts
• packages/agent-core/: The central engine powering AI agent operations
• packages/klient/: The public SDK for external consumers
• packages/telemetry/, packages/transcript/, packages/kosong/, packages/kaos/: Supporting infrastructure for execution environment, logging, and model abstractions

Each package maintains its own README.md, test suite, and build configuration, allowing them to be developed and versioned independently while respecting the workspace dependency graph.

Build and Development Workflow

The repository employs a dual-build strategy supporting both JavaScript and Nix ecosystems. When adding new packages, developers must register them in both configuration files.

Adding a New Package

To introduce a new library to the monorepo:

# Create the package structure

mkdir -p packages/my-new-lib/src

# Initialize with pnpm workspace integration

pnpm init -w packages/my-new-lib

# Create public API entry point

echo "export * from './src/index';" > packages/my-new-lib/index.ts

After modifying pnpm-workspace.yaml, synchronize the Nix configuration:

# Validate and sync workspace definitions

node scripts/check-nix-workspace.mjs

Continuous Integration

The .github/workflows/ci.yml pipeline orchestrates testing and building across all workspace members. It validates that both the pnpm and Nix workspaces remain in sync, runs unit tests for individual packages, and bundles native applications—ensuring that changes to shared libraries do not break downstream applications in apps/.

Summary

• Workspace Declaration: pnpm-workspace.yaml and flake.nix define all monorepo members at the root level
• Apps Directory: Contains standalone front-ends like apps/vscode with its React-based webview-ui sub-component
• Packages Directory: Houses reusable TypeScript libraries under the @moonshot-ai/* scope, including tree-sitter-bash, oauth, and agent-core
• Sync Scripts: scripts/check-nix-workspace.mjs ensures consistency between package manager and Nix flake definitions
• Independent Execution: Applications can be built and run in isolation using pnpm --filter while sharing linked dependencies from packages/

Frequently Asked Questions

How does Kimi-Code handle dependency management across the monorepo?

The repository uses pnpm workspaces to automatically link dependencies between packages/ and apps/. When you run pnpm install at the root, pnpm installs all dependencies and creates symbolic links for internal packages, allowing apps/vscode to import from packages/agent-core using standard npm imports like @moonshot-ai/agent-core without manual path mapping.

What is the purpose of the flake.nix file in a JavaScript monorepo?

The flake.nix file provides reproducible builds for Nix users and CI pipelines. It declares the same workspace members as pnpm-workspace.yaml but enables native compilation and dependency management through the Nix package manager. The scripts/check-nix-workspace.mjs script validates that both files remain synchronized, preventing build failures on Nix-based systems.

Can I run the VS Code extension without building the entire monorepo?

No, you must install dependencies for the entire workspace first using pnpm install at the root. However, you can build and run only the VS Code extension using the filter flag: pnpm --filter @moonshot-ai/kimi-code-vscode dev. This builds only the extension and its transitive dependencies while skipping unrelated packages, significantly reducing build time.

Where should new UI applications be added in the Kimi-Code repository?

New front-end applications should be created as subdirectories under apps/, following the pattern established by apps/vscode/. Each application should contain its own package.json, source directory, and entry point. After creation, ensure the directory is captured by the globs in pnpm-workspace.yaml (typically automatically if using standard naming) and run the Nix sync script to maintain build compatibility.

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