Kilo Code
IDE extensionKilo
Open-source AI coding agent extension for VS Code, part of the Kilo agentic engineering platform, configured via shared kilo.jsonc files.
MCP
SupportedMCP servers configured under the top-level mcp key of kilo.jsonc (project or global). Local (STDIO) and remote (Streamable HTTP with SSE fallback) servers, with OAuth 2.0 for remote servers.
Config files
| Path | Scope | Format | Key |
|---|---|---|---|
.kilo/kilo.jsoncPreferred project location; kilo.json also accepted. Takes priority over root kilo.jsonc. | Project | jsonc | mcp |
kilo.jsoncProject-root config alternative. | Project | jsonc | mcp |
~/.config/kilo/kilo.jsoncGlobal config applying to all projects. | Global | jsonc | mcp |
Fields
| Field | Type | Description |
|---|---|---|
type* | "local" | "remote" | Server kind: local spawns a child process over STDIO; remote connects over HTTP/HTTPS. |
command | string[] | Command and arguments to start a local server (e.g. ["node", "/path/to/server.js"]). |
environment | record<string, string> | Environment variables for the local server process. |
url | string | Endpoint URL for a remote server. |
headers | record<string, string> | Custom HTTP headers for remote servers (e.g. Authorization). |
oauth | boolean | Set false to disable the automatic OAuth 2.0 flow for a remote server. |
enabled | boolean | Toggle the server without removing its configuration. |
timeout | number | Timeout in milliseconds. Defaults: 10s for local servers, 15s for remote servers. |
Capabilities
Examples
{
"mcp": {
"my-local-server": {
"type": "local",
"command": ["node", "/path/to/server.js"],
"environment": { "API_KEY": "your_api_key" },
"enabled": true
}
}
}{
"mcp": {
"my-remote-server": {
"type": "remote",
"url": "https://your-server-url.com/mcp",
"headers": { "Authorization": "Bearer your-token" }
}
},
"permission": {
"my_remote_server_*": "allow"
}
}- •Project-level configuration takes precedence over global configuration.
- •For remote servers Kilo tries Streamable HTTP first, then falls back to SSE automatically.
- •Remote servers supporting OAuth 2.0 trigger the auth flow automatically; disable with "oauth": false.
- •Tool auto-approval uses the shared permission key with namespaced names ({server}_{tool}) and wildcard patterns.
- •Config files support {env:VARIABLE_NAME} syntax to reference environment variables.
Skills
SupportedAgent Skills (SKILL.md packages) loaded from .kilo/skills/ (project) and ~/.kilo/skills/ (global), plus cross-agent compatibility directories and extra paths/URLs configured in kilo.jsonc.
Config files
| Path | Scope | Format | Key |
|---|---|---|---|
.kilo/skills/<name>/SKILL.mdProject skills, shareable via version control. | Project | markdown | — |
~/.kilo/skills/<name>/SKILL.mdPersonal skills available in all projects. | Global | markdown | — |
.agents/skills/<name>/SKILL.mdCross-agent compatibility directory, loaded by default. | Project | markdown | — |
.claude/skills/<name>/SKILL.mdClaude Code compatibility directory, loaded when Claude Code Compatibility is enabled. | Project | markdown | — |
Fields
| Field | Type | Description |
|---|---|---|
name* | string | Max 64 characters; lowercase letters, numbers, and hyphens only; must not start or end with a hyphen. Must match the parent directory name. |
description* | string | Max 1024 characters. Describes what the skill does and when to use it; the agent matches requests against this text. |
license | string | License name or reference to a bundled license file. |
compatibility | string | Environment requirements (intended product, system packages, network access, etc.). |
metadata | record<string, string> | Arbitrary key-value mapping for additional metadata. |
Examples
---
name: api-design
description: REST API design best practices and conventions
---
# API Design Guidelines
When designing REST APIs, follow these conventions:
## URL Structure
- Use plural nouns for resources: /users, /orders
- Use kebab-case for multi-word resources: /order-items{
"skills": {
"paths": ["/path/to/shared/skills", "~/my-skills"],
"urls": ["https://example.com/.well-known/skills/"]
}
}- •Progressive disclosure: only name/description metadata is scanned at session start; the full SKILL.md loads on demand via the skill tool.
- •Project skills override global skills with the same name.
- •Compatibility directories: .agents/skills/ is loaded by default; .claude/skills/ when Claude Code Compatibility is enabled.
- •Extra locations via skills.paths (absolute, ~/, or project-relative) and skills.urls (remote directories serving an index.json manifest) in kilo.jsonc.
- •Skills can bundle scripts/, references/, and assets/ directories alongside SKILL.md.
Rules
SupportedPersistent instructions via auto-discovered AGENTS.md files (project root, subdirectories, and global config dir) plus the instructions array in kilo.jsonc pointing at rule files, globs, or URLs.
Config files
| Path | Scope | Format | Key |
|---|---|---|---|
AGENTS.mdPrimary project instruction file at the workspace root; also loadable from any subdirectory. | Project | markdown | — |
.kilo/rules/*.mdConventional rules directory, referenced from the instructions array in kilo.jsonc. | Project | markdown | — |
kilo.jsoncArray of file paths, globs, or URLs pointing to instruction files. Also valid in .kilo/kilo.jsonc. | Project | jsonc | instructions |
~/.config/kilo/AGENTS.mdGlobal instructions applying to all projects; ~/.claude/CLAUDE.md is read for Claude compatibility. | Global | markdown | — |
~/.config/kilo/kilo.jsoncGlobal instruction sources. | Global | jsonc | instructions |
Examples
{
"instructions": [
".kilo/rules/formatting.md",
".kilo/rules/*.md",
"https://example.com/team-instructions.md"
]
}# Restricted files
Files in the list contain sensitive data, they MUST NOT be read
- supersecrets.txt
- credentials.json
- .env- •AGENTS.md is the primary instruction file; CLAUDE.md and CONTEXT.md are also recognized at the project root (discovered via findUp in parent directories too).
- •Per-directory AGENTS.md files are loaded dynamically when the agent reads a file in that directory.
- •The instructions key in kilo.jsonc accepts paths, glob patterns, and URLs; URL sources are fetched at session start with a 5-second timeout.
- •Global instructions from the global kilo.jsonc load after project instructions; project-level instructions take precedence on conflict.
- •Backward compatible with legacy .kilocode/rules/ directories and .kilocoderules files via auto-migration; migrating to kilo.jsonc/AGENTS.md is recommended.
- •Markdown is recommended for rule files, though plain text works.
Hooks
Not supportedKilo Code does not expose user-configurable lifecycle hooks.
- •The official documentation has no hooks feature and no hook configuration file.
- •An open feature request in the official repo (Kilo-Org/kilocode#5827) asks for session lifecycle hooks, confirming they are not currently available.
Commands
SupportedWorkflows (slash commands) as markdown files in .kilo/commands/ (project) or ~/.config/kilo/commands/ (global); the filename becomes the command name.
Config files
| Path | Scope | Format | Key |
|---|---|---|---|
.kilo/commands/<name>.md | Project | markdown | — |
~/.config/kilo/commands/<name>.md | Global | markdown | — |
Fields
| Field | Type | Description |
|---|---|---|
description | string | Shown in the command picker. |
agent | string | Which agent to use when invoking this command. |
model | string | Model override for this command. |
subtask | boolean | When true, runs the command as a sub-agent session. |
Examples
---
description: Submit a pull request with full checks
agent: code
---
# Submit PR Workflow
1. Use grep to check for TODO comments or console.log statements
2. Run tests using bash with npm test
3. If tests pass, stage and commit changes with a descriptive message
4. Push the branch and create a pull request using gh pr create- •Legacy .kilocode/workflows/ files are automatically migrated to the new command format on startup.
- •Workflows can use all built-in tools (read, glob, grep, edit, write, bash, webfetch) and MCP server tools.
Settings
Supportedkilo.jsonc is the primary config file, shared by the VS Code extension, CLI, and JetBrains. Global config at ~/.config/kilo/kilo.jsonc; project config at kilo.jsonc or .kilo/kilo.jsonc.
Config files
| Path | Scope | Format | Key |
|---|---|---|---|
~/.config/kilo/kilo.jsoncGlobal config applying to all projects. | Global | jsonc | — |
.kilo/kilo.jsoncPreferred project config; takes priority over root kilo.jsonc. | Project | jsonc | — |
kilo.jsoncProject-root config alternative. | Project | jsonc | — |
Fields
| Field | Type | Description |
|---|---|---|
permission | record<string, "allow" | ...> | Auto-approval rules for tools, including MCP tools via namespaced {server}_{tool} keys and wildcards. |
instructions | string[] | Paths, globs, or URLs of additional instruction files (see rules surface). |
mcp | record<string, McpServer> | MCP server definitions (see mcp surface). |
skills | { paths?: string[], urls?: string[] } | Extra skill directories and remote skill URLs (see skills surface). |
hide_prompt_training_models | boolean | Hide Kilo Gateway models whose providers may use prompts for training (default false). |
auto_collapse_reasoning | boolean | Collapse reasoning blocks in the chat UI after the agent finishes writing them. |
terminal_command_display | string | Whether terminal command blocks start expanded or collapsed. |
experimental | object | Advanced options not exposed in the UI (e.g. codebase_search, batch_tool, openTelemetry, mcp_timeout, speech_to_text_model). |
Examples
{
"permission": {
"my_server_*": "allow"
},
"instructions": [".kilo/rules/*.md"],
"auto_collapse_reasoning": true,
"experimental": {
"codebase_search": true,
"mcp_timeout": 30000
}
}- •The Settings webview UI (gear icon) reads and writes the same JSONC files; the .kilo/kilo.jsonc version takes priority over root kilo.jsonc if both exist.
- •Settings can be exported/imported as kilo-settings.json from the About tab; files are plain text and portable between machines.
- •The agent has a built-in skill that understands the full kilo.jsonc schema and can edit config on request.
- •An auto-generated $schema in kilo.jsonc documents the full list of available options.
- •Avoid committing API keys (e.g. provider.*.options.apiKey); use environment variables for credentials.