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

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. 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, 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 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. 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.

// 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>
`;

// 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. You can also set the KIMI_TUI_THEME environment variable to load predefined schemes at startup.

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 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.

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.

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 and invoke its registration API. Refer to .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:

// 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:

// 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 (CLI), apps/kimi-code/src/tui/tui-state.ts (state), and 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, 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 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 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. This file exports the base Theme type and default color values that the orchestrator loads unless overridden by runtime configuration or environment variables.

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