217 스타 · 무서운 속도로 상승 중. Moonshot AI(중국 Kimi 팀)가 만든 터미널 AI 코딩 에이전트. Claude Code · OpenAI Codex CLI · opencode와 정확히 같은 카테고리지만, 출발선부터 다른 설계를 들고 나왔다 — 단일 바이너리 배포(Node.js 불필요), 밀리초 단위 TUI 부팅, 비디오 입력, 대화형 MCP 설정, 서브에이전트, lifecycle hooks. TypeScript 모노레포로 "에이전트 SDK"부터 짠 다음 그 위에 CLI를 올린, 프로덕션 grade 구조.
중국 Moonshot AI의 LLM 브랜드. 2024~2025년 OSS LLM 판도를 흔든 K2 모델의 회사.
Kimi는 Moonshot AI가 만드는 LLM 시리즈 이름이다. 중국 베이징 기반 스타트업으로 2023년 창업, ChatGPT 대안 챗봇 Kimi.ai로 중국 내에서 인지도를 쌓았다. 2025년에 공개한 Kimi K2는 약 1T 파라미터급 MoE 모델로 코딩·에이전트 벤치마크에서 GPT-4·Claude와 어깨를 나란히 하며 OSS LLM 판도를 한 차례 흔들었다.
그 회사가 이번에 들고 나온 게 Kimi Code CLI다. 자기네 모델을 가장 잘 활용할 수 있는 "에이전트 하네스"를 직접 만든 셈 — Anthropic이 Claude Code를 만든 것, OpenAI가 Codex CLI를 만든 것과 똑같은 흐름이다.
LLM 자체는 엔진이다. 엄청 잘 도는 엔진이지만 그 자체로는 차가 아니다. 에이전트 하네스는 그 엔진에 핸들·바퀴·계기판·안전벨트를 달아 "차"로 만드는 작업이다. Kimi K2가 엔진이라면, Kimi Code CLI는 그 위에 얹은 도요타 캠리에 해당한다.
Kimi Code CLI = 터미널에서 도는 Kimi 모델용 AI 코딩 에이전트.
코드 읽기·수정, 셸 명령 실행, 파일 탐색, 웹 페이지 가져오기, 다음 행동 자율 결정 — 이걸 한 묶음으로 묶은 대화형 TUI(Text UI) 에이전트다. 기본 엔진은 Moonshot의 Kimi지만 config.toml에 키만 박으면 Anthropic Claude, OpenAI, Google 모델로도 돌릴 수 있다.
"또 다른 Claude Code 클론"이라기엔, 차별점이 꽤 구체적이다.
2025~2026년 들어 터미널 코딩 에이전트는 거대한 카테고리가 됐다. Claude Code, OpenAI Codex CLI, Cursor CLI, opencode, Gemini CLI… 거의 매주 하나씩 나온다. 이 와중에 Kimi Code가 트렌딩에 오른 이유는 네 가지 차별점 때문이다.
대부분의 동급 CLI는 npm install -g가 강제된다. 즉 Node.js를 먼저 깔아야 한다. Kimi Code는 완성된 실행 파일을 한 번에 떨군다 — curl ... | bash 한 줄이면 끝. Node 버전 호환·PATH 충돌·글로벌 모듈 문제가 없다. npm 설치 옵션도 따로 제공한다.
node --experimental-sea-config(Single Executable Application)로 가능해진 기법이며, Bun·Deno도 같은 능력을 제공한다.대화형 에이전트는 반복 호출이 잦다. 매번 "kimi" 명령 하나 치고 1~2초씩 기다리면 짜증이 쌓인다. Kimi Code는 의도적으로 TUI 부팅을 ms 단위로 끌어내렸다 — pi-tui라는 가벼운 TUI 라이브러리를 베이스로 깔고, 그 위에 자체 컴포넌트를 얹었다.
이게 다른 CLI들이 흉내 못 내는 차별 포인트다. 스크린 녹화·데모 클립을 채팅창에 그대로 드래그하면 에이전트가 영상을 보고 "이 버튼을 누르면 이런 에러가 뜬다"는 식의 상황을 이해한다. 글로 설명하기 어려운 UI 버그·재현 시나리오를 영상 하나로 떠넘길 수 있다.
이 세 가지는 묶어서 봐야 한다 — 모두 "에이전트를 진지하게 운영하기 위한 인프라"다.
| 기능 | 역할 | 같은 기능 비교 |
|---|---|---|
/mcp-config | JSON 직접 편집 없이 대화로 MCP 서버 추가·인증 | Claude Code는 JSON 수동 편집 |
Subagents (coder/explore/plan) | 격리된 컨텍스트에서 병렬 위임 작업 | Claude Code의 Task tool과 유사 |
| Lifecycle hooks | 위험 동작 차단·감사 로그·데스크탑 알림 | Claude Code의 hooks와 같은 컨셉 |
Anthropic 모델만 쓰던 사람도 config.toml에 키 하나 더 박으면 Kimi/Anthropic/OpenAI/Google을 자유롭게 갈아끼울 수 있는 중립 하네스로 쓸 수 있다. 그래서 트렌딩에 오른 거다.
TypeScript 모노레포 + pnpm workspace. 9개 패키지 + 2개 앱으로 깔끔하게 나눠진다.
| 역할 | 도구 | 버전 |
|---|---|---|
| 런타임 | Node.js | >=24.15.0 (engine-strict) |
| 패키지 매니저 | pnpm | 10.33.0 (workspace) |
| 언어 | TypeScript | 6.0.2 (정식 릴리스 직후 트랙) |
| 린터 | oxlint (Rust) | 1.59.0 + tsgolint |
| 번들러 | tsdown | 0.22.0 (Rolldown 기반) |
| 테스트 | Vitest | 4.1.4 |
| 릴리스 | Changesets | 2.30.0 |
| 훅 | simple-git-hooks + lint-staged | — |
| 재현 환경 | Nix flake | flake.nix |
type-aware 모드는 TypeScript 컴파일러 정보를 활용한 더 엄격한 검사다.| 패키지 | 책임 |
|---|---|
agent-core | 핵심 엔진. Agent, Session, profile, skills, tools, plan, permission, background, records — 에이전트의 "뇌"에 해당하는 모든 컴포넌트 |
node-sdk | 외부 개발자용 퍼블릭 TypeScript SDK + harness. apps는 이걸 통해서만 agent-core를 호출한다 |
kosong | LLM/Provider 추상화. Kimi·Anthropic·OpenAI·Google을 같은 인터페이스로 묶음 ("코송"은 인도네시아어로 "비어 있다" — provider-agnostic의 비유) |
kaos | 실행 환경 추상화. 파일 시스템·프로세스·셸을 안전한 API로 감쌈 (chaos를 길들였다는 뉘앙스) |
oauth | Kimi OAuth device-code flow + managed auth 유틸 |
telemetry | 익명 사용 통계 수집(클라이언트 사이드) |
migration-legacy | 이전 kimi-cli 사용자 마이그레이션 호환 레이어 |
acp-adapter | ACP(Agent Client Protocol) 어댑터 — Zed·JetBrains 등 IDE 에디터 통합용 |
protocol | 에이전트 내부 메시지·이벤트 프로토콜 타입 정의 |
| 앱 | 역할 |
|---|---|
apps/kimi-code | 실제 사용자가 쓰는 TUI/CLI. kimi 명령의 본체. agent-core를 직접 import하면 안 된다 — node-sdk만 통해야 한다 (계약 규칙) |
apps/vis/server | 세션 디버깅용 백엔드 (Node.js 서버) |
apps/vis/web | 세션 디버깅용 프론트엔드 — 에이전트의 turn-by-turn 실행을 웹 UI로 리플레이 |
이 구조는 레스토랑의 주방-홀 분리와 같다. agent-core는 주방(뜨거운 곳), node-sdk는 서빙 카운터(외부와의 유일한 접점), apps/kimi-code는 손님이 앉는 홀. 손님(앱)이 주방(엔진)에 직접 들어가면 안 된다는 규칙을 AGENTS.md에 못 박아 둔다.
SDK가 안 보이는 벽이고, kosong/kaos가 양쪽 끝에 있는 변환기다.
사용자 터미널 (zsh / bash / pwsh)
│
▼
┌───────────────────────────────────────────────┐
│ apps/kimi-code ─ TUI (pi-tui 기반) │
│ · 입력 파싱 · 슬래시 명령 · 권한 다이얼로그 │
└────────────────────┬──────────────────────────┘
│ ★ 여기까지만 SDK 사용
▼
┌───────────────────────────────────────────────┐
│ packages/node-sdk ─ 공개 표면 │
│ · Agent 인스턴스화 · 세션 관리 · 타입 │
└────────────────────┬──────────────────────────┘
│
▼
┌───────────────────────────────────────────────┐
│ packages/agent-core ─ 엔진 본체 │
│ ┌─────────┐ ┌─────────┐ ┌──────────────┐ │
│ │ Agent │ │ Session │ │ Plan/Skills │ │
│ └────┬────┘ └────┬────┘ └──────┬───────┘ │
│ └──────┬────┴─────────────┘ │
│ ▼ │
│ permission · tools · background · records │
└──────┬───────────────────────────┬────────────┘
│ │
▼ ▼
┌───────────────────────┐ ┌─────────────────────────┐
│ packages/kosong │ │ packages/kaos │
│ (LLM provider 추상화) │ │ (실행 환경 추상화) │
│ ─ Kimi ─ Anthropic │ │ ─ FS ─ shell ─ proc │
│ ─ OpenAI ─ Google │ │ ─ MCP 클라이언트 │
└──────────┬────────────┘ └────────────┬────────────┘
▼ ▼
외부 LLM API 유저의 디스크/셸
(HTTPS 스트림) (검증된 권한 안에서)
루트 AGENTS.md가 못 박는 규칙: "apps/kimi-code는 agent-core를 직접 의존하면 안 된다. 반드시 node-sdk를 통해서만 호출하라." 이 한 줄이 SDK의 정체성을 만든다 — 외부 사용자가 쓰는 SDK와 자기네 앱이 쓰는 SDK가 같다는 뜻이다 (eating their own dog food).
"같은 호출 시그니처로 Kimi, Anthropic, OpenAI, Google을 갈아끼울 수 있다." 이걸 어떻게 만드냐가 관건이다 — 각 모델의 도구 호출(tool calling) 포맷이 다르고, 프롬프트 캐시 키도 다르고, 스트리밍 SSE 형식도 다르다. kosong은 이 차이를 모두 내부에서 정규화해서 agent-core에는 통일된 인터페이스만 노출한다.
AGENTS.md에 명시: "Agent 클래스는 Session 없이도 단독으로 쓸 수 있어야 한다." 즉 new Agent({...})가 절대로 Session 생성을 강제하지 않는다. sessionId는 request-config 힌트로만 전달되며 (예: provider의 prompt_cache_key에 매핑) Agent 인스턴스가 sessionId를 들고 있지 않는다.
이건 "택시 기사는 자기 손님 명단을 기억하지 않는다"는 규칙이다. 손님(Session)이 바뀌어도 기사(Agent)는 그냥 운전만 한다. 같은 기사를 여러 손님이 돌려쓸 수 있고, 손님 관리는 따로 하는 부서(Session)가 책임진다. 이 분리 덕분에 Agent를 서버 사이드 SDK에서도 재사용할 수 있다.
"파일 읽기·검색·웹 fetch처럼 읽기 전용 도구는 자동 실행. 파일 수정·셸 명령은 매번 사용자에게 묻기." 이 분리가 permission 모듈에 들어 있다. lifecycle hooks와 결합해 "특정 디렉토리 밖 쓰기 금지" 같은 정책을 외부 명령으로 강제할 수 있다.
레포 루트에 뭐가 있는지부터, 각 디렉토리가 왜 거기 있는지까지.
kimi-code/ ├── apps/ │ ├── kimi-code/ ← 실제 `kimi` 명령 (TUI 본체) │ └── vis/ │ ├── server/ ← 세션 리플레이 서버 │ └── web/ ← 세션 리플레이 웹 UI │ ├── packages/ │ ├── agent-core/ ← 엔진 (Agent, Session, plan, skills...) │ ├── node-sdk/ ← 외부 공개 SDK (Agent 진입점) │ ├── kosong/ ← LLM provider 어댑터 │ ├── kaos/ ← 파일/셸/프로세스 안전 추상화 │ ├── oauth/ ← Kimi OAuth + 토큰 관리 │ ├── telemetry/ ← 클라이언트 사용 통계 │ └── migration-legacy/ ← 이전 kimi-cli 호환층 │ ├── plugins/ ← 마켓플레이스 플러그인 정의 (marketplace.json + official/) │ ├── .agents/ │ └── skills/ ← 에이전트가 따라야 할 자체 스킬 │ └── gen-changesets/SKILL.md │ ├── .changeset/ ← 릴리스 버전 노트 단위 (changesets) ├── .github/ ← CI / PR 템플릿 / workflow ├── build/ ← 단일 바이너리 빌드 스크립트 ├── docs/ ← VitePress 기반 사용자 문서 (영/중) │ ├── AGENTS.md ← 에이전트 작업 규칙 (이게 본 레포의 헌법) ├── CONTRIBUTING.md ├── SECURITY.md ├── README.md / README.zh-CN.md │ ├── package.json ← 모노레포 루트, scripts와 devDeps만 ├── pnpm-workspace.yaml ← workspace 정의 + catalog ├── pnpm-lock.yaml ← 잠금 (재현성 보장) ├── tsconfig.json ← 루트 TS 설정 (각 패키지가 extends) ├── vitest.config.ts ← 모노레포 전역 테스트 설정 ├── .oxlintrc.json ← oxlint 룰 ├── .oxfmtrc.json ← oxlint 포맷터 ├── .nvmrc ← `24.15.0` (Node 자동 스위처용) ├── .npmrc ← engine-strict=true ├── .editorconfig ├── flake.nix / flake.lock ← Nix 재현 환경 └── Makefile ← 단축 명령 (build, install 등)
.agents/skills/ — 자기네 에이전트(Kimi Code)가 따라야 할 스킬 SKILL.md가 들어있다. gen-changesets 스킬은 PR 만들 때 자동으로 changeset을 만들도록 강제한다. "에이전트가 자기 자신의 레포에 PR을 올릴 때 따를 규칙"이라는 메타한 개념이다.
AGENTS.md — 단순 README가 아니라 에이전트 헌법. "코드를 진실의 원천으로 봐라, 일반 마크다운을 일부러 읽지 마라, PR 메시지에 'AI agent'라는 표현 박지 마라, 단일 매개변수는 options 객체로 만들지 마라" 같은 매우 구체적인 규칙들이 있다.
.changeset/ — Changesets는 라이브러리 버전을 PR 단위로 관리하는 도구. PR을 머지하기 전에 "이 변경이 major/minor/patch 중 뭐냐"를 한 줄로 기록하는 마크다운을 남긴다. CI가 이걸 모아 자동으로 CHANGELOG.md를 만들고 npm publish까지 한다.
이 레포에서 진짜로 배울 만한 것들. 단순히 따라 치는 게 아니라 설계를 흡수하는 관점에서.
"라이브러리 + CLI + 웹앱"이 한 레포에 사이좋게 사는 표준 패턴. pnpm-workspace.yaml의 catalog: 필드로 여러 패키지가 같은 의존성 버전을 강제하는 트릭(zod: ^4.3.6)을 그대로 흉내 낼 수 있다.
당신의 사이드 프로젝트를 apps/web(Next.js) + packages/api-client(zod 스키마 공유) + packages/utils 세 패키지로 쪼개 보라. 의존 방향은 단방향(apps → packages)으로 강제.
웹 프론트엔드 사고방식(컴포넌트 트리)을 터미널에 적용한 게 modern TUI다. pi-tui는 React-like API로 터미널 UI를 짤 수 있게 해 준다. ink(React-for-CLI)와 같은 카테고리.
3-pane TUI를 직접 만들어 보라 — 왼쪽 파일 트리, 가운데 코드 뷰어, 오른쪽 상태 패널. ink 또는 pi-tui를 써서.
여러 모델을 같은 인터페이스로 쓰려면 도구 호출 포맷·스트리밍 SSE·이미지 입력·system prompt 위치 등을 정규화해야 한다. 이건 OpenAI의 OpenRouter, Vercel AI SDK가 푸는 문제와 같은 도메인이다.
TypeScript 인터페이스 LLMProvider를 정의하고 OpenAI·Anthropic 두 어댑터를 만들어 같은 함수 시그니처로 호출되게 해 보라. 도구 호출(tools[])의 응답 차이를 어떻게 정규화할지가 핵심.
Node.js 22+의 Single Executable Application 기능, 또는 Bun의 bun build --compile로 Node 런타임 자체를 묶어 실행 파일을 만든다. Kimi Code는 build/ 디렉토리에 OS별 패키징 스크립트를 둔다.
한 PR에 .changeset/*.md 한 장을 같이 넣으면, CI가 모아서 자동으로 버전을 올리고 CHANGELOG를 쓰고 npm publish까지 한다. Turborepo·Nx 진영의 표준 패턴.
CLI에서 브라우저 없이 인증하는 방식. CLI가 짧은 코드를 보여 주면 사용자가 다른 디바이스에서 URL을 열고 그 코드를 입력해 승인한다. GitHub CLI·Azure CLI가 쓰는 방식과 동일.
사실상 사용자 측엔 부담이 거의 없다. 무거운 추론은 모두 클라우드에서 돈다.
| 구분 | 요구사항 |
|---|---|
| 운영체제 | macOS / Linux / Windows (PowerShell) |
| 런타임 (단일 바이너리 사용 시) | 아무것도 필요 없음 |
| 런타임 (npm 설치 시) | Node.js >= 24.15.0 |
| 개발 시 | Node.js 24.15+, pnpm 10.33.0 |
| 인증 | Kimi OAuth 또는 Moonshot API key (또는 Anthropic/OpenAI/Google API key) |
| 네트워크 | LLM API로 나가는 HTTPS — 모델 호출 때마다 토큰 단위 과금 |
| 로컬 저장소 | ~/.kimi-code/에 설정·세션·로그·업데이트 캐시 저장. KIMI_CODE_HOME 환경변수로 이전 가능 |
Kimi Code 자체는 "모델"이 아니라 "하네스"다. 모델 호출은 Moonshot 클라우드 또는 다른 LLM Provider에 HTTPS로 나간다. 오프라인에서 안 돈다. 진짜 로컬 LLM이 필요하면 ollama + 호환 provider를 직접 붙이거나, 처음부터 다른 도구(예: llm CLI + ollama)를 골라야 한다.
초급 → 상급으로 갈수록 "쓰기"에서 "확장하기"로 넘어간다.
install.sh로 설치, kimi 진입, /login으로 OAuth 인증, 그리고 다음 질문 한 번 던지기:
도구 호출 결과(파일 트리)와 함께 답하는지 확인. 이게 안 되면 권한 문제다.
~/.kimi-code/config.toml을 직접 열어 Anthropic Claude를 기본 provider로 설정. ANTHROPIC_API_KEY 환경변수 + provider = "anthropic", model = "claude-...". 같은 질문에 답이 어떻게 달라지는지 비교.
/mcp-config로 공개 MCP 서버(예: filesystem, fetch)를 추가한 다음, "내 ~/Documents 디렉토리에서 'project'라는 단어가 들어간 파일 전부 찾아줘" 같은 작업을 시켜 보라. JSON 편집 없이 대화만으로 인증·설정이 되는지 체험.
예: 셸 명령 실행 직전에 rm -rf /·git push --force·curl ... | sh 같은 패턴이 보이면 차단하는 훅을 셸 스크립트로 짜서 연결. 에이전트가 자기 손을 잘못 휘둘러도 시스템이 깨지지 않게 만드는 안전망.
Kimi Code의 apps/ + packages/ + AGENTS.md + .changeset/ 패턴을 그대로 자기 사이드 프로젝트에 도입. pnpm workspace, oxlint, changesets, simple-git-hooks를 세팅하고 PR 워크플로를 굴려 본다. 회사에서 Turborepo 도입 제안할 때 좋은 reference가 된다.
"Kimi Code를 쓰기"가 아니라 "Kimi Code처럼 짜는 능력"을 키우는 코스.
| 주차 | 주제 | 해야 할 것 |
|---|---|---|
| 1주차 모노레포 토대 |
pnpm workspace + TypeScript 6 + tsdown | 빈 모노레포 생성 → packages/utils, packages/api-client, apps/web 3개로 분리 → catalog로 zod 버전 통일 |
| 2주차 에이전트 엔진 |
LLM 호출 + tool calling + 단순 plan loop | OpenAI Function calling으로 "파일 읽기"·"파일 쓰기" 도구를 만든 작은 에이전트. while loop로 도구 호출이 끝날 때까지 반복 |
| 3주차 TUI + 권한 |
pi-tui 또는 ink + permission 모듈 | 채팅창 + 도구 실행 로그 패널 + 위험 명령 권한 다이얼로그를 가진 작은 TUI 구현 |
| 4주차 배포와 거버넌스 |
단일 바이너리 + changesets + CI | Node SEA 또는 bun build --compile로 실행 파일 생성. changesets 도입 후 자동 npm publish CI 구성 |
이 레포·문서를 읽다가 막히는 단어가 있으면 여기로 돌아오라.
explore(탐색)·plan(계획)·coder(실제 코드 작성)처럼 역할별로 분리해, 메인 대화의 토큰을 아낀다.node --experimental-sea-config로 만든다.--type-aware는 TS 컴파일러 정보까지 활용.flake.nix가 있으면 nix develop 한 줄로 모든 의존성(Node, pnpm 등)이 정확한 버전으로 설치된다.공식 출처와, 같이 보면 좋은 친구 레포들.
code.kimi.com/kimi-code/install.sh@moonshot-ai/kimi-codeanthropics/claude-code, anomalyco/opencode, openai/codex — Kimi Code와 같은 카테고리earendil-works/pi (pi-tui의 본가, pi-deep-dive.html), vadimdemedes/ink (ink-deep-dive.html)humanlayer/12-factor-agents (12-factor-agents-deep-dive.html)BigPizzaV3/CodexPlusPlus (CodexPlusPlus-deep-dive.html)curl ... | bash로 깔고 5분만 써 보라. 같은 자리에서 Claude Code와 체감 차이를 느낄 수 있다.config.toml을 직접 열어 provider를 갈아끼우고, 같은 작업을 두 모델로 돌려 비교하라.