Kilo Code Rules: How to Configure kilo.jsonc (2026)

Last updated: May 2026 · Covers Kilo Code v7 (GA April 2, 2026)

Kilo Code rebuilt its configuration system when it moved from the Roo-derived v5 codebase to the OpenCode-based v7. The old .kilocoderules and mode files are gone. Everything now lives in kilo.jsonc — a single config file shared across the VS Code extension, the CLI, and Cloud Agents.

This guide covers how the configuration system works, how to write effective rules, how permissions work, how to define custom agents, and templates you can copy directly.

---

The Config File: kilo.jsonc

Kilo Code reads its configuration from kilo.jsonc. There are two valid locations:

• kilo.jsonc — project root (idiomatic default, shown throughout Kilo's docs)
• .kilo/kilo.jsonc — inside the .kilo/ directory for a cleaner repo layout

If both exist, .kilo/kilo.jsonc takes priority. Choose one and stick with it — having both causes the wrong file to win silently.

The file uses JSONC (JSON with comments), so you can annotate entries inline.

Minimal starter:

{
  "$schema": "https://app.kilo.ai/config.json",
  "instructions": [".kilo/rules/*.md"],
  "permission": {
    "bash": "ask",
    "read": "allow",
    "edit": "allow",
    "webfetch": "ask"
  }
}

The $schema line enables autocomplete in VS Code for all valid Kilo config keys — worth including.

Global config lives at ~/.config/kilo/kilo.jsonc. It applies across all projects. Project-level kilo.jsonc takes precedence for any conflicting directives.

---

Rules: The Instructions System

The instructions key accepts an array of file paths, glob patterns, or URLs pointing to markdown files. Kilo loads them at session start and appends their contents to the system prompt.

{
  "instructions": [
    ".kilo/rules/standards.md",
    ".kilo/rules/architecture.md",
    ".kilo/rules/*.md",
    "https://example.com/team-shared-rules.md"
  ]
}

Key behaviours:

• Files matched by glob patterns load in filesystem order
• URLs are fetched at session start with a 5-second timeout — if unreachable, silently skipped
• Project instructions take precedence over global instructions for conflicting directives
• Rules take effect on the next interaction after saving the config file

Recommended structure:

project/
├── kilo.jsonc
└── .kilo/
    └── rules/
        ├── 01-project-overview.md
        ├── 02-build-commands.md
        ├── 03-coding-standards.md
        ├── 04-architecture.md
        └── 05-definition-of-done.md

Numbered prefixes (01-, 02-) control load order — files load alphabetically. Put foundational context first.

What belongs in rule files

Build and test commands — the most important section. Without these, Kilo cannot verify its own work.

## Commands
- Build: `npm run build`
- Test: `npm test`
- Typecheck: `npm run typecheck`
- Lint: `npm run lint`
- Dev: `npm run dev`

Coding standards — concrete and enforceable, not vague principles.

## Standards
- TypeScript strict mode — never use `any`
- async/await only, no .then() chains
- Absolute imports via @/ alias
- No console.log — use logger from @/lib/logger
- Error handling: always catch explicitly, never swallow

Architecture constraints — where business logic lives, which layers are off-limits.

## Architecture
- Business logic in /lib/services only — not in route handlers
- DB access only via Prisma client at @/lib/db — never raw SQL
- No cross-imports between /apps packages — use /packages/shared

Forbidden patterns — explicit prohibitions, not inferred from context.

## Never
- @ts-ignore or @ts-expect-error
- Modify schema.prisma without explicit instruction
- Install new dependencies without asking first
- Bare catch blocks without specifying exception type

Definition of done — what "finished" means so Kilo stops at the right point.

## Done means
- `npm run build` exits 0
- `npm test` passes
- `npm run typecheck` reports no errors
- `npm run lint` reports no warnings

AGENTS.md

Kilo also reads AGENTS.md from the project root if present. This is the same file format used by GitHub Copilot Coding Agent — content you already maintain for one tool works here too. See the GitHub Copilot Coding Agent guide for the full AGENTS.md format.

---

Permissions

The permission key controls which actions Kilo can take automatically versus which require confirmation. This is Kilo v7's replacement for Roo Code's tool groups (read/edit/browser/command/mcp).

Each permission value is one of: allow (runs without asking), ask (prompts each time), or deny (blocked).

{
  "permission": {
    "bash": "ask",
    "read": "allow",
    "edit": "allow",
    "webfetch": "ask"
  }
}

Granular bash permissions — you can pattern-match specific commands:

{
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm test": "allow",
      "npm run lint": "allow",
      "npm run build": "allow",
      "rm *": "deny"
    },
    "read": "allow",
    "edit": "allow"
  }
}

The catch-all "*": "ask" applies to any command not matched by a more specific pattern. More specific patterns take precedence — put "*" first, specific overrides after.

External directory access — Kilo blocks access outside the working directory by default. To allow specific external paths:

{
  "permission": {
    "external_directory": {
      "~/projects/shared-lib/**": "allow"
    }
  }
}

Recommended starting permissions for most projects:

Tool	Value	Reason
bash	ask with git/test/build allowlist	Prevents destructive commands, allows CI loop
read	allow	Context gathering should be automatic
edit	allow	Fast iteration; review diffs in the UI
webfetch	ask	External requests warrant awareness

---

Custom Agents

Agents replace Roo Code's custom modes. Each agent is a markdown file with YAML front matter that defines its role, permissions, and behaviour.

Store agent files in .kilo/agents/ and reference them in kilo.jsonc:

{
  "instructions": [".kilo/rules/*.md"],
  "permission": { "bash": "ask", "read": "allow", "edit": "allow" },
  "agents": [".kilo/agents/*.md"]
}

Example agent — read-only code reviewer:

---
description: Review code without editing source files
mode: primary
permission:
  edit: deny
  bash: ask
  read: allow
---

You are a code review specialist. Focus on correctness, test coverage,
security issues, and maintainability. Provide actionable review comments,
not rewrites. Reference specific file paths and line numbers.

Example agent — documentation writer:

---
description: Write and update technical documentation
mode: primary
permission:
  edit: allow
  bash: deny
  read: allow
---

You write technical documentation: README files, JSDoc comments, API
reference, and architecture notes. You do not write or run code.
You document what the code actually does, not what it should do.

Built-in agents available without configuration: code (default), plan (architecture/planning, replaces old Architect mode), ask (read-only Q&A), debug (focused on root-cause analysis).

---

Workflows

Workflows are reusable slash-commands backed by markdown template files. Store them in .kilo/commands/:

.kilo/
└── commands/
    ├── review.md
    ├── test-coverage.md
    └── changelog.md

Example review.md:

Review the changes in the current branch against main.

Check for:
- Logic errors and edge cases
- Missing tests for new functions
- Security issues (input validation, auth checks, SQL injection)
- TypeScript errors or unsafe casts
- Unused imports or dead code

Output a numbered list of issues, each with file path and line number.

Use the workflow in a session with /review. Workflows accept arguments: /review --focus security passes the argument into the template as $ARGUMENTS.

---

Configuring via the Agent

Kilo has a built-in skill that understands the full kilo.jsonc schema. Instead of editing the file manually, ask the agent:

"Add a rule file at .kilo/rules/testing.md with our testing standards, and add it to the instructions."

The agent edits kilo.jsonc and creates the rule file. It validates the JSON structure before saving and explains what changed. This works in both the CLI and VS Code extension.

---

Templates

TypeScript / Next.js

kilo.jsonc:

{
  "$schema": "https://app.kilo.ai/config.json",
  "instructions": [".kilo/rules/*.md"],
  "permission": {
    "bash": {
      "*": "ask",
      "npm test": "allow",
      "npm run build": "allow",
      "npm run typecheck": "allow",
      "npm run lint": "allow",
      "git *": "allow"
    },
    "read": "allow",
    "edit": "allow",
    "webfetch": "ask"
  }
}

.kilo/rules/01-project.md:

## Project
Next.js 15 App Router, TypeScript strict, Prisma + PostgreSQL, Tailwind.

## Commands
- Build: `npm run build`
- Test: `npm test`
- Typecheck: `npm run typecheck`
- Lint: `npm run lint`

## Standards
- No `any` types
- async/await only
- Absolute imports via @/ alias
- No console.log — use @/lib/logger

## Architecture
- Business logic in /lib/services — not in route handlers
- DB access only via Prisma at @/lib/db

## Never
- Modify schema.prisma without explicit instruction
- Install packages without asking

## Done
Build, tests, typecheck, and lint all pass with no errors.

Python / FastAPI

kilo.jsonc:

{
  "$schema": "https://app.kilo.ai/config.json",
  "instructions": [".kilo/rules/*.md"],
  "permission": {
    "bash": {
      "*": "ask",
      "pytest": "allow",
      "ruff check .": "allow",
      "ruff format .": "allow",
      "mypy .": "allow"
    },
    "read": "allow",
    "edit": "allow"
  }
}

.kilo/rules/01-project.md:

## Project
FastAPI REST API, Python 3.12, SQLAlchemy + PostgreSQL, pytest, ruff.

## Commands
- Test: `pytest`
- Lint: `ruff check .`
- Format: `ruff format .`
- Typecheck: `mypy .`
- Dev: `uvicorn main:app --reload`

## Standards
- Type hints on all function signatures
- Pydantic models for all request/response schemas
- No bare `except:` — always specify exception type

## Architecture
- Routes in /api/routes — thin, call service functions only
- Business logic in /services

## Done
pytest passes, ruff reports no errors, mypy reports no errors.

---

Migrating from Roo Code

If you are coming from Roo Code, the mapping is:

Roo Code	Kilo Code v7
.roorules	rule file in .kilo/rules/, referenced in instructions
.roo/rules/ directory	.kilo/rules/ directory, glob in instructions
.roo/rules-code/	custom agent in .kilo/agents/
.roomodes	agent files in .kilo/agents/
Tool groups (read/edit/command)	permission keys in kilo.jsonc

The content of your rule files transfers without modification. The structure changes. For the full Roo Code migration walkthrough, see Roo Code shutdown and migration guide.

---

Migrating from Cursor

If you are coming from Cursor, .cursorrules content maps directly to a Kilo rule file. Copy the text into .kilo/rules/cursor-rules.md and add it to the instructions array. See Cursor Rules guide for what a well-structured rules file looks like.

---

Verifying Your Configuration

After writing or updating your config, start a fresh Kilo session and run:

"What are the build and test commands for this project?"

"List three things you are not allowed to do in this codebase."

If Kilo answers both accurately from a cold start, the rules are loading correctly. If it cannot, either the instructions path is wrong, the file is not saved, or the content is too long — Kilo, like all tools, deprioritizes instructions buried deep in an oversized rules file.

---

Further Reading

• Kilo Code listing — feature overview and pricing
• Kilo Code official docs — custom rules
• Kilo Code official docs — permissions
• Roo Code shutdown and migration guide — migrating from Roo Code to Kilo
• Cursor Rules guide — migrating from Cursor
• Cline Rules guide — equivalent configuration for Cline
• Claude Code Rules guide — CLAUDE.md configuration reference
• Aider Rules guide — configuration for Aider CLI