# How Applications Are Organized Within the Kimi-Code Monorepo Structure

> Discover how Kimi Code organizes its applications within a TypeScript monorepo. Learn about the separation of apps and packages managed by pnpm workspace and flake.nix.

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

---

**Kimi-Code uses a TypeScript monorepo layout that separates standalone applications in `apps/` from reusable libraries in `packages/`, coordinated by [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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:

```bash

# Build only the VS Code extension in watch mode

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

```

To run the extension locally for development:

```bash

# 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`](https://github.com/MoonshotAI/kimi-code/blob/main/src/parser.ts)
- **`packages/oauth/`**: Authentication utilities that handle Kimi service integration, located in [`src/oauth-manager.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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:

```bash

# 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`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml), synchronize the Nix configuration:

```bash

# Validate and sync workspace definitions

node scripts/check-nix-workspace.mjs

```

### Continuous Integration

The [`.github/workflows/ci.yml`](https://github.com/MoonshotAI/kimi-code/blob/main/.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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json), source directory, and entry point. After creation, ensure the directory is captured by the globs in [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) (typically automatically if using standard naming) and run the Nix sync script to maintain build compatibility.