# ⚡ kimi-boost
**Battle-tested skills · hooks · agents — one command, for Kimi Code, Claude Code and Codex CLI.**
`npx kimi-boost install` → pick a preset → done.
[](https://github.com/shidesheng0218/kimi-boost)
[](https://www.npmjs.com/package/kimi-boost)
[](/LICENSE)
[](https://github.com/shidesheng0218/kimi-boost/actions/workflows/ci.yml)
[](https://github.com/shidesheng0218/kimi-boost/actions/workflows/verify.yml)
[](#presets)
**[English](README.md) · [中文文档](docs/README.zh-CN.md)**
---
## Why
Your AI coding agent only knows what you teach it. Without guidance it writes generic, unidiomatic code, pushes straight to `main`, and runs `rm -rf` on things you liked. Hand-configuring skills, hooks and agents takes hours — so nobody ever does it.
**kimi-boost installs a complete, opinionated development workflow in seconds:**
| You get | What it does |
|---|---|
| 🧠 **Skills** | Best-practice rules your agent **auto-loads** — no prompting required |
| 🔍 **Reviewer agents** | Read-only subagents your agent delegates to before committing |
| 🛡️ **Hooks** | Cross-platform Node guards: dangerous commands, main-branch protection |
| 🔄 **One-command updates** | `kimi-boost update` keeps every preset current, even on forks |
## Demo
GIF won't load (or you're behind a slow CDN)? Same session, as plain text:
```text
$ kimi-boost install vue3
✓ [kimi] Installed preset 'vue3' into Kimi Code
/Users/you/.kimi-boost/hooks/vue3
config.toml[extra_skill_dirs], config.toml[extra_agent_dirs], config.toml[[hooks]] (+1)
Run /reload or start a new session.
$ kimi-boost doctor
✓ kimi: detected (version 0.36.1)
✓ kimi: config.toml parses
✓ kimi: hook script valid
✓ kimi: mounted dir present
All checks passed.
```
## Two ways to install
**① Official Kimi Code plugin channel — no CLI required.** The five flagship presets are mirrored to single-plugin repos and install natively:
```
/plugins install https://github.com/shidesheng0218/kimi-boost-vue3
```
Available mirrors: [vue3](https://github.com/shidesheng0218/kimi-boost-vue3) · [react](https://github.com/shidesheng0218/kimi-boost-react) · [go](https://github.com/shidesheng0218/kimi-boost-go) · [python](https://github.com/shidesheng0218/kimi-boost-python) · [usage](https://github.com/shidesheng0218/kimi-boost-usage) · **[core](https://github.com/shidesheng0218/kimi-boost-core)** (the guardrails — install them in Kimi Code with no CLI at all)
Or browse them inside the `/plugins` panel via our marketplace feed:
```bash
export KIMI_CODE_PLUGIN_MARKETPLACE_URL=https://raw.githubusercontent.com/shidesheng0218/kimi-boost/main/marketplace.json
```
**② kimi-boost CLI — all 19 presets, three harnesses.** One installer for Kimi Code, Claude Code *and* Codex CLI, with updates, doctor checks and clean uninstalls:
```bash
npx kimi-boost install
```
| | Official channel | kimi-boost CLI |
|---|---|---|
| Presets | 5 flagship (mirrored) | All 19 |
| Harnesses | Kimi Code | Kimi Code · Claude Code · Codex |
| Needs | Just Kimi Code | Node.js |
| Extras | — | update · doctor · usage stats · dry-run |
## Presets
| Preset | Stack | Reviewer agent | Hooks | Official repo |
|---|---|---|---|---|
| `vue3` | Vue 3 + TypeScript | `vue3-reviewer` | 🛡️ main-branch guard | [✅ kimi-boost-vue3](https://github.com/shidesheng0218/kimi-boost-vue3) |
| `react` | React + TypeScript | `react-reviewer` | 🛡️ main-branch guard | [✅ kimi-boost-react](https://github.com/shidesheng0218/kimi-boost-react) |
| `go` | Go | `go-reviewer` | 🛡️ main-branch guard | [✅ kimi-boost-go](https://github.com/shidesheng0218/kimi-boost-go) |
| `python` | Python | `python-reviewer` | 🛡️ dangerous-shell blocker | [✅ kimi-boost-python](https://github.com/shidesheng0218/kimi-boost-python) |
| `nextjs` | Next.js (fullstack) | `nextjs-reviewer` | 🛡️ main-branch guard | via CLI |
| `react-native` | React Native | `react-native-reviewer` | 🛡️ main-branch guard | via CLI |
| `flutter` | Flutter / Dart | `flutter-reviewer` | 🛡️ main-branch guard | via CLI |
| `uniapp` | uni-app (cross-platform) | `uniapp-reviewer` | 🛡️ main-branch guard | via CLI |
| `weapp` | WeChat Mini Program | `weapp-reviewer` | — | via CLI |
| `nestjs` | NestJS / TypeScript backend | `nestjs-reviewer` | 🛡️ main-branch guard | via CLI |
| `express` | Express (Node.js) | `express-reviewer` | 🛡️ main-branch guard | via CLI |
| `fastapi` | FastAPI (Python) | `fastapi-reviewer` | 🛡️ main-branch guard | via CLI |
| `rust` | Rust | `rust-reviewer` | 🛡️ main-branch guard | via CLI |
| `java` | Java (Spring Boot) | `java-reviewer` | 🛡️ main-branch guard | via CLI |
**Special presets:**
| Preset | What it gives you | Official repo |
|---|---|---|
| `usage` | Tracks sessions / prompts / tool calls into `~/.kimi-boost/usage.json`; daily limit hint via `KIMI_BOOST_DAILY_LIMIT`; view with `kimi-boost stats` | [✅ kimi-boost-usage](https://github.com/shidesheng0218/kimi-boost-usage) |
| `core` | **The baseline insurance every project should have** — blocks direct pushes to `main`/`master`, dangerous shell commands (`rm -rf /`, `mkfs`, `dd` to disk, `curl\|sh`), hardcoded secrets in written files, credential reads and workspace-destroying git ops. Included by default in `kimi-boost init` | [✅ kimi-boost-core](https://github.com/shidesheng0218/kimi-boost-core) |
| `mcp-tools` | Zero-config MCP servers: `fetch` (web scraping) + `time` (timezones) — written to `~/.kimi-code/mcp.json` | via CLI |
| `security` | Cross-stack guard: scans Write/Edit for hardcoded secrets, blocks dangerous `git push` (`--force`/`--delete`, allows `--force-with-lease`); plus a `security-reviewer` agent | via CLI |
| `git-workflow` | Conventional commits, branch naming & PR discipline (auto-loaded skill) + a `git-workflow-reviewer` agent; no hooks | via CLI |
> Every preset bundles a best-practice SKILL.md (auto-loaded) + a reviewer agent. New stacks are vote-driven — [issue #1](https://github.com/shidesheng0218/kimi-boost/issues/1). "via CLI" presets get their own official repo as demand grows.
Each preset is **one directory** in this repo — a valid `kimi.plugin.json` plugin AND a kimi-boost preset. Contributions welcome:
```
presets//
├── preset.json # kimi-boost metadata
├── kimi.plugin.json # Kimi Code plugin manifest (native marketplace form)
├── skills//SKILL.md
├── agents/-reviewer.md
└── hooks/.mjs # cross-platform Node, fail-open by design
```
## Commands
| Command | What it does |
|---|---|
| `kimi-boost install [preset]` | Install a preset by id — or from any GitHub repo: `install github:owner/repo` (`--dry-run` preview, `--with-hooks` force, `--project` install into current project) |
| `kimi-boost init` | Detect this project's stack and install matching presets — always includes the `core` guardrails by default (`--yes` skip prompt, `--dry-run` preview, `--project`) |
| `kimi-boost list` | Show available + installed presets |
| `kimi-boost remove ` | Uninstall cleanly |
| `kimi-boost update [--repo owner/repo]` | Pull latest versions and re-apply (works on forks; community presets update from their source repo) |
| `kimi-boost update --dry-run` | Preview what an update would change (version + file-level diff) without writing |
| `kimi-boost outdated [--project] [--json]` | Show installed presets with newer registry versions |
| `kimi-boost doctor [--fix]` | Diagnose config, hooks, mounted dirs, manifest consistency, duplicate hooks |
| `kimi-boost guard` | Guardrail status + block history; `--log`, `--disable/--enable`, `--warn/--block`, `--explain `, `--add-pattern `, `--ci [--staged]`, `--install-git-hook` — tune and run guards without reinstalling |
| `kimi-boost marketplace [--source-mode repo\|zip]` | Generate a Kimi Code custom marketplace JSON |
| `kimi-boost stats [-d N] [--share]` | Usage report with bar chart, streak & top tools; `--share` exports an SVG card (alias: `usage`) |
| `kimi-boost badge [preset]` | Print a README badge (markdown) showing this project uses kimi-boost |
| `kimi-boost export [file]` | Export your preset setup to a shareable file (`--embed-content` for offline restore, `--include-usage`) |
| `kimi-boost import ` | Restore a previously exported setup on another machine (`--yes`, `--dry-run`) |
| `kimi-boost validate ` | Validate a preset directory (for preset authors) |
| `kimi-boost dev ` | Validate + preview-install a local preset (dry-run) |
| `kimi-boost package ` | Validate + pack a preset into `-.zip` |
| `kimi-boost status` | Detect installed CLIs & platform |
| `kimi-boost bootstrap [--makefile]` | Generate a `setup.sh` (or Makefile `setup` target) for team onboarding |
| `kimi-boost update --check` | Check for preset updates without installing; notifies + exits non-zero if found |
| `kimi-boost update --watch [--interval h] [--uninstall]` | Register/remove a periodic background update check |
### Project-level installs (team sharing)
`kimi-boost install --project` writes the preset into the current project instead of your user config:
- skills → `.agents/skills/` (Kimi Code + the cross-tool `.agents/` convention) and `.claude/skills/`
- agents → `.agents/agents/` and `.claude/agents/`
- hooks → `.claude/settings.json` (Claude Code only — Kimi Code has no project-level hook mechanism; Codex is skipped)
Everything lands inside the project root (nearest `.git` ancestor), so you can **commit the preset and share it with your team** — every clone gets the same AI behavior. Remove with `kimi-boost remove --project`.
### Community presets — install from any GitHub repo
Anyone can publish a preset as a plain GitHub repo (a `preset.json` at the repo root, plus `skills/`, `agents/`, `hooks/`):
```bash
kimi-boost install github:owner/repo # or the full https://github.com/owner/repo URL
kimi-boost install github:owner/repo@v1.2.0 # pin a branch or tag
```
kimi-boost shows you exactly what the preset will register — especially its hooks, which execute when the agent runs — and asks for confirmation before installing (`--yes` to skip in scripts, `--dry-run` to preview). Community presets are tracked in `update` / `outdated` against their source repo, so they stay current. **Only install presets from authors you trust** — hooks run shell commands with your agent's permissions.
### Shareable stats — your AI-coding wrapped
The `usage` preset quietly counts your sessions / prompts / tool calls. `stats` turns it into a report you'll want to screenshot:
```bash
$ kimi-boost stats -d 7
📊 kimi-boost stats · last 7 days
128 prompts · 12 sessions · 856 tool calls · 5 active days · streak 3 🔥
09-01 ████████████ 24
09-02 ██████ 12
...
$ kimi-boost stats --share # → kimi-boost-stats.svg
```
`--share` exports a self-contained SVG card (no server, no upload — your data never leaves your machine). Post it, or embed it in your README next to a `kimi-boost badge`.
### Guardrails you can actually see
Most "agent safety" is invisible — a hook silently blocks something and you never know your agent almost ran `rm -rf /`. kimi-boost makes the seatbelt visible:
- Every blocked action is logged to `~/.kimi-boost/guard-log.jsonl` (secret previews are redacted — never the secret itself).
- `kimi-boost guard` shows every guard's status and how many times it fired; `guard --log` lists recent blocks with timestamps.
- `kimi-boost stats` reports `🛡️ N blocks` — your share card can now say *"it stopped my agent N times this week."*
- Tune live without reinstalling: `guard --disable/--enable ` turns a guard off/on, `guard --warn/--block ` softens a guard to warn-only (still logged, no longer blocking), and `guard --explain ` tells you what it blocks, how to bypass it and what disabling it risks.
- `guard --add-pattern ` teaches `block-dangerous` your own patterns.
**The `core` preset ships 8 guards:** `protect-main` (direct pushes to trunk), `block-dangerous` (dangerous shell), `git-destructive` (`reset --hard`, `clean -f`, `checkout -- .`), `secret-scan` (hardcoded secrets on write), `protect-credentials` (reading `~/.ssh`, `~/.aws/credentials`, `*.pem`… into context), `protect-paths` (hand-editing lockfiles, writes into `node_modules/`/`.git/`), `protect-guards` (the agent disabling guardrails or rewriting their config), and `secret-scan-post` (a PostToolUse re-scan that catches secrets written via shell redirection).
**Same guards, in CI:** `kimi-boost guard --ci [--staged]` scans changed files for secrets and exits non-zero on findings; `guard --install-git-hook` wires that into a pre-commit hook so agent-authored code passes the same checks locally.
#### What the guardrails don't promise
Read this before trusting them with anything important:
- **Pattern matching is not a security boundary — sandboxing is.** These hooks raise the cost of accidents; they do not stop a determined adversary (or a prompt-injected agent) that obfuscates commands (`base64 | sh`), hides writes inside scripts, or assembles a secret at runtime. For real isolation, run your agent in a sandbox (e.g. Claude Code's `/sandbox`) or a container.
- **Everything fails open by design.** If a hook errors, a runtime is missing, or the matcher doesn't cover a tool, the action is allowed. Availability beats strictness — that's the deliberate trade-off.
- **`secret-scan-post` informs, it cannot undo.** The file is already written when it fires; it tells the agent to fix it.
- **Guards are per-tool.** A guard registered for `Write`/`Edit` does not see a harness whose file tools have other names.
- Use them as one layer: host-side secret scanning (GitHub push protection), review, and a sandbox are the others.
### Export & import — clone your AI setup to any machine
### Export & import — clone your AI setup to any machine
`export` captures your whole kimi-boost setup — installed presets with versions, community preset sources, and the background update check — into one shareable file:
```bash
kimi-boost export # → kimi-boost-export.json
kimi-boost export --embed-content # → .tar.gz with preset contents (exact, offline)
kimi-boost export --include-usage # also carry your usage history
# on the new machine:
kimi-boost import kimi-boost-export.json # shows the plan, asks once, restores everything
kimi-boost import kimi-boost-export.json --dry-run
```
Official presets reinstall from the registry, community presets reinstall from their exact `repo@ref` source, and the update watch is re-registered. Commit the file to your dotfiles repo, or drop it in your team's chat — one file, same AI workflow everywhere.
### Authoring presets
Building a community preset? Three helpers cover the loop:
```bash
kimi-boost validate ./my-preset # schema, hooks, skills, plugin manifest
kimi-boost dev ./my-preset # validate + preview the install (dry-run)
kimi-boost package ./my-preset # validate + pack my-preset-1.0.0.zip
```
Push the directory to a GitHub repo (with `preset.json` at its root) and anyone can install it with `kimi-boost install github:you/my-preset`.
### `doctor` — know your setup is healthy
```bash
$ kimi-boost doctor
✓ kimi: detected
version 0.36.1
✓ kimi: config.toml parses
✓ kimi: hook script valid
/Users/you/.kimi-boost/hooks/vue3/protect-main.mjs
✓ kimi: mounted dir present
⚠ codex: CLI not detected
Install codex or ignore if you don't use it.
1 warning(s), no errors
```
`kimi-boost doctor --fix` restores missing mounted dirs and hook scripts automatically.
## How it works
```mermaid
flowchart TD
REG["presets/ registry (19 presets)
skills · agents · hooks · mcp"]
subgraph CI["Monorepo CI"]
VERIFY["verify.yml
live-installs every preset
into a real Kimi Code CLI"]
SPLIT["split-presets.yml
git subtree mirror"]
end
REG --> CI
SPLIT -->|"auto-mirror"| M1["kimi-boost-vue3"]
SPLIT -->|"auto-mirror"| M2["react · go · python · usage"]
M1 & M2 -->|"/plugins install"| KP["Kimi Code /plugins"]
REG -->|"builds (repo sources)"| MKT["marketplace.json"]
MKT -->|"KIMI_CODE_PLUGIN_MARKETPLACE_URL"| KP
KB["kimi-boost CLI
install · remove · doctor · update"]
REG --> KB
KB -->|"text-level edit"| KCF["~/.kimi-code/config.toml"]
KB -->|"manifest-driven"| CCS["~/.claude/settings.json"]
KB -->|"manifest-driven"| CXC["~/.codex/config.toml"]
classDef cli fill:#7c3aed,color:#fff,font-weight:bold;
classDef tool fill:#1e293b,color:#e2e8f0;
classDef out fill:#064e3b,color:#a7f3d0;
class KB,REG cli;
class M1,M2,MKT tool;
class KCF,CCS,CXC,KP out;
```
- **Single source of truth** — presets live in this monorepo; the five flagship mirrors are read-only CI artifacts, re-synced on every push.
- **Kimi Code** — the CLI edits `~/.kimi-code/config.toml` at **text level** (a managed `# >>> kimi-boost managed >>>` block plus in-place array merge). Your comments and formatting survive untouched.
- **Claude Code & Codex** — manifest-driven install into `~/.claude` / `~/.codex`; agent files use the native frontmatter format (cross-compatible, per Kimi docs).
- **Hooks are plain Node `.mjs`** — the same pattern Kimi Code's own docs use, identical behavior on macOS / Windows / Linux.
- **Compatibility is tested, not assumed** — CI live-installs all 19 presets into a real Kimi Code CLI on every PR, and weekly against upstream drift.
## Safety by default
- 🔒 **Never touches your config beyond its own managed section** — comments, ordering, formatting all preserved
- 🗄️ Backed up to `.kboost.bak` before every change
- 🚧 Managed-roots whitelist — refuses to delete anything outside `~/.kimi-boost`, `~/.kimi-code`, `~/.claude`, `~/.codex`
- 🛡️ Dual-channel guard — already installed via Kimi `/plugins`? No duplicate hooks.
- ♻️ **Content-aware hook dedup** — presets bundling the same guard script (e.g. `protect-main.mjs`) share a single config entry; uninstalling one preset retargets the entry to the next owner instead of breaking the rest. `doctor` flags redundant or diverging hook copies.
- ⚡ Fail-open hooks — a crashing hook never blocks your work (exit `0` allow · exit `2` block)
## Roadmap
- [x] MCP server presets
- [x] Token/cost usage guard hooks
- [x] Official-channel distribution (single-plugin repo mirrors)
- [x] Per-project (`.kimi-boost/`) presets
- [ ] More stack presets (vote in [issue #1](https://github.com/shidesheng0218/kimi-boost/issues/1))
- [ ] Mirror every preset to its own official repo
## Contributing
Preset catalog is PR-driven: add a directory under `presets/`, CI validates schema, hook events and file existence — then live-installs your preset into a real Kimi Code CLI. See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
MIT