Hero Kimi

hero_kimi is the Hero OS edition of the wonderful Kimi Code CLI — an AI agent that runs in your terminal, reads and edits code, runs shell commands, browses the web, and autonomously plans and adjusts its actions while it works.

This fork tailors the upstream agent to the Hero stack: the welcome banner reads Hero Kimi, the embedded web UI is wired up for use inside the Hero admin surface, and there's a one-shot scripts/bundle.sh that produces a single self-contained, platform-tagged binary you can drop on any machine.

Gratitude & acknowledgement

We are deeply grateful to the Moonshot AI team for building and open-sourcing Kimi Code CLI. Their work is the foundation everything here stands on, and we are honored to extend it so it fits naturally into the Hero OS world. All of the agent intelligence, the shell mode, the ACP integration, and the web UI are their contribution; our role is just to make them feel at home alongside the rest of the Hero tooling.

Upstream project: https://github.com/MoonshotAI/kimi-cli · Documentation · 文档

Getting Started

See Getting Started for how to install and start using Kimi Code CLI.

Key Features

Shell command mode

Kimi Code CLI is not only a coding agent, but also a shell. You can switch the shell command mode by pressing Ctrl-X. In this mode, you can directly run shell commands without leaving Kimi Code CLI.

Note

Built-in shell commands like cd are not supported yet.

VS Code extension

Kimi Code CLI can be integrated with Visual Studio Code via the Kimi Code VS Code Extension.

IDE integration via ACP

Kimi Code CLI supports Agent Client Protocol out of the box. You can use it together with any ACP-compatible editor or IDE.

To use Kimi Code CLI with ACP clients, make sure to run Kimi Code CLI in the terminal and send /login to complete the login first. Then, you can configure your ACP client to start Kimi Code CLI as an ACP agent server with command kimi acp.

For example, to use Kimi Code CLI with Zed or JetBrains, add the following configuration to your ~/.config/zed/settings.json or ~/.jetbrains/acp.json file:

{
  "agent_servers": {
    "Kimi Code CLI": {
      "type": "custom",
      "command": "kimi",
      "args": ["acp"],
      "env": {}
    }
  }
}

Then you can create Kimi Code CLI threads in IDE's agent panel.

Zsh integration

You can use Kimi Code CLI together with Zsh, to empower your shell experience with AI agent capabilities.

Install the zsh-kimi-cli plugin via:

git clone https://github.com/MoonshotAI/zsh-kimi-cli.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/kimi-cli

Note

If you are using a plugin manager other than Oh My Zsh, you may need to refer to the plugin's README for installation instructions.

Then add kimi-cli to your Zsh plugin list in ~/.zshrc:

plugins=(... kimi-cli)

After restarting Zsh, you can switch to agent mode by pressing Ctrl-X.

MCP support

Kimi Code CLI supports MCP (Model Context Protocol) tools.

kimi mcp sub-command group

You can manage MCP servers with kimi mcp sub-command group. For example:

# Add streamable HTTP server:
kimi mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: ctx7sk-your-key"

# Add streamable HTTP server with OAuth authorization:
kimi mcp add --transport http --auth oauth linear https://mcp.linear.app/mcp

# Add stdio server:
kimi mcp add --transport stdio chrome-devtools -- npx chrome-devtools-mcp@latest

# List added MCP servers:
kimi mcp list

# Remove an MCP server:
kimi mcp remove chrome-devtools

# Authorize an MCP server:
kimi mcp auth linear

Ad-hoc MCP configuration

Kimi Code CLI also supports ad-hoc MCP server configuration via CLI option.

Given an MCP config file in the well-known MCP config format like the following:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "YOUR_API_KEY"
      }
    },
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Run kimi with --mcp-config-file option to connect to the specified MCP servers:

kimi --mcp-config-file /path/to/mcp.json

Web interface

Kimi Code CLI includes a built-in web UI. Start it with:

uv run kimi web

By default the server binds to 127.0.0.1:5494 and uses the current working directory as the agent directory.

To run the web interface against a specific agent directory, use --agent-dir (or -d):

uv run kimi web --agent-dir /path/to/my/project

Other useful options:

uv run kimi web --port 8080           # use a different port
uv run kimi web --network             # bind to 0.0.0.0 (LAN access)
uv run kimi web --auth-token mytoken  # require a bearer token

More

See more features in the Documentation.

Development

To work on Hero Kimi, run:

git clone <this-repo-url>
cd hero_kimi

make prepare  # prepare the development environment

Useful commands once you're set up:

uv run kimi  # run Hero Kimi from sources

make format  # format code
make check   # run linting and type checking
make test    # run tests
make help    # show all make targets

Building

Build the web UI

The terminal app embeds a small web UI (the kimi web server). Rebuild it whenever you touch anything under web/ or vis/:

make build-web   # build the web UI (vite) and sync it into the kimi-cli package
make build-vis   # same, for the vis UI

Both call scripts/build_web.py / scripts/build_vis.py under the hood — Node.js (with npm or pnpm) is required.

Build the standalone binary

To ship Hero Kimi as a single self-contained executable — Python interpreter, kimi-cli code, and the built web/vis assets all bundled in one file — use:

make build-bin

or, equivalently and with a bit more control, the convenience wrapper:

scripts/bundle.sh            # one-file binary, written to dist/kimi-<os>-<arch>
scripts/bundle.sh --onedir   # one-directory bundle (faster startup), dist/kimi-<os>-<arch>/
scripts/bundle.sh --skip-web # skip rebuilding web/vis assets (use what's already synced)

The script auto-detects the host platform and architecture and stamps it into the output filename (e.g. dist/kimi-darwin-arm64, dist/kimi-linux-x86_64, dist/kimi-windows-x86_64.exe) so artifacts from different build hosts don't collide.

Note

PyInstaller binaries are platform- and architecture-specific — there is no cross-compilation. To ship for multiple platforms, run scripts/bundle.sh on each target OS/arch (CI matrix recommended). For maximum Linux portability, build inside an older distro (e.g. Ubuntu 20.04 or a manylinux image); the binary will then run on newer ones too.

make build and make build-bin both automatically rebuild the web UI so it's always embedded fresh.

Install the binary on the host

To build the standalone binary and install it directly on the host (no uv or Python required on the host after this):

make install

This will:

1. Build the self-contained binary via make build-bin
2. Remove any existing uv/Python-managed kimi installation
3. Copy the binary to ~/.local/bin/kimi

After this, kimi on the host is a plain native executable with no Python dependency.