# How the Kimi-Code TUI Is Built and How to Customize the Terminal Interface

> Explore the modular architecture of Kimi-Code TUI. Learn how to customize the terminal interface with widget composition, theme overrides, and keymap modifications.

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

---

**Kimi-Code's terminal interface is built on a modular architecture separating the CLI entry point, state orchestration, and a reusable `pi-tui` rendering engine, allowing customization through widget composition, theme overrides, keymap modifications, and runtime configuration files.**

The **Kimi-Code TUI** (Terminal User Interface) delivers the interactive command-line experience for the MoonshotAI/kimi-code repository. Located in the `apps/kimi-code` package, the interface acts as a thin wrapper around the `@moonshot-ai/kimi-code-sdk` and delegates low-level terminal rendering to the isolated `pi-tui` component library.

## Architecture of the Kimi-Code TUI

The codebase follows a strict layered design that decouples rendering primitives from business logic, enabling both stability and extensibility.

### CLI Entry Point and SDK Integration

Every session begins at [`apps/kimi-code/src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/main.ts). This file parses command-line arguments, initializes the SDK, and hands control to the TUI orchestrator. It serves as the bootstrap sequence that wires core logic into the visual interface without mixing concerns.

### The pi-tui Rendering Engine

At the heart of the system lies [`packages/pi-tui/src/tui.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/pi-tui/src/tui.ts), which exports a **`createTui`** factory function. This engine receives a **state object** and a **render function**, returning an API surface with `mount()`, `unmount()`, `update()`, and `dispose()` methods. The `pi-tui` package is deliberately isolated so the same rendering primitives can be reused by other projects, such as end-to-end testing suites.

### State Orchestration and Screen Routing

The file [`apps/kimi-code/src/tui/tui-state.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/tui/tui-state.ts) serves as the orchestrator. It maintains global UI state—including selected sessions, active panels, and cursor positions—and constructs the concrete state tree passed to the `pi-tui` renderer on every change. This file also manages the `screenMap` that routes user actions to specific widget trees.

### Widget Library and Theming

Reusable interface elements live in `packages/pi-tui/src/widgets/*`, while default aesthetics are defined in [`packages/pi-tui/src/theme.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/pi-tui/src/theme.ts). The theme system supports runtime overrides through environment variables like `KIMI_TUI_THEME` or direct object injection into the `createTui` factory.

## Customizing the Terminal Interface

Developers can modify the interface without altering core SDK logic by working within the `apps/kimi-code/src/tui` directory and the public `pi-tui` API.

### Adding New Screens and Panels

To introduce a new view, create a widget file under `apps/kimi-code/src/tui/widgets/`. Export a function that accepts the global UI state and returns a `pi-tui` component tree using the `view` tagged template literal. Then register the widget in the `screenMap` object within [`tui-state.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/tui-state.ts).

```typescript
// apps/kimi-code/src/tui/widgets/my-panel.ts
import { view } from '#/pi-tui';

export const MyPanel = (state) => view`
  <box borderColor="cyan" title="My Panel">
    <text>${state.message}</text>
  </box>
`;

```

```typescript
// apps/kimi-code/src/tui/tui-state.ts
import { MyPanel } from './widgets/my-panel';

const screenMap = {
  // ...existing screens
  myPanel: MyPanel,
};

```

### Overriding Themes and Colors

Customize the color palette by supplying a **`Theme`** object when calling `createTui`. The `Theme` type is defined in [`packages/pi-tui/src/theme.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/pi-tui/src/theme.ts). You can also set the `KIMI_TUI_THEME` environment variable to load predefined schemes at startup.

```typescript
import { createTui } from '#/pi-tui';

const customTheme = {
  primary: '#ff6f61',
  secondary: '#2e3440',
  background: '#1d2021',
};

const tui = createTui({ state: initialState, theme: customTheme });

```

### Modifying Key Bindings

The orchestrator defines a **`keyMap`** in [`tui-state.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/tui-state.ts) that maps input sequences to action identifiers. Edit this table to add or replace keystrokes; the `pi-tui` input handling layer applies changes immediately without requiring a restart of the render loop.

```typescript
const keyMap = {
  'ctrl+c': 'quit',
  'ctrl+d': 'duplicateSession', // custom binding
};

```

### Runtime Configuration via CLI

The CLI accepts a **`--tui-config <path>`** argument pointing to a JSON file. The orchestrator loads this file via `fs.readFileSync` and merges it with built-in defaults, allowing end-users to customize behavior without touching source code.

```bash
kimi-code --tui-config ./my-tui-config.json

```

### Extending with Plugins

Because `pi-tui` is published as a standard npm package (`@moonshot-ai/pi-tui`), you can develop standalone plugin packages. Import your plugin into [`tui-state.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/tui-state.ts) and invoke its registration API. Refer to [`.agents/skills/write-tui/SKILL.md`](https://github.com/MoonshotAI/kimi-code/blob/main/.agents/skills/write-tui/SKILL.md) for the official contributor guidelines on plugin architecture and lifecycle management.

## Implementation Examples

Mounting the TUI with full configuration:

```typescript
// apps/kimi-code/src/main.ts
import { createTui } from '#/pi-tui';
import { initialState, customKeyMap } from './tui/tui-state';

const tui = createTui({
  state: initialState,
  theme: { primary: '#00ff00', background: '#000000' },
  keyMap: customKeyMap,
});

tui.mount();  // Starts the render loop

```

Creating a reusable status bar widget:

```typescript
// apps/kimi-code/src/tui/widgets/status-bar.ts
import { view } from '#/pi-tui';

export const StatusBar = (state) => view`
  <box bg="black" fg="white" height="1">
    <text>Session: ${state.sessionId} | Mode: ${state.mode}</text>
  </box>
`;

```

## Summary

- The Kimi-Code TUI architecture separates concerns across [`apps/kimi-code/src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/main.ts) (CLI), [`apps/kimi-code/src/tui/tui-state.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/tui/tui-state.ts) (state), and [`packages/pi-tui/src/tui.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/pi-tui/src/tui.ts) (rendering).
- The **`createTui`** factory in `pi-tui` provides `mount()`, `unmount()`, `update()`, and `dispose()` lifecycle methods for managing the terminal session.
- Customization occurs through widget composition in `apps/kimi-code/src/tui/widgets/`, theme overrides via [`packages/pi-tui/src/theme.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/pi-tui/src/theme.ts), and keymap edits in the orchestrator.
- Runtime configuration is supported via **`--tui-config`** JSON files and environment variables like `KIMI_TUI_THEME`.
- The `pi-tui` package is reusable and supports external plugin development according to the [`.agents/skills/write-tui/SKILL.md`](https://github.com/MoonshotAI/kimi-code/blob/main/.agents/skills/write-tui/SKILL.md) specification.

## Frequently Asked Questions

### What is the difference between pi-tui and the main Kimi-Code TUI?

`pi-tui` is the low-level rendering library in `packages/pi-tui/` that provides terminal drawing primitives and the `createTui` factory, while the main TUI in `apps/kimi-code/src/tui/` implements the specific screens, business logic, and SDK integration for the Kimi-Code CLI.

### How do I add a new keyboard shortcut to the terminal interface?

Edit the **`keyMap`** object in [`apps/kimi-code/src/tui/tui-state.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/tui/tui-state.ts) to map a keystroke sequence (e.g., `'ctrl+d'`) to an action identifier. The `pi-tui` input layer automatically recognizes new entries and applies them to the active session.

### Can I use the pi-tui library in my own Node.js projects?

Yes. `pi-tui` is designed as an isolated package that can be imported from `@moonshot-ai/pi-tui`. It exports `createTui`, theme utilities, and widget primitives for general-purpose terminal applications, independent of the Kimi-Code SDK.

### Where are the default color themes defined in the source code?

Default color palettes are defined in [`packages/pi-tui/src/theme.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/pi-tui/src/theme.ts). This file exports the base `Theme` type and default color values that the orchestrator loads unless overridden by runtime configuration or environment variables.