diff --git a/README.md b/README.md
index dbdfaacd..8abf7373 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
[](https://opensource.org/licenses/Apache-2.0)
[](https://agents.md)
-[中文文档](README.zh-CN.md) | [Contributing](CONTRIBUTING.md) | [Documentation](docs/)
+[中文文档](README.zh-CN.md) | [Contributing](CONTRIBUTING.md) | [Documentation](docs/README.md)
@@ -18,32 +18,46 @@
## 📢 Update Log
-**2025-08-29**: We've added Windows support! All Windows users can now run Kode using Git Bash, Unix subsystems, or WSL (Windows Subsystem for Linux) on their computers.
-
-**2025-12-30**: Windows now works out of the box with native cmd.exe support. Git Bash and WSL are optional but recommended for the best experience.
+**2025-12-22**: Native-first distribution (Windows OOTB). Kode prefers a cached native binary and falls back to the Node.js runtime when needed. See `docs/binary-distribution.md`.
## 🤝 AGENTS.md Standard Support
-**Kode proudly supports the [AGENTS.md standard protocol](https://agents.md) initiated by OpenAI** - a simple, open format for guiding programming agents that's used by 20k+ open source projects.
+Kode supports the [AGENTS.md standard](https://agents.md): a simple, open format for guiding coding agents, used by 60k+ open-source projects.
### Full Compatibility with Multiple Standards
- ✅ **AGENTS.md** - Native support for the OpenAI-initiated standard format
-- ✅ **CLAUDE.md** - Full backward compatibility with Claude Code `.claude` configurations
+- ✅ **Legacy `.claude` compatibility** - Reads `.claude` directories and `CLAUDE.md` when present (see `docs/compatibility.md`)
- ✅ **Subagent System** - Advanced agent delegation and task orchestration
- ✅ **Cross-platform** - Works with 20+ AI models and providers
Use `# Your documentation request` to generate and maintain your AGENTS.md file automatically, while preserving compatibility with existing `.claude` workflows.
+### Instruction Discovery (Codex-compatible)
+
+- Kode reads project instructions by walking from the Git repo root → current working directory.
+- In each directory, it prefers `AGENTS.override.md` over `AGENTS.md` (at most one file per directory).
+- Discovered files are concatenated root → leaf (combined size capped at 32 KiB by default; override with `KODE_PROJECT_DOC_MAX_BYTES`).
+- If `CLAUDE.md` exists in the current directory, Kode also reads it as a legacy instruction file.
+
## Overview
Kode is a powerful AI assistant that lives in your terminal. It can understand your codebase, edit files, run commands, and handle entire workflows for you.
-> **⚠️ Security Notice**: Kode runs in YOLO mode by default (equivalent to Claude Code's `--dangerously-skip-permissions` flag), bypassing all permission checks for maximum productivity. YOLO mode is recommended only for trusted, secure environments when working on non-critical projects. If you're working with important files or using models of questionable capability, we strongly recommend using `kode --safe` to enable permission checks and manual approval for all operations.
+> **⚠️ Security Notice**: Kode runs in YOLO mode by default (equivalent to the `--dangerously-skip-permissions` flag), bypassing all permission checks for maximum productivity. YOLO mode is recommended only for trusted, secure environments when working on non-critical projects. If you're working with important files or using models of questionable capability, we strongly recommend using `kode --safe` to enable permission checks and manual approval for all operations.
>
> **📊 Model Performance**: For optimal performance, we recommend using newer, more capable models designed for autonomous task completion. Avoid older Q&A-focused models like GPT-4o or Gemini 2.5 Pro, which are optimized for answering questions rather than sustained independent task execution. Choose models specifically trained for agentic workflows and extended reasoning capabilities.
+## Network & Privacy
+
+- Kode does not send product telemetry/analytics by default.
+- Network requests happen only when you explicitly use networked features:
+ - Model provider requests (Anthropic/OpenAI-compatible endpoints you configure)
+ - Web tools (`WebFetch`, `WebSearch`)
+ - Plugin marketplace downloads (GitHub/URL sources) and OAuth flows (when used)
+ - Optional update checks (opt-in via `autoUpdaterStatus: enabled`)
+
## Features
@@ -59,8 +73,8 @@ Kode is a powerful AI assistant that lives in your terminal. It can understand y
- 🛠️ **Workflow Automation** - Handle complex development tasks with simple prompts
### Authoring Comfort
-- `Ctrl+G` opens your message in your preferred editor (respects `$EDITOR`/`$VISUAL`; falls back to code/nano/vim/notepad) and returns the text to the prompt when you close it.
-- `Shift+Enter` inserts a newline inside the prompt without sending; plain Enter submits. `Ctrl+M` switches the active model.
+- `Option+G` (Alt+G) opens your message in your preferred editor (respects `$EDITOR`/`$VISUAL`; falls back to code/nano/vim/notepad) and returns the text to the prompt when you close it.
+- `Option+Enter` inserts a newline inside the prompt without sending; plain Enter submits. `Option+M` cycles the active model.
### 🎯 Advanced Intelligent Completion System
Our state-of-the-art completion system provides unparalleled coding assistance:
@@ -95,22 +109,40 @@ Our state-of-the-art completion system provides unparalleled coding assistance:
npm install -g @shareai-lab/kode
```
+> **🇨🇳 For users in China**: If you encounter network issues, use a mirror registry:
+> ```bash
+> npm install -g @shareai-lab/kode --registry=https://registry.npmmirror.com
+> ```
+
+Dev channel (latest features):
+
+```bash
+npm install -g @shareai-lab/kode@dev
+```
+
After installation, you can use any of these commands:
- `kode` - Primary command
- `kwa` - Kode With Agent (alternative)
- `kd` - Ultra-short alias
-### Windows Notes
+### Native binaries (Windows OOTB)
+
+- No WSL/Git Bash required.
+- On `postinstall`, Kode will best-effort download a native binary from GitHub Releases into `${KODE_BIN_DIR:-~/.kode/bin}//-/kode(.exe)`.
+- The wrapper (`cli.js`) prefers the native binary and falls back to the Node.js runtime (`node dist/index.js`) when needed.
+
+Overrides:
+- Mirror downloads: `KODE_BINARY_BASE_URL`
+- Disable download: `KODE_SKIP_BINARY_DOWNLOAD=1`
+- Cache directory: `KODE_BIN_DIR`
+
+See `docs/binary-distribution.md`.
-- **Git Bash is optional**: Kode now works natively with Windows cmd.exe and PowerShell.
- - Kode automatically prefers Git Bash/MSYS or WSL Bash when available for better Unix compatibility.
- - If neither is available, it uses cmd.exe which works out of the box.
-- For best experience, consider using VS Code's integrated terminal:
- - Better font rendering and icon support.
- - Fewer path and encoding quirks compared to legacy Command Prompt.
-- Optional: Install Git for Windows for enhanced Unix-like functionality: https://git-scm.com/download/win
-- If you install globally via npm, avoid spaces in the global prefix path to prevent shim issues.
- - Example: `npm config set prefix "C:\\npm"` and reinstall global packages.
+### Configuration / API keys
+
+- Global config (models, pointers, theme, etc): `~/.kode.json` (or `/config.json` when `KODE_CONFIG_DIR`/`CLAUDE_CONFIG_DIR` is set).
+- Project/local settings (output style, etc): `./.kode/settings.json` and `./.kode/settings.local.json` (legacy `.claude` is supported for some features).
+- Configure models via `/model` (UI) or `kode models import/export` (YAML). Details: `docs/develop/configuration.md`.
## Usage
@@ -132,6 +164,24 @@ kode -p "explain this function" path/to/file.js
kwa -p "explain this function" path/to/file.js
```
+### ACP (Agent Client Protocol)
+
+Run Kode as an ACP agent server (stdio JSON-RPC), for clients like Toad/Zed:
+
+```bash
+kode-acp
+# or
+kode --acp
+```
+
+Toad example:
+
+```bash
+toad acp "kode-acp"
+```
+
+More: `docs/acp.md`.
+
### Using the @ Mention System
Kode supports a powerful @ mention system for intelligent completions:
@@ -155,13 +205,61 @@ Kode supports a powerful @ mention system for intelligent completions:
#### 📁 Smart File References
```bash
# Reference files and directories with auto-completion
-@src/components/Button.tsx
-@docs/api-reference.md
+@packages/core/src/query/index.ts
+@docs/README.md
@.env.example
```
The @ mention system provides intelligent completions as you type, showing available models, agents, and files.
+### MCP Servers (Extensions)
+
+Kode can connect to MCP servers to extend tools and context.
+
+- Config files: `.mcp.json` (recommended) or `.mcprc` in your project root. See `docs/mcp.md`.
+- CLI:
+
+```bash
+kode mcp add
+kode mcp list
+kode mcp get
+kode mcp remove
+```
+
+Example `.mcprc`:
+
+```json
+{
+ "my-sse-server": { "type": "sse", "url": "http://127.0.0.1:3333/sse" }
+}
+```
+
+### Permissions & Approvals
+
+- Default mode skips most prompts for speed.
+- Safe mode: `kode --safe` requires approval for Bash commands and file writes/edits.
+- Plan mode: the assistant may ask to enter plan mode to draft a plan file; while in plan mode, only read-only/planning tools (and the plan file) are allowed until you approve exiting plan mode.
+
+### Paste & Images
+
+- Multi-line/large paste is inserted as a placeholder and expanded on submit.
+- Pasting multiple existing file paths inserts `@path` mentions automatically (quoted when needed).
+- Image paste (macOS): press `Ctrl+V` to attach clipboard images; you can paste multiple images before sending.
+
+### System Sandbox (Linux)
+
+- In safe mode (or with `KODE_SYSTEM_SANDBOX=1`), agent-triggered Bash tool calls try to run inside a `bwrap` sandbox when available.
+- Network is disabled by default; set `KODE_SYSTEM_SANDBOX_NETWORK=inherit` to allow network.
+- Set `KODE_SYSTEM_SANDBOX=required` to fail closed if sandbox cannot be started.
+- See `docs/system-sandbox.md` for details and platform notes.
+
+### Troubleshooting
+
+- Models: use `/model`, or `kode models import kode-models.yaml`, and ensure required API key env vars exist.
+- Windows: if the native binary download is blocked/offline, set `KODE_BINARY_BASE_URL` (mirror) or `KODE_SKIP_BINARY_DOWNLOAD=1` (skip download); the wrapper will fall back to the Node.js runtime (`dist/index.js`).
+- MCP: use `kode mcp list` to check server status; tune `MCP_CONNECTION_TIMEOUT_MS`, `MCP_SERVER_CONNECTION_BATCH_SIZE`, and `MCP_TOOL_TIMEOUT` if servers are slow.
+- Sandbox: install `bwrap` (bubblewrap) on Linux, or set `KODE_SYSTEM_SANDBOX=0` to disable.
+
### AGENTS.md Documentation Mode
Use the `#` prefix to generate and maintain your AGENTS.md documentation:
@@ -229,21 +327,145 @@ As long as you have an openai-like endpoint, it should work.
- `/help` - Show available commands
- `/model` - Change AI model settings
- `/config` - Open configuration panel
+- `/agents` - Manage subagents
+- `/output-style` - Set the output style
+- `/statusline` - Configure a custom status line command
- `/cost` - Show token usage and costs
- `/clear` - Clear conversation history
-- `/compact-threshold` - View or set auto-compact threshold ratio (e.g. `/compact-threshold 0.85` or `/compact-threshold 85%`)
+- `/init` - Initialize project context
+- `/plugin` - Manage plugins/marketplaces (skills, commands)
- | Value | Effect | Use Case |
- |-------|--------|----------|
- | 0.80 | Compress earlier, more conservative | Small context models (e.g. deepseek 131k) |
- | 0.85 | Balanced | Medium context models |
- | 0.90 | Default | Large context models (e.g. Claude 200k) |
+## Agents / Subagents
-- `/init` - Initialize project context
+Kode supports subagents (agent templates) for delegation and task orchestration.
+
+- Agents are loaded from `.kode/agents` and `.claude/agents` (user + project), plus plugins/policy and `--agents`.
+- Manage in the UI: `/agents` (creates new agents under `./.claude/agents` / `~/.claude/agents` by default).
+- Run via mentions: `@run-agent- ...`
+- Run via tooling: `Task(subagent_type: "", ...)`
+- CLI flags: `--agents ` (inject agents for this run), `--setting-sources user,project,local` (control which sources are loaded)
+
+Minimal agent file example (`./.kode/agents/reviewer.md`):
+
+```md
+---
+name: reviewer
+description: "Review diffs for correctness, security, and simplicity"
+tools: ["Read", "Grep"]
+model: inherit
+---
+
+Be strict. Point out bugs and risky changes. Prefer small, targeted fixes.
+```
+
+Model field notes:
+- Compatibility aliases: `inherit`, `opus`, `sonnet`, `haiku` (mapped to model pointers)
+- Kode selectors (via `/model`): pointers (`main|task|compact|quick`), profile name, modelName, or `provider:modelName` (e.g. `openai:o3`)
+
+Validate agent templates:
+
+```bash
+kode agents validate
+```
+
+See `docs/agents-system.md`.
+
+## Skills & Plugins
+
+Kode supports the [Agent Skills](https://agentskills.io) open format for extending agent capabilities:
+- **Agent Skills** format (`SKILL.md`) - see [specification](https://agentskills.io/specification)
+- **Marketplace compatibility** (`.kode-plugin/marketplace.json`, legacy `.claude-plugin/marketplace.json`)
+- **Install from any repository** using [`add-skill` CLI](https://github.com/vercel-labs/add-skill)
+
+### Quick install with add-skill
+
+Install skills from any git repository:
+
+```bash
+# Install from GitHub
+npx add-skill vercel-labs/agent-skills -a kode
+
+# Install to global directory
+npx add-skill vercel-labs/agent-skills -a kode -g
+
+# Install specific skills
+npx add-skill vercel-labs/agent-skills -a kode -s pdf -s xlsx
+```
+
+### Install skills from a marketplace
+
+```bash
+# Add a marketplace (local path, GitHub owner/repo, or URL)
+kode plugin marketplace add ./path/to/marketplace-repo
+kode plugin marketplace add owner/repo
+kode plugin marketplace list
+
+# Install a plugin pack (installs skills/commands)
+kode plugin install document-skills@anthropic-agent-skills --scope user
+
+# Project-scoped install (writes to ./.kode/...)
+kode plugin install document-skills@anthropic-agent-skills --scope project
+
+# Disable/enable an installed plugin
+kode plugin disable document-skills@anthropic-agent-skills --scope user
+kode plugin enable document-skills@anthropic-agent-skills --scope user
+```
+
+Interactive equivalents:
+
+```text
+/plugin marketplace add owner/repo
+/plugin install document-skills@anthropic-agent-skills --scope user
+```
+
+### Use skills
+
+- In interactive mode, run a skill as a slash command: `/pdf`, `/xlsx`, etc.
+- Kode can also invoke skills automatically via the `Skill` tool when relevant.
+
+### Create a skill (Agent Skills)
+
+Create `./.kode/skills//SKILL.md` (project) or `~/.kode/skills//SKILL.md` (user):
+
+```md
+---
+name: my-skill
+description: Describe what this skill does and when to use it.
+allowed-tools: Read Bash(git:*) Bash(jq:*)
+---
+
+# Skill instructions
+```
+
+Naming rules:
+- `name` must match the folder name
+- Lowercase letters/numbers/hyphens only, 1–64 chars
+
+Compatibility:
+- Kode also discovers `.claude/skills` and `.claude/commands` for legacy compatibility.
+
+### Distribute skills
+
+- Marketplace repo: publish a repo containing `.kode-plugin/marketplace.json` listing plugin packs and their `skills` directories (legacy `.claude-plugin/marketplace.json` is also supported).
+- Plugin repo: for full plugins (beyond skills), include `.kode-plugin/plugin.json` at the plugin root and keep all paths relative (`./...`).
+
+See `docs/skills.md` for a compact reference and examples.
+
+### Output styles
+
+Use output styles to switch system-prompt behavior.
+
+- Select: `/output-style` (menu) or `/output-style