How to Install the pi-tui Package from Kimi-Code: A Complete Guide

You can install the private @moonshot-ai/pi-tui package by cloning the MoonshotAI/kimi-code monorepo and referencing it via pnpm workspaces or local file paths, since it is not published to the public npm registry.

The @moonshot-ai/pi-tui package is a private, vendored copy of the pi-tui terminal UI framework located in the packages/pi-tui directory of the Kimi-Code repository. As a workspace dependency marked private: true in packages/pi-tui/package.json, it cannot be installed via npm install from the public registry. Instead, you must integrate it directly from the source tree using pnpm's workspace protocol or file references.

Understanding the Package Structure

The pi-tui package lives under packages/pi-tui in the MoonshotAI/kimi-code monorepo. According to the source code, this is a vendored framework consumed by the Kimi-Code CLI/TUI application. The monorepo's root pnpm-workspace.yaml declares packages/* as workspace members, which allows any package to resolve @moonshot-ai/pi-tui from the local source automatically.

Key characteristics of this package:

• Package name: @moonshot-ai/pi-tui
• Privacy status: Marked "private": true in packages/pi-tui/package.json
• Location: packages/pi-tui/src/tui.ts contains the core TUI class implementation
• Consumption: Used by apps/kimi-code/src/tui/theme/pi-tui-theme.ts for the CLI's custom theme

Installation Options

Because the package is not published, you have two primary methods to install and use it in your projects.

Option 1: Work Inside the Kimi-Code Monorepo

Use this approach when developing features for Kimi-Code itself or creating packages within the same workspace.

1. Clone the repository:

git clone https://github.com/MoonshotAI/kimi-code.git
cd kimi-code

2. Install all workspace dependencies:

pnpm install

3. Import the package using its workspace name in your TypeScript code:

import { TUI, Text, Editor } from "@moonshot-ai/pi-tui"

Option 2: Use in an External Project

Use this approach when embedding the terminal UI components in a separate Node/TypeScript project without publishing to a registry.

1. Clone the Kimi-Code repository (or add it as a git submodule) adjacent to your project:

git clone https://github.com/MoonshotAI/kimi-code.git ../kimi-code

2. From the repository root, install dependencies:

cd ../kimi-code && pnpm install

3. In your external project's package.json, add either a workspace reference (if using pnpm workspaces) or a file reference:

For pnpm workspaces:

{
  "dependencies": {
    "@moonshot-ai/pi-tui": "workspace:*"
  }
}

For local file reference (npm/yarn/pnpm):

{
  "dependencies": {
    "@moonshot-ai/pi-tui": "file:../kimi-code/packages/pi-tui"
  }
}

4. Run pnpm install (or npm install) in your project directory. The package manager will symlink the local copy of pi-tui into your node_modules.

5. Import symbols as shown in the usage example below.

Basic Usage Example

Once installed, you can create flicker-free, component-based terminal interfaces. The following example demonstrates the core classes defined in packages/pi-tui/src/tui.ts:

// example.ts – minimal "Hello World" using pi-tui
import { TUI, Text, ProcessTerminal, matchesKey } from "@moonshot-ai/pi-tui";

// 1️⃣ Create a terminal that talks directly to STDOUT/STDIN
const terminal = new ProcessTerminal();

// 2️⃣ Build the TUI container
const tui = new TUI(terminal);

// 3️⃣ Add a simple text component
tui.addChild(new Text("👋 Welcome to my app!"))

// 4️⃣ Hook Ctrl-C to exit cleanly
tui.addInputListener((data) => {
  if (matchesKey(data, "ctrl+c")) {
    tui.stop();
    process.exit(0);
  }
});

// 5️⃣ Start the rendering loop
tui.start();

Run the example (ensure the repository is installed as described above):

npx tsx example.ts

Key Source Files to Reference

When working with the pi-tui package from the Kimi-Code repository, consult these files:

• packages/pi-tui/README.md – Overview, features, quick-start snippets, and development commands
• packages/pi-tui/package.json – Declares the package name, privacy status, and dependency list
• packages/pi-tui/src/tui.ts – Core TUI class implementation; the heart of the rendering engine
• apps/kimi-code/src/tui/theme/pi-tui-theme.ts – Demonstrates how the Kimi-Code CLI customizes the pi-tui theme
• apps/kimi-code/README.md – General installation instructions showing the CLI itself installs via npm install -g @moonshot-ai/kimi-code

Summary

• The @moonshot-ai/pi-tui package is a private, vendored dependency located at packages/pi-tui in the Kimi-Code monorepo.
• You cannot install it from npm; you must clone the MoonshotAI/kimi-code repository and reference the local source.
• Use pnpm install from the repo root to set up workspace dependencies.
• Reference the package via workspace:* (within the monorepo) or file: paths (external projects).
• The main implementation resides in packages/pi-tui/src/tui.ts, exposing the TUI class and ProcessTerminal for building terminal interfaces.

Frequently Asked Questions

Why can't I install @moonshot-ai/pi-tui from npm?

The package is marked "private": true in its package.json, meaning it is intentionally excluded from publication to the npm registry. It exists solely as a vendored workspace dependency within the Kimi-Code monorepo to support the CLI's terminal interface.

Can I use this package with npm or yarn instead of pnpm?

While the Kimi-Code repository uses pnpm workspaces, you can reference the local package using standard file: protocol paths in npm or yarn. However, you must still run pnpm install inside the cloned kimi-code repository to ensure all internal dependencies resolve correctly before linking to your external project.

Where is the main TUI implementation located?

The core TUI class implementation is located at packages/pi-tui/src/tui.ts. This file contains the rendering engine and component lifecycle management that powers the terminal interface.

How does Kimi-Code customize the pi-tui theme?

According to the source code in apps/kimi-code/src/tui/theme/pi-tui-theme.ts, the Kimi-Code CLI imports components from @moonshot-ai/pi-tui and applies custom styling and theming configurations to match the application's visual design language.

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