# Kilo Code

Open-source AI coding agent extension for VS Code, part of the Kilo agentic engineering platform, configured via shared kilo.jsonc files.

Schema: 1.0 · Data: ee5de863c30bdbe4fe7dd3e07c7e22ea9bf4ab2248dbc7c35cdbf60bc28be1db

## Configuration

### MCP

Status: supported

MCP 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.

- project: `.kilo/kilo.jsonc` (jsonc) — key: mcp — Preferred project location; kilo.json also accepted. Takes priority over root kilo.jsonc.
- project: `kilo.jsonc` (jsonc) — key: mcp — Project-root config alternative.
- global: `~/.config/kilo/kilo.jsonc` (jsonc) — key: mcp — Global config applying to all projects.
- project: `.kilo/kilo.json` (json) — key: mcp
- project: `kilo.json` (json) — key: mcp
- global: `~/.config/kilo/kilo.json` (json) — key: mcp
- `type`: "local" | "remote" (required) — Server kind: local spawns a child process over STDIO; remote connects over HTTP/HTTPS. Values: local, remote
- `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.
- transports: stdio, http, sse
- auth: oauth, headers
- Tools: supported — MCP tools share the built-in permission system via namespaced {server}_{tool} keys.
- Resources: supported — Servers expose resources alongside tools; Kilo detects available tools and resources automatically.
- JSON and JSONC are supported. add-mcp 2.3.1 defaults new installs to kilo.json and reuses existing project/global files.
- 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.

Local (STDIO) server
```jsonc
{
  "mcp": {
    "my-local-server": {
      "type": "local",
      "command": ["node", "/path/to/server.js"],
      "environment": { "API_KEY": "your_api_key" },
      "enabled": true
    }
  }
}

```


Remote server with auto-approved tools
```jsonc
{
  "mcp": {
    "my-remote-server": {
      "type": "remote",
      "url": "https://your-server-url.com/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  },
  "permission": {
    "my_remote_server_*": "allow"
  }
}

```

Source: https://kilo.ai/docs/automate/mcp/using-in-kilo-code
Checked: 2026-09-07

### Skills

Status: supported

Agent 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.

- project: `.kilo/skills/<name>/SKILL.md` (markdown) — Project skills, shareable via version control.
- global: `~/.kilo/skills/<name>/SKILL.md` (markdown) — Personal skills available in all projects.
- project: `.agents/skills/<name>/SKILL.md` (markdown) — Cross-agent compatibility directory, loaded by default.
- project: `.claude/skills/<name>/SKILL.md` (markdown) — Claude Code compatibility directory, loaded when Claude Code Compatibility is enabled.
- `name`: string (required) — 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 (required) — 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.
- invocation: automatic (request matches skill description), skill tool (explicit load, e.g. "use the api-design skill")
- 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.

SKILL.md
```markdown
---
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

```


Extra skill paths and remote URLs (kilo.jsonc)
```jsonc
{
  "skills": {
    "paths": ["/path/to/shared/skills", "~/my-skills"],
    "urls": ["https://example.com/.well-known/skills/"]
  }
}

```

Source: https://kilocode.ai/docs/customize/skills
Checked: 2026-07-12

### Rules

Status: supported

Persistent 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.

- project: `AGENTS.md` (markdown) — Primary project instruction file at the workspace root; also loadable from any subdirectory.
- project: `.kilo/rules/*.md` (markdown) — Conventional rules directory, referenced from the instructions array in kilo.jsonc.
- project: `kilo.jsonc` (jsonc) — key: instructions — Array of file paths, globs, or URLs pointing to instruction files. Also valid in .kilo/kilo.jsonc.
- global: `~/.config/kilo/AGENTS.md` (markdown) — Global instructions applying to all projects; ~/.claude/CLAUDE.md is read for Claude compatibility.
- global: `~/.config/kilo/kilo.jsonc` (jsonc) — key: instructions — Global instruction sources.
- 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.

Instruction sources (kilo.jsonc)
```jsonc
{
  "instructions": [
    ".kilo/rules/formatting.md",
    ".kilo/rules/*.md",
    "https://example.com/team-instructions.md"
  ]
}

```


Rule file (.kilo/rules/restricted_files.md)
```markdown
# Restricted files

Files in the list contain sensitive data, they MUST NOT be read

- supersecrets.txt
- credentials.json
- .env

```

Source: https://kilocode.ai/docs/advanced-usage/custom-rules
Checked: 2026-07-12

### Hooks

Status: unsupported

Kilo 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.
Checked: 2026-07-12

### Commands

Status: supported

Workflows (slash commands) as markdown files in .kilo/commands/ (project) or ~/.config/kilo/commands/ (global); the filename becomes the command name.

- project: `.kilo/commands/<name>.md` (markdown)
- global: `~/.config/kilo/commands/<name>.md` (markdown)
- `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.
- invocation: /command-name
- 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.

PR submission workflow (.kilo/commands/submit-pr.md)
```markdown
---
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

```

Source: https://kilocode.ai/docs/features/slash-commands/workflows
Checked: 2026-07-12

### Settings

Status: supported

kilo.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.

- global: `~/.config/kilo/kilo.jsonc` (jsonc) — Global config applying to all projects.
- project: `.kilo/kilo.jsonc` (jsonc) — Preferred project config; takes priority over root kilo.jsonc.
- project: `kilo.jsonc` (jsonc) — Project-root config alternative.
- project: `.kilo/kilo.json` (json)
- project: `kilo.json` (json)
- global: `~/.config/kilo/kilo.json` (json)
- `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. Values: expanded, collapsed
- `experimental`: object — Advanced options not exposed in the UI (e.g. codebase_search, batch_tool, openTelemetry, mcp_timeout, speech_to_text_model).
- 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.

kilo.jsonc
```jsonc
{
  "permission": {
    "my_server_*": "allow"
  },
  "instructions": [".kilo/rules/*.md"],
  "auto_collapse_reasoning": true,
  "experimental": {
    "codebase_search": true,
    "mcp_timeout": 30000
  }
}

```

Source: https://kilocode.ai/docs/getting-started/settings
Checked: 2026-07-12

## Search, browser & identification

Not researched. Unknown does not mean unsupported.