kilocode Documentation

Technical Documentation: Kilo-Org/kilocode

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

Kilo Code is an AI coding agent that meets you everywhere you work: VS Code, JetBrains, and the CLI. It's open source with open pricing. You pick from 500+ models, switch between them mid-task, and pay the model provider's rate with zero markup. No API keys required to start.

Installation Copy Section

Pick where you want to run Kilo.

VS Code

Install the Kilo Code extension directly, or grab it from the VS Code Marketplace. Create an account and you'll have access to 500+ models including GPT-6 Astra, Claude Fable 5.1, Gemini 3.8 Flash, Grok 4.6, and DeepSeek V4.1 Flash, all at provider pricing.

CLI

# npm
npm install @kilocode/cli

# curl
curl -fsSL https://kilo.ai/cli/install | bash

# pnpm
pnpm add @kilocode/cli

# bun
bun add -g @kilocode/cli

# Homebrew (macOS / Linux)
brew install Kilo-Org/tap/kilo

# Arch Linux (AUR)
paru -S kilo-bin

Then run kilo in any project directory to start.

JetBrains

Install the Kilo Code plugin from the JetBrains Marketplace, or search "Kilo Code" in Settings → Plugins inside any JetBrains IDE.

Cloud Agent

Run Kilo from the web, no local machine needed, at app.kilo.ai/cloud.

Code Reviews

Set up automated AI code reviews on your pull requests at app.kilo.ai/code-reviews.

Install the CLI from GitHub Releases (binaries)

Download the latest binary from the Releases page.

Notes: x64-baseline is a compatibility build for older CPUs without AVX. musl is the statically linked build for Alpine or minimal Docker images without glibc. kilo-vscode-*.vsix is the VS Code extension package, not the CLI. Source code archives are for building from source.

Agents Copy Section

Kilo ships with specialized agents you switch between depending on the task. You can also build your own custom agents.

• Code - The default. Implements and edits code from natural language.
• Plan - Designs architecture and writes implementation plans before any code gets written.
• Ask - Answers questions about your codebase without touching any files.
• Debug - Troubleshoots and traces issues.

Learn more about agents and custom agents.

What it does Copy Section

• Code generation from natural language, across multiple files.
• Inline autocomplete with ghost-text suggestions and tab to accept.
• Self-checking so the agent reviews and corrects its own work.
• Terminal and browser control to run commands and automate the web.
• Kilo Marketplace to install agents, skills, MCP servers, and plugins that extend what the agent can do.
• 500+ models with mid-task switching, so you can match latency, cost, and reasoning to the job.

Autonomous Mode (CI/CD) Copy Section

Run kilo run with --auto for fully autonomous operation with no prompts, built for CI/CD pipelines:

kilo run --auto "run tests and fix any failures"

--auto auto-approves permission prompts unless a rule explicitly denies the action. Only use it in trusted environments.

Documentation Copy Section

For configuration and everything else, head over to the docs.

Contributing Copy Section

Contributions are welcome from developers, writers, and everyone in between. Start with the Contributing Guide for environment setup, coding standards, and how to open a pull request. See RELEASING.md for the VS Code extension and CLI release process, and packages/kilo-jetbrains/RELEASING.md for the JetBrains plugin.

Please review our Code of Conduct before getting involved.

License Copy Section

MIT. You're free to use, modify, and distribute this code, including commercially, as long as you keep the attribution and license notices. See License.

FAQ Copy Section

Where did Kilo CLI come from?

Kilo CLI is a fork of OpenCode, enhanced to work within the Kilo agentic engineering platform.

Join the community Discord | X | Reddit

Community Triage (`docs/community-triage.md`) Copy Section

Community triage

How we handle pull requests and issues from people outside the Kilo team.

The goal is simple. Maintainers see the community work that matters, and contributors know what happens next.

Background: Slack discussion.

Overview Copy Chapter

flowchart LR
    A[PR or issue opened] --> B[community-label.yml]
    B --> C[Labels: community, needs-triage,<br/>priority:*, first-time-contributor, area:*]
    C --> D[community-sweep.yml<br/>Mon + Thu 17:00 UTC]
    D --> E[Status labels synced]
    D --> F[Queue posted to job summary and Slack]
    F --> G[Tuesday: Bruno]
    F --> H[Friday: Andrea]
    G --> I[Review, label, comment]
    H --> I
    I --> D

Two workflows do the work. Both use script/kilocode/community-triage.ts. A third runs the tests of that script.

The sweep runs the evening before each maintainer slot. Andrea starts Friday and Bruno starts Tuesday with a fresh queue.

Closing Copy Chapter

Only one workflow closes PRs: kilo-auto-close.yml. The sweep and the label workflow close and remove nothing. They only add and remove labels, and the sweep posts the queue.

kilo-auto-close.yml runs every day at 06:00 UTC and is controlled by the single variable KILO_AUTO_CLOSE_ENABLED:

Issues with no activity for 60 days are closed too. A close comment explains the reason.

• KILO_AUTO_CLOSE_ENABLED must be exactly true to close. Any other value makes the workflow log what it would close, and do nothing else. A manual run uses its "dryRun" box instead.
• The sweep sets awaiting-contributor. keep-open is set by hand. The workflow reads both labels at run time, so a label that is a few days old does not close a PR that was active since.

Paused: opencode v2 migration Copy Section

The team is migrating to opencode v2, and community reviews are paused until further notice. A community PR must not be closed because nobody had time to answer it. So KILO_AUTO_CLOSE_ENABLED must be kept set to false while the pause lasts. If it is set to true, kilo-auto-close.yml closes PRs, and the awaiting-contributor rule closes them after 14 days with no warning. Any other value, including unset, closes nothing.

• Labels, priorities and the queue keep working.
• To resume, set the variable to true (gh variable set KILO_AUTO_CLOSE_ENABLED --body true) and remove this note.
• To check what would be closed first, run "kilo-auto-close" by hand with "dryRun" ticked.

Who is a maintainer Copy Chapter

An author or commenter is a maintainer when one of these is true:

• GitHub shows them as OWNER, MEMBER or COLLABORATOR.
• The secret COMMUNITY_TRIAGE_MEMBER_TOKEN (read:org) shows they are in the org.
• Their login is in .github/community-maintainers.json.

The default token cannot see private org members. They look like normal contributors. The member token fixes that, so it is needed. If the secret is missing or empty, the label job and the sweep fail with a clear message, so team PRs are not labeled as community. Org members are never listed in the file.

Bots are ignored.

The list of extra maintainers Copy Section

.github/community-maintainers.json holds logins that count as maintainers but are not in the org: bot and agent accounts, and people outside the org. It has one key, logins, with a list of GitHub logins. The list must be sorted, in lower case and without duplicates. A test checks this.

{
  "logins": ["some-agent-account", "someone-outside-the-org"]
}

• Change the list with a normal PR.
• The file is public. Do not add org members. The member token finds them, and their membership may be private.
• One file serves every repo. The community dashboard reads the same file for its four repos, so the two tools agree on who is a maintainer.
• The dashboard's reviewer list is separate. It says who can be assigned reviews, not who counts as a maintainer.

Labels Copy Chapter

Set by the workflows:

Set by hand:

The sweep owns the status labels, first-time-contributor and quick-win. It adds and removes them on its own. Do not manage them by hand.

The sweep also removes community, first-time-contributor, quick-win and the status labels from open PRs whose author is a maintainer. This fixes labels set before the maintainer list was known. It only handles PRs.

area:* labels are only added, never removed. Fix a wrong one by hand. On every run the sweep also adds an area for a product name in the title of each open community PR.

Whose turn is it Copy Chapter

The sweep reads the comments, reviews, review replies, commits and reopen events of each open community PR. Drafts are skipped. A reopen by the author counts as a reply. The sweep ignores commit dates more than 5 minutes in the future.

The sweep reads only the latest events. If it finds no maintainer reaction on a PR with more events than it can read, it labels the PR needs-triage so a person decides.

stateDiagram-v2
    [*] --> triage: opened, no maintainer reaction
    triage --> awaiting: maintainer comments or requests changes
    triage --> approved: maintainer approves
    awaiting --> review: contributor comments or pushes
    review --> awaiting: maintainer comments or requests changes
    review --> approved: maintainer approves
    approved --> review: contributor pushes again
    awaiting --> closed: 14 days, not keep-open, closing on
    awaiting --> adopted: 14 days, keep-open
    adopted --> [*]: team re-implements or fixes it
    closed --> [*]

The 14 day clock starts at the time of the last maintainer reaction.

Priority Copy Chapter

Every community PR gets a priority label when it opens, so the queue can be sorted at once. The label workflow sets it. The sweep adds it to PRs that have none. Other tools can read the same label.

The type of a PR decides the label:

The first rule that fits decides the type:

1. The title starts with fix, fixes, bugfix, hotfix or revert: fix. Or with docs or documentation: docs. Or with feat or feature: feature.
2. The PR has the label bug: fix. Or documentation or docs: docs. Or enhancement or feature: feature.
3. area:docs is the only area label: docs.
4. The title starts with add, adds, support or implement: feature.
5. Nothing fits: other.

So a PR titled Add docs for X with the documentation label is docs, not a feature. P0 is never automatic.

To change a priority, edit the label on GitHub. The sweep never changes an existing priority, even when the title changes. Priority does not mean the PR is triaged. A PR is triaged when a maintainer reacts, or when it has keep-open.

First-time contributors Copy Chapter

A warm first reply matters most for people who are new here.

• GitHub marks an author as FIRST_TIME_CONTRIBUTOR or FIRST_TIMER until one of their PRs is merged. These PRs and issues get first-time-contributor.
• The label is set when the item opens or is edited. The sweep keeps it in sync on PRs, and removes it after the first merge. Issues keep the label.
• The digest adds "first-time contributor" next to these PRs, and the Slack summary shows how many there are.
• First-time contributors often need a maintainer to approve their workflow runs before CI starts. Approve the runs early. Few checks on a PR can mean this.

Quick wins Copy Chapter

quick-win marks PRs that are small and low-risk, so a maintainer can review them in minutes. It does not mean "merge without review". The sweep sets it when all of these are true:

• The PR is not a draft, its author is a community member, and it is not waiting for the contributor.
• The last commit has passing checks, and GitHub reports the PR as mergeable.
• No changed file is risky: .github/, .kilo/, script/, patches/, packages/kilo-gateway/, package.json or bun.lock.
• One of these shapes fits:

The sweep removes the label when a PR stops fitting, for example after a new push or when checks fail. A PR that GitHub has not yet checked for conflicts misses the label until the next sweep.

A quick win can still need a decision. A new provider docs page is small, but the team still has to keep it up to date.

The digest lists quick wins in their own section, right after "Adopt".

The 14 day rule Copy Chapter

When a PR has been awaiting-contributor for 14 days with no activity:

The sweep itself closes nothing and posts no warning comment. The digest shows the days waiting, so a maintainer can still reply before day 14.

The digest Copy Chapter

Each sweep writes a queue to the job summary, and to Slack. It lists the open community PRs in these sections. An empty section is left out. Each section shows at most 15 PRs, and a line with the number of the others.

A PR can be in "Quick wins" and in its state section. The digest marks first-time contributors and PRs with failing checks next to the PR. Adopt and Quick wins follow the keep-open and quick-win rules. The other sections use the same state rules as the status labels. needs-triage covers both "Needs triage" and "Contributor replied, needs review", because a maintainer should look in both cases.

The maintainer routine Copy Chapter

Open the latest "Community sweep" run. The job summary has the queue. A copy goes to Slack when a Slack secret is set.

1. Adopt: pick an owner and add the PR to the standup doc.
2. Quick wins: review these first. They are the fastest way to clear the queue.
3. Needs triage: decide. Comment on it, or add keep-open. Change the priority if it is wrong. Not sure? Put it in the standup doc.
4. Needs review: the contributor replied. Review again.
5. Approved: merge.
6. Waiting for contributor: nothing to do.

Greet first-time contributors first, and approve their workflow runs.

Friday and Tuesday are three to four days apart. This gives contributors time to reply between reviews.

Useful searches:

• All community PRs: is:pr is:open label:community
• Needs a maintainer: is:pr is:open label:needs-triage
• One area: is:pr is:open label:community label:area:vscode
• Quick wins: is:pr is:open label:quick-win
• First-time contributors: is:pr is:open label:first-time-contributor

Slack Copy Chapter

The sweep can post the queue to Slack. Slack is optional.

• Bot token and channel set: the channel gets one short message with the title, a count per section and a link to the run. Each section is a reply in its thread.
• Only the webhook set: the channel gets the whole queue as one message.
• The bot post fails: the sweep still finishes and logs a warning with the Slack error. If not even the summary was posted, the whole queue goes through the webhook when one is set. If only a thread reply fails, the sweep warns and keeps the rest, so the queue is not posted twice.
• Manual runs: the "slack" box is ticked by default. Untick it to run without posting. Scheduled runs always post.

Issues Copy Chapter

New issues get the community label, needs-triage, first-time-contributor for new authors and an area:* label. The area comes from the required "Component" dropdown in the bug and feature templates. If there is no answer, for example "Other / not sure" or an issue that skips the form, a product name in the title is used instead. The sweep only handles PRs, so older issues get their labels when they are edited, and needs-triage on an issue stays until you remove it by hand.

Setup Copy Chapter

Labels are created by the workflows, and their color and description are kept in line with the list in the script. Run "Community sweep" once by hand after merge to create them and label the open PRs.

Safety Copy Chapter

• community-label.yml uses pull_request_target. It checks out the base branch only. It never runs PR code.
• The sweep and the label workflow close nothing. A test checks that the sweep script has no close call.
• Closed PRs can be reopened by the contributor.

Jetbrains Vscode Settings Parity (`docs/jetbrains-vscode-settings-parity.md`) Copy Section

JetBrains ↔ VS Code Settings Parity: Easy Wins

How parity works here Copy Chapter

Both clients edit the same shared kilo.json through the CLI. So any setting whose
behavior lives entirely in the CLI is an "easy win" for JetBrains: the CLI already does the
work, JetBrains just needs a UI row that writes the config key. No CLI changes, no new feature.

Structural gap: today JetBrains only has Models / Providers / Agent Behavior / Profile
settings pages. There is no General / Display / Experimental / Context / Checkpoints page.
The lift for most easy wins is:

1. Add a new Configurable page (using existing settings/base/ primitives —
   BaseSettingsUi, SettingsRow, SettingsToggle, SettingsListPanel), register it in
   kilo.jetbrains.frontend.xml.
2. Extend the buildConfigPatch allowlist in KiloCliDataParser.kt (currently only
   model, small_model, subagent_model, subagent_variant, default_agent) and add
   boolean/number JSON serialization — it currently only emits strings.
3. Add localized labels to KiloBundle.properties.

No CLI/SDK change and no new runtime feature.

Excluded from "easy" Copy Chapter

Tier 1 — Genuinely easy (CLI does all the work; just add UI + config key) Copy Chapter

Claude Code compatibility: lives under "Agent Behavior" in VS Code, but in JetBrains the
entire backend (KiloClaudeCompatSettings + RPC getter/setter + spawn-env wiring) already
exists with no UI. Exposing it is the single lowest-effort item — just a checkbox bound to the
existing RPC, no config plumbing.

⚠️ Hold back experimental.image_generation (adds a tool) — arguably "enabling a feature."

Tier 2 — Config is easy, but honoring it needs JetBrains rendering work Copy Chapter

Recommendation Copy Chapter

Add a new "General/Display" page + "Experimental" page driven entirely by CLI config,
seeded with Tier 1 behavioral settings, plus wire the already-built Claude Code compat
toggle. This closes most of the non-feature gap with:

• zero CLI/SDK changes,
• one allowlist extension in KiloCliDataParser.buildConfigPatch (add keys + boolean/number serialization),
• reuse of existing settings/base/ UI primitives and test patterns (FakeAppRpcApi
  frontend test + MockCliServer backend body assertion).

Do Tier 2 (reasoning/terminal/edit display defaults) after Tier 1, since it touches the
session-rendering layer rather than being pure config.

Packages Kilo Vscode Docs Opencode Migration Plan (`packages/kilo-vscode/docs/opencode-migration-plan.md`) Copy Section

Feature Parity Plan — Kilo Code VS Code Extension (Rebuild)

Overview Copy Chapter

This extension is a ground-up rebuild of the old Kilo Code extension using Kilo CLI as the backend. Rather than migrating the old extension's codebase, we started fresh with a Solid.js webview, a CLI server manager, and a message-based protocol between extension host and webview. This new extension lives in the kilocode monorepo.

This document tracks remaining work needed for feature parity with the old extension. Each feature links to its detailed parity requirement doc. Features sourced from the GitHub project board include issue links.

Chat UI Feature Parity Copy Chapter

Non-Agent Feature Parity Copy Chapter

Agent Behaviour Tab Parity Copy Chapter

The "Agent Behaviour" settings tab contains 5 sub-tabs in both the legacy and new extensions. The legacy tab was a combined 2800+ lines of UI; the new tab is ~820 lines. Each sub-tab has its own parity doc.

Project Board Issues Copy Chapter

Open issues from the GitHub project board not covered by the feature docs above. Each item has its own detailed doc.

UI Polish & Bugs Copy Section

Features Copy Section

Error Handling & Reliability Copy Section

Infrastructure / Refactoring Copy Section

CLI-Side (tracked here for awareness) Copy Section

Pre-Production Checklist Copy Chapter

Before publishing this extension to the VS Code Marketplace or deploying to users, verify every item below.

Security Copy Section

• Review and tighten CSP — The current policy in KiloProvider._getHtmlForWebview() has several areas to audit:
  • style-src 'unsafe-inline' is broadly permissive — investigate whether nonce-based style loading is feasible now that kilo-ui styles are bundled
  • connect-src http://127.0.0.1:* http://localhost:* allows connections to any localhost port — tighten to the actual CLI server port once known at runtime
  • img-src … https: allows images from any HTTPS origin — scope to ${webview.cspSource} data: unless external images are explicitly needed
  • 'wasm-unsafe-eval' in script-src was added for shiki — confirm it is still required and document the reason
  • ws:// connections to any localhost port — same concern as connect-src
• Validate openExternal URLs — The openExternal handler passes any URL from the webview directly to vscode.env.openExternal() with no allowlist or scheme check. Restrict to https: (and possibly vscode:) schemes, or allowlist specific hosts
• Audit credential storage — CLI stores credentials as plaintext JSON with chmod 0600. Evaluate whether VS Code's SecretStorage API should be used for extension-side secrets, and document the threat model for CLI-managed credentials
• Audit workspace path containment — CLI's path traversal checks are lexical only; symlinks and Windows cross-drive paths can escape the workspace boundary. Determine if additional hardening (realpath canonicalization) is needed before production

Reliability Copy Section

• VS Code error notifications — Critical errors (CLI missing, server crash, connection lost) need VS Code-native notifications (details). Users get no feedback if the webview is hidden
• HTTP request timeouts — SDK calls need configurable timeouts (details)

Testing Copy Section

• Test coverage — Only one test file exists (extension.test.ts). Add integration tests for: server lifecycle, SSE event routing, message send/receive, permission flow, session management
• Multi-theme visual check — Verify the webview renders correctly in at least one light theme, one dark theme, and one high-contrast theme
• Multi-platform smoke test — Test on macOS, Windows, and Linux. Particularly: CLI binary provisioning, path handling, chmod-based credential protection on Windows

Packaging & Marketplace Copy Section

• Bundle size audit — With kilo-ui and its transitive dependencies (shiki, marked, katex, dompurify, etc.) now bundled, measure dist/webview.js size and verify the total .vsix package size is acceptable
• .vscodeignore review — Ensure only necessary files are included in the package (no docs/, src/, test artifacts, or development scripts)
• Marketplace metadata — Verify README.md, CHANGELOG.md, publisher name, extension icon, and package.json fields (displayName, description, categories, keywords, repository) are production-ready
• activationEvents review — Confirm the extension only activates when needed (not *), to avoid impacting VS Code startup time
• Minimum VS Code version — Verify engines.vscode in package.json matches the minimum API features actually used

Logging & Observability Copy Section

• Dedicated output channel — All logging currently goes to console.log mixed with other extensions (details). Create a dedicated "Kilo Code" output channel before production
• Remove or guard verbose logging — Many console.log calls with emojis and debug detail exist in KiloProvider.ts. Gate behind a debug flag or move to the output channel at appropriate log levels

Implementation Notes Copy Chapter

Architecture Copy Section

• Solid.js (not React) powers the webview. JSX compiles via esbuild-plugin-solid. All webview components use Solid's reactive primitives (signals, createEffect, etc.).
• Two separate esbuild builds: extension (Node/CJS) and webview (browser/IIFE), configured in esbuild.js.
• No shared state between extension and webview. All communication is via vscode.Webview.postMessage() with typed messages defined in messages.ts. Provider hierarchy: ThemeProvider → DialogProvider → VSCodeProvider → ServerProvider → LanguageBridge → MarkedProvider → ProviderProvider → SessionProvider → DataBridge.
• CLI backend owns: agent orchestration, MCP lifecycle, tool execution, search/grep/glob, session storage, permissions runtime, custom commands, skills, and fast edits.
• Extension owns: VS Code API integrations (code actions, inline completions, terminal, SCM, settings sync), webview rendering, auth mediation, and any feature not supported by CLI.

kilo-ui Shared Library Copy Section

• kilo-ui shared library: The webview now heavily uses @kilocode/kilo-ui for UI components. A DataBridge component in App.tsx adapts the session store to kilo-ui's DataProvider expected shape, enabling shared components like <KiloMessage> to work with the extension's data model.

Key Differences from Old Extension Copy Section

• No Task.ts or webviewMessageHandler.ts — the CLI server replaces the old in-process agent loop.
• Permissions flow through CLI's ask/reply model, not extension-side approval queues. Permissions are rendered through kilo-ui's DataProvider pattern, not a standalone PermissionDialog.
• Session history is CLI-managed, not stored in VS Code global state.
• MCP servers are configured and managed by the CLI, not the extension.

Packages Kilo Vscode Docs Agent Behaviour Mcp Server Creation (`packages/kilo-vscode/docs/agent-behaviour/mcp-server-creation.md`) Copy Section

MCP Servers Sub-Tab Parity

Priority: P2

The legacy MCP Servers sub-tab (842 lines) had full server lifecycle management. The new sub-tab supports viewing, removing, and toggling servers with live connection status.

Side-by-Side Comparison Copy Chapter

Expandable Server Detail (Legacy Only) Copy Section

When a server was connected and enabled, expanding it showed 5 tabs:

The new extension has none of this expandable detail.

Remaining Work Copy Chapter

Important (P2) Copy Section

• Add MCP Server dialog: Form to define a new server with name, transport type (stdio/SSE), command+args or URL, environment variables. Write to CLI config via updateConfig()
• Edit MCP Server: Allow modifying existing server configurations
• Restart/refresh button: Per-server and "refresh all" buttons. Requires CLI endpoint to restart MCP servers
• Edit config file buttons: Quick links to open global/project MCP config in the editor

Nice to Have (P3) Copy Section

• Expandable server detail: Show tools, resources, instructions, and logs per server when expanded. Requires CLI to expose per-server tool/resource/log data
• Network timeout per server: If CLI supports per-server timeout config, expose it
• Server source badge: Display whether server comes from global or project config
• OAuth/Auth tab: Display auth status for OAuth-based MCP servers (depends on CLI support)

Notes Copy Chapter

The mcp-and-mcp-hub.md doc in non-agent-features/ tracks MCP configuration as a broader feature. This doc focuses specifically on the MCP Servers sub-tab within the Agent Behaviour settings tab. The Marketplace covers MCP server discovery and installation from a registry.

Packages Kilo Vscode Docs Agent Behaviour Modes Subtab Parity (`packages/kilo-vscode/docs/agent-behaviour/modes-subtab-parity.md`) Copy Section

Modes / Agents Sub-Tab Parity

Priority: P2

The legacy "Modes" sub-tab was a 1794-line component with comprehensive mode management. The new "Agents" sub-tab now covers core CRUD (create, edit, delete) after PR #7225 but is still missing several legacy features.

Side-by-Side Comparison Copy Chapter

Mode/Agent CRUD Copy Section

Per-Mode/Agent Settings Copy Section

System Prompt Features Copy Section

Global Custom Instructions Copy Section

Organization Features Copy Section

CLI Agent Fields Not Exposed Copy Section

These are CLI capabilities beyond what the legacy had:

Remaining Work Copy Chapter

Important (P2) Copy Section

• When to Use field: Add a text area for orchestrator routing hints (if CLI supports it)
• System prompt preview: Add a button to view the full rendered system prompt — requires a CLI endpoint to return the assembled prompt for an agent
• Import/Export: Add import (from file) and export (to file) for agent/mode definitions
• Default variant per agent: Expose agent[name].variant for persistent thinking effort defaults
• Hidden/disable toggles: Add visibility controls for agents

Nice to Have (P3) Copy Section

• Rename agent: Allow renaming custom agents (currently name is immutable after creation)
• Edit config JSON buttons: Quick links to open the raw config file for global/project agent config
• Marketplace integration: Button to open mode marketplace (covered by marketplace.md)
• Organization mode features: Share modes banner and org mode warning (depends on org feature implementation)
• Agent mode selector: Dropdown for subagent/primary/all
• Color picker: Visual agent identification
• Per-agent permissions: Collapsible permission override section per agent
• Copy system prompt: Clipboard button for the assembled prompt

Packages Kilo Vscode Docs Agent Behaviour Rules Workflows Subtab Parity (`packages/kilo-vscode/docs/agent-behaviour/rules-workflows-subtab-parity.md`) Copy Section

Rules & Workflows Sub-Tabs Parity

Priority: P2 (Rules), P3 (Workflows)

The legacy extension had feature-complete Rules and Workflows sub-tabs with toggle lists, file creation, and global/workspace separation. The new extension has a simpler Rules sub-tab and a stub Workflows sub-tab.

Rules Sub-Tab Comparison Copy Chapter

Key Architectural Difference Copy Section

The legacy extension auto-discovered rule files from well-known filesystem locations and displayed them with on/off toggles. The new extension treats instruction files as explicit config entries — you add paths to config.instructions and they're always active. There's no discovery or toggling.

Workflows Sub-Tab Comparison Copy Chapter

Remaining Work Copy Chapter

Rules (P2) Copy Section

• Description text: Add explanatory description with link to docs, matching the legacy pattern
• Global vs workspace separation: If the CLI distinguishes between global and workspace instruction files, separate them into two sections
• Enable/disable toggles: If rules can be toggled without removing them from config, add toggle switches per rule
• New rule file creation: Add a button/input to create a new rule file (not just add an existing path)
• Auto-discovery: Consider adding a section showing auto-discovered rule sources (.kilocode/rules/, AGENTS.md) that the CLI loads regardless of explicit config.instructions entries

Workflows (P3) Copy Section

• Implement the sub-tab: Replace the placeholder with actual workflow management
• Determine CLI mapping: The CLI has custom commands — determine whether "workflows" maps to CLI custom commands or is a distinct concept
• Workflow file management: Add toggle list for global/workspace workflow files with create/enable/disable
• Description text: Add explanatory description matching the legacy pattern

Notes Copy Chapter

The existing non-agent-features/rules-and-workflows.md doc covers workflows broadly. This doc adds the specific UI comparison for what the sub-tabs look like in the Agent Behaviour tab. The CLI's config.instructions array is a simpler model than the legacy's auto-discovered toggle list — the extension may need to augment it with discovery logic to match parity.

Packages Kilo Vscode Docs Chat Ui Features Browser Session Controls (`packages/kilo-vscode/docs/chat-ui-features/browser-session-controls.md`) Copy Section

Browser Session Controls

Priority: P3

Remaining Work Copy Chapter

• In-chat browser session controls (start/stop/navigate)
• Action replay and control buttons
• Screenshot viewing within chat messages
• Dedicated browser tool rendering (currently falls through to generic MCP tool display)

Packages Kilo Vscode Docs Chat Ui Features Checkpoint Task Management (`packages/kilo-vscode/docs/chat-ui-features/checkpoint-task-management.md`) Copy Section

Checkpoint & Task Management

Priority: P1

CLI-side snapshot service is fully implemented (packages/opencode/src/snapshot/). Extension has a settings toggle. What's missing is the management UI.

Remaining Work Copy Chapter

• Checkpoint restore dialogs
• Checkpoint navigation menu / timeline
• Diff viewing between checkpoints
• "See New Changes" buttons to view git diffs for completed tasks
• Integration with CLI session undo/redo/fork operations
• Consider reusing kilo-ui's MessageNav component
• Evaluate whether CLI session undo/redo/revert maps to Kilo's checkpoint model or if extension needs its own git-based implementation

Packages Kilo Vscode Docs Chat Ui Features Mermaid Diagram Features (`packages/kilo-vscode/docs/chat-ui-features/mermaid-diagram-features.md`) Copy Section

Mermaid Diagrams

Chat Markdown renders fenced mermaid code blocks as diagrams after a response finishes streaming.

Behavior Copy Chapter

• Valid mermaid fences render inline as SVG diagrams.
• The original Mermaid source remains available through the existing code-block copy button.
• Rendered diagrams include Copy and Download menus for Mermaid source, SVG, and PNG formats.
• The Zoom action opens a fullscreen viewer with zoom in/out and reset controls, mouse-wheel zoom, drag-to-pan, and keyboard shortcuts (+, -, 0, Escape).
• Invalid Mermaid syntax shows a contained error state and keeps the source visible.
• Diagrams are not rendered while a message is streaming, which avoids repeated parse/render work on every token.
• Diagram colors are derived from the active VS Code/Kilo CSS variables so light, dark, and high-contrast themes can render with matching backgrounds, text, borders, and link colors.

Limitations Copy Chapter

• Mermaid is bundled by the current webview build, so bundle splitting remains a future optimization.
• Advanced legacy actions are not restored yet: AI syntax fixing.

Packages Kilo Vscode Docs Chat Ui Features Message Editing Management (`packages/kilo-vscode/docs/chat-ui-features/message-editing-management.md`) Copy Section

Message Editing & Management

Priority: P1

Remaining Work Copy Chapter

• Edit user messages inline (with full chat input features — mode selector, image attachments, cancel/save)
• Delete user messages from conversation
• Click-to-edit on message text
• Timestamp display on messages
• Redo previous message via up-arrow key
• Map edit/delete to CLI session operations (fork-from-message + re-run)

Packages Kilo Vscode Docs Chat Ui Features Special Content Types (`packages/kilo-vscode/docs/chat-ui-features/special-content-types.md`) Copy Section

Special Content Types

Priority: P1

Remaining Work Copy Chapter

• Copy button on error cards (error text displays but no dedicated copy action)
• Dedicated MCP tool/resource rows with specialized rendering (beyond generic fallback)
• "Open markdown preview" button (opens rendered markdown in VS Code's preview pane)

Packages Kilo Vscode Docs Cli Side Architect Mode Plan Files (`packages/kilo-vscode/docs/cli-side/architect-mode-plan-files.md`) Copy Section

Re-add Architect Mode / Enhance Plan Mode to Write Plan Files

Priority: P2
Status: ❌ Not started
Issue: #6230

Problem Copy Chapter

The old Kilo Code extension had an "Architect mode" that would write the resulting plan as a .md file into a /plans directory in the project root. Users adopted this workflow and now miss it.

The new extension has Plan mode, but plans are stored only inside .opencode/ — not as human-readable .md files in the project. Users can't see or reference their plans easily.

Remaining Work Copy Chapter

Options (pick one or combine):

1. Enhance Plan mode — After a plan is finalized, automatically write it as a .md file to a /plans directory in the project root. The filename could be based on the plan title or a timestamp. This happens in addition to the internal .opencode/ storage.

2. Re-add Architect mode — Add a distinct "Architect" mode that is specifically focused on writing plans as .md files to /plans.

3. Prompt Plan mode — When finishing a plan, offer the user a choice: "Save plan to /plans/plan-name.md?" with accept/dismiss.

Option 3 is the least disruptive. The recommended approach is to add an "Export plan" action button in the Plan mode UI that saves the current plan to /plans/.

Implementation Notes Copy Chapter

• This requires CLI-side changes to the Plan mode behavior and/or an extension-side "export plan" button
• The plan content is available in the session; extracting it requires identifying what parts constitute the plan output
• /plans/ directory creation should be done safely (don't overwrite existing files without confirmation)

Packages Kilo Vscode Docs Cli Side Init Secret Check (`packages/kilo-vscode/docs/cli-side/init-secret-check.md`) Copy Section

/init Pre-Commit Secret Check

Priority: P2
Issue: #6077

Remaining Work Copy Chapter

• In the CLI's /init command, after writing init files, check if the repository has:
  • A .pre-commit-config.yaml with a secret scanning hook
  • A .git/hooks/pre-commit file
  • A detect-secrets baseline file (.secrets.baseline)
• If none found, output a recommendation with link to detect-secrets or gitleaks
• Optionally: offer to install detect-secrets as part of init flow

Packages Kilo Vscode Docs Cli Side Plan Mode Over Prompting (`packages/kilo-vscode/docs/cli-side/plan-mode-over-prompting.md`) Copy Section

Plan Mode Over-Prompting to Implement

Priority: P1
Issue: #6143

The plan mode prompt is verbose. The agent still tends to ask "Should I implement this?" repeatedly.

Remaining Work Copy Chapter

• Review the Plan mode system prompt for language that encourages the agent to switch to implementation
• The prompt should make clear that in Plan mode, the agent's job is to help create and refine a plan — not implement
• "Should I implement this?" should be asked at most once, after the plan appears settled
• Coordinate with team on correct Plan mode behavior before changing the prompt

Packages Kilo Vscode Docs Error Handling Autocomplete Settings Link (`packages/kilo-vscode/docs/error-handling/autocomplete-settings-link.md`) Copy Section

Autocomplete Broken Notice — Settings Link Not Clickable

Priority: P1
Issue: #6284

Autocomplete settings tab exists but the "settings" link in the broken notice may not navigate to it.

Remaining Work Copy Chapter

• Fix the "settings" link in the autocomplete broken notice to navigate to the Autocomplete settings tab
• Investigate why autocomplete model selector shows "no model selected" by default — add a sensible fallback
• Check whether the "autocomplete broken" state is correctly detected and cleared

Packages Kilo Vscode Docs Error Handling Cli Startup Errors (`packages/kilo-vscode/docs/error-handling/cli-startup-errors.md`) Copy Section

Surface CLI Startup Errors in the Extension

Priority: P1
Issue: #6209

StartupErrorBanner exists in webview but VS Code-native notifications for startup failures are missing.

Remaining Work Copy Chapter

• Detect CLI process unexpected exit before port announced (process.on('exit', ...) in ServerManager)
• Capture last N lines of stderr
• Show error notification with "Show Logs" and "Retry" buttons
• Add 'failed' state to ConnectionState
• For malformed config: parse error and show human-readable hint

Packages Kilo Vscode Docs Error Handling Extension Refresh On Update (`packages/kilo-vscode/docs/error-handling/extension-refresh-on-update.md`) Copy Section

Extension View Doesn't Refresh on Restart/Update

Priority: P1
Issue: #6086

Remaining Work Copy Chapter

• Subscribe to vscode.extensions.onDidChange to detect extension updates
• When Kilo Code is updated, force-reload the webview panel (dispose and recreate, or post reload message)
• Ensure panel is properly disposed and recreated on extension host restart

Packages Kilo Vscode Docs Error Handling Pre Release Switch Crash (`packages/kilo-vscode/docs/error-handling/pre-release-switch-crash.md`) Copy Section

CPU Spike / Crash When Switching Pre-Release <> Release

Priority: P0
Issue: #6083

ServerManager has startup guards and process cleanup, but no explicit handling for version switch conflicts.

Remaining Work Copy Chapter

• Reproduce and profile CPU usage during release <> pre-release switch
• Check if both versions attempt to spawn kilo serve simultaneously causing port/race conflicts
• Ensure deactivate() fully terminates the server process before new version starts
• Check for file lock conflicts on shared state (e.g., agent-manager.json, CLI config)

Packages Kilo Vscode Docs Error Handling Propagate Cli Errors To Ui (`packages/kilo-vscode/docs/error-handling/propagate-cli-errors-to-ui.md`) Copy Section

Propagate All CLI Errors to the UI

Priority: P1
Issue: #6146

Remaining Work Copy Chapter

• Intercept CLI error output (stderr) in ServerManager / KiloConnectionService
• Show VS Code error notification for critical/startup errors
• Inject error messages into chat UI as system messages for mid-session errors
• Ensure CLI's error SSE events are forwarded to the webview and rendered
• Distinguish between startup errors and runtime errors

Packages Kilo Vscode Docs Features Background Agent Visibility (`packages/kilo-vscode/docs/features/background-agent-visibility.md`) Copy Section

Background Agent Visibility

Priority: P1

Background subagents are enabled by default, so a session can have several async agents running at once. The parent transcript shows a task card while the agent runs and injects the result when it finishes, but the card scrolls away. Once it is off screen there is no way to see that agents are still running, how many, or what they are doing.

The CLI already solves this. It keeps a per-session subagent list with status (running, done, cancelled, error), shows a subagents hint in the status line, and opens a subagent inspector tab. See packages/opencode/src/cli/cmd/run/subagent-data.ts and footer.command.tsx.

Goal Copy Chapter

Give the VS Code extension the same observability, without inventing a new viewer. Clicking an agent must keep landing in the surfaces users already have:

• Agent Manager: the shared right-hand inspector (SubagentPanel), reached with the agentManager.openSubagent event.
• Sidebar and Kilo tab: a dedicated editor tab, reached with the openSubAgentViewer message.

Placement Copy Chapter

The indicator goes in the task header strip slot, directly above the existing to-do strip in TaskHeader.tsx.

┌──────────────────────────────────────────────┐
│ Upstream background agents…   $6.72  26%  ⌄  │  session header
├──────────────────────────────────────────────┤
│ ⟳ 3 agents                               ⌄  │  NEW strip, collapsed
├──────────────────────────────────────────────┤
│ ⌗ 0/1 to-dos done                        ⌃  │  existing to-do strip
├──────────────────────────────────────────────┤
│  …transcript…                                │

├──────────────────────────────────────────────┤
│ ⟳ 3 agents                               ⌃  │
│   ⟳ Refactor task registry              ↗   │
│   ⟳ Audit dependency versions           ↗   │
│   ⟳ Research meaning of life            ↗   │
├──────────────────────────────────────────────┤

Why this slot:

• The to-do strip already proves the pattern: conditional, collapsible, sticky, one line when collapsed, full width when open.
• It costs zero vertical space when no agent runs.
• It cannot scroll away, which is the actual defect.
• TaskHeader is shared through ChatView, so the sidebar, the Kilo tab, and Agent Manager all get it.

Rejected: the action row above the composer (ChatView.renderActions). It is already full in a narrow sidebar, its buttons appear and disappear with session status, and it is an actions row rather than a status row.

State source Copy Chapter

The webview uses the Kilo-owned background-job API for authoritative lifecycle state. A task-part fallback keeps running agents visible while the first request is loading:

The per-session tool index matters for correctness, not only cost. allParts() holds the parts of every loaded session, so deriving from it would make one session's strip list agents started by another session, which is wrong in Agent Manager where several sessions are loaded at once. The index is keyed by session, so the strip lists only agents this session started. Agents started by a sub-agent appear in that sub-agent's own header, not in the root strip.

An agent counts as running only when its child session status is busy or retry. This fails closed: a stale running part from a previous backend process does not produce a phantom spinner.

Implementation Copy Chapter

1. packages/opencode/src/kilocode/server/httpapi/
   Kilo-owned parent-scoped background-job list and cancellation routes.
2. webview-ui/src/components/chat/open-subagent.ts
   Shared helper holding the Agent Manager vs sidebar branch. Extracted from TaskToolExpanded.openInTab so the task card and the strip cannot drift apart.
3. webview-ui/src/components/chat/background-agents.ts
   Pure derivation for backend lifecycle rows and the running-task fallback.
4. webview-ui/src/components/chat/BackgroundAgents.tsx
   The strip. Collapsed by default, opens an agent through the shared helper.
5. TaskHeader.tsx renders ``.
6. styles/task-header.css adds [data-component="task-header-agents"].
7. i18n/*.ts adds the localized task.backgroundAgents.* strings.
8. tests/unit/background-agents.test.ts covers lifecycle derivation, attention attribution, and promotion discovery.

Concurrency Copy Chapter

Opening an agent from the strip while its task card is also open is safe. VisibleTaskStreams refcounts stream visibility per session, and only visible: false releases a child session, so two openers cannot cut each other's stream.

The strip itself does not sync any child session. It only reads status, so listing agents stays cheap and full part streaming happens on open.

Known limits Copy Chapter

• The strip marks agents that need permission or question input, but the user must open the child inspector or editor tab to answer it.
• The strip has no elapsed-time counter or dedicated keyboard shortcut.
• Finished rows can be dismissed locally, but dismissal does not delete the child session or backend job record.

Packages Kilo Vscode Docs Features Expandable Mcp Tools (`packages/kilo-vscode/docs/features/expandable-mcp-tools.md`) Copy Section

Expandable MCP Tools in Chat

Priority: P2
Issue: #6229

MCP tool calls render as non-expandable entries.

Remaining Work Copy Chapter

• Make MCP tool call rows expandable, matching regular tool expand/collapse behavior
• Expanded view should show: tool name, MCP server name, input arguments (JSON), tool output/result
• Use same UI pattern as regular tools (chevron icon, collapsible section)

Packages Kilo Vscode Docs Features File Attachments (`packages/kilo-vscode/docs/features/file-attachments.md`) Copy Section

File Attachments in Chat Input

Priority: P2
Issue: #6078

Image attachments and @file path mentions work. Non-image file content attachments are missing.

Supported Image Types Copy Chapter

The following image formats are supported for paste and drag-and-drop:

• PNG (image/png)
• JPEG (image/jpeg)
• GIF (image/gif)
• WebP (image/webp)

Drag-and-Drop (Shift Required) Copy Chapter

VS Code disables webview pointer-events during drag operations so it can handle drops in the editor area. To drop images into the chat input, hold Shift while dragging. This re-enables the webview to receive drop events (VS Code 1.91+, see microsoft/vscode#182449).

Remaining Work Copy Chapter

• Add a file attachment button to the chat input toolbar (paperclip icon or similar)
• Support drag-and-drop of non-image files onto the chat input area
• Support a file picker dialog via the button
• For text-based files: read content and include as a text part in the message
• For binary files: show an unsupported notice
• Show attached files as chips/tags above the input with remove button
• Limit attachment size with a clear error if exceeded

Packages Kilo Vscode Docs Features Remember Last Model (`packages/kilo-vscode/docs/features/remember-last-model.md`) Copy Section

Remember Last Model Choice

Priority: P2
Issue: #6211

Model selection is in-memory only. No persistence across sessions/restarts.

Remaining Work Copy Chapter

• On model change, persist choice to globalState.update('lastModel', modelId)
• On new session, pre-select last-used model via globalState.get('lastModel')
• Fall back to default gracefully if stored model is no longer available

Packages Kilo Vscode Docs Features Session Preview Improvements (`packages/kilo-vscode/docs/features/session-preview-improvements.md`) Copy Section

Session Preview Improvements

Priority: P2
Issue: #6234

Session titles are often too short to distinguish sessions.

Remaining Work Copy Chapter

• Evaluate options: show first message snippet as subtitle, improve title generation, show message count/timestamp
• Review the "recent sessions" cards on the start/home screen
• User testing preferred to determine most useful approach

Packages Kilo Vscode Docs Infrastructure Changelog On Update (`packages/kilo-vscode/docs/infrastructure/changelog-on-update.md`) Copy Section

Show Changelog on Extension Update

Priority: P3
Issue: #6079

No version comparison or "What's New" notification exists.

Remaining Work Copy Chapter

• On activation, compare current version against last-seen version in globalState
• If version changed, show notification with "What's New" and "Dismiss" options
• Update stored version after showing
• Do not show on first install

Packages Kilo Vscode Docs Infrastructure Dedicated Output Channel (`packages/kilo-vscode/docs/infrastructure/dedicated-output-channel.md`) Copy Section

Dedicated Output Channel

Priority: P2

Agent Manager has its own output channel. No general "Kilo Code" output channel exists.

Remaining Work Copy Chapter

• Create vscode.window.createOutputChannel("Kilo Code") during activation
• Centralized logging utility with log levels (debug, info, warn, error)
• Route all [Kilo New] log messages to this channel
• Dispose on deactivation
• Migrate existing console.log("[Kilo New] ...") calls to the logger

Packages Kilo Vscode Docs Infrastructure Http Request Timeouts (`packages/kilo-vscode/docs/infrastructure/http-request-timeouts.md`) Copy Section

HTTP Request Timeouts

Priority: P1

Health check has a 3s timeout via AbortController. SSE has a 15s heartbeat timeout. General SDK calls have no timeouts.

Remaining Work Copy Chapter

• Add configurable request timeout (default: 60s) around SDK calls in KiloProvider
• Add shorter connect timeout where possible (default: 10s)
• Ensure timeout cleanup on successful response (no leaked timers)

Packages Kilo Vscode Docs Infrastructure Openvsx Publish (`packages/kilo-vscode/docs/infrastructure/openvsx-publish.md`) Copy Section

Publish to OpenVSX

Priority: P3
Issue: #6080

Remaining Work Copy Chapter

• Create OpenVSX publisher account
• Add ovsx publish step to CI/CD pipeline after VS Code Marketplace publish
• Set up OpenVSX token as CI secret
• Test the publish manually first

Packages Kilo Vscode Docs Infrastructure Vscode Error Notifications (`packages/kilo-vscode/docs/infrastructure/vscode-error-notifications.md`) Copy Section

VSCode Error Notifications for Critical Failures

Priority: P1

showErrorMessage is used in peripheral services (commit, Agent Manager, autocomplete). Core connection errors only go to console.error and webview postMessage.

Remaining Work Copy Chapter

• Show showErrorMessage() when CLI binary is missing or server fails to start
• Show showWarningMessage() when SSE connection is lost (with "Retry" action)
• Avoid notification spam — throttle or deduplicate repeated errors

Packages Kilo Vscode Docs Nes Examples INSTRUCTIONS (`packages/kilo-vscode/docs/nes-examples/INSTRUCTIONS.md`) Copy Section

NES Test Playground — Instructions

These tests are designed so that the source files contain no hints about what Mercury is supposed to predict. All cursor placements and expected behaviors live here. Don't open this file inside the Dev Host while testing — keep it in a separate window so the model can't see it.

One-time setup Copy Chapter

1. bun run watch is already running for the kilocode extension.
2. In the kilocode VSCode window, press F5 → opens the Extension Development Host.
3. In the Dev Host: File → Open Folder… → packages/kilo-vscode/docs/nes-examples/ inside this repo.
4. Open Settings (Cmd+,), confirm:
   • kilo-code.new.autocomplete.enableAutoTrigger → ✓ (default true)
   • kilo-code.new.autocomplete.model → Mercury Next Edit (Inception) ← NOT "Mercury Edit 2", which is the classic FIM option
   • kilo-code.new.autocomplete.nextEdit.apiKey → your sk_... key
   • VSCode global editor.inlineSuggest.enabled → ✓
5. To watch the pipeline live: View → Output → pick the "Kilo Code · Next Edit" channel.

Conventions used below Copy Chapter

• Cursor placement: where to click in the file before waiting.
• Expected (editor): what should appear on screen.
• Expected (channel): a stripped-down line you should see in the Next Edit output channel.
• Path: which NES rendering path this exercises — same-line ghost / off-cursor replace / off-cursor insert / suppressed.

After each test, don't accept if you want to re-run it — the suggestion will edit the file. Either Cmd+Z after accept, or just navigate to the next test file.

Core tests (Python) Copy Chapter

01 — Finish a function body *(path: same-line insert)* Copy Section

• File: 01_finish_function_body.py
• Cursor: the empty indented line at the end of factorial (column 4).
• Expected editor: ghost text proposing the recursive case.
• Expected channel: diff at lines [N..N], cursor at line N, then RENDER.

02 — Pattern continuation *(path: same-line ghost)* Copy Section

• File: 02_pattern_continuation.py
• Cursor: end of the last line (after COLOR_BLUE = ).
• Expected editor: ghost text appending a hex color.
• Expected channel: diff at lines [N..N], cursor at line N, then RENDER.

03 — Mid-identifier completion *(path: same-line ghost)* Copy Section

• File: 03_typo_completion.py
• Cursor: end of the file (after return tot).
• Expected editor: ghost text completing the identifier.
• Path: same-line.

04 — Loop body inference *(path: same-line insert)* Copy Section

• File: 04_loop_body.py
• Cursor: the empty indented line inside the for loop (column 8).
• Expected editor: ghost text proposing the accumulator update.

05 — Sibling method body *(path: same-line insert)* Copy Section

• File: 05_class_method.py
• Cursor: empty indented line inside pop (column 8).
• Expected editor: ghost text proposing the pop body.

Advanced Python tests Copy Chapter

07 — Multi-line rename refactor *(path: off-cursor replace)* Copy Section

• File: 07_multiline_rename_refactor.py
• Cursor: end of the line with def compute_user_score(user_id, weight): (the renamed signature). The body below still uses the old u / w names.
• Expected editor: strikethrough on the body lines + ghost showing the renamed body.
• Tab: jump, then apply.

08 — Mixed insert + replace *(path: off-cursor replace, multi-line)* Copy Section

• File: 08_mixed_insert_and_replace.py
• Cursor: end of line total = 0.
• Expected editor: a decoration spanning the for-loop area showing the corrected accumulator body. The proposed text is longer than the original.

10 — Mid-token completion *(path: same-line ghost)* Copy Section

• File: 10_mid_token_completion.py
• Cursor: end of the file (after result = fib).
• Expected editor: ghost extending the identifier and supplying a call.

11 — Stub method with implemented siblings *(path: same-line insert)* Copy Section

• File: 11_fill_sibling_method.py
• Cursor: empty indented line inside dequeue (column 8).
• Expected editor: ghost text filling in the FIFO body.

12 — Type annotation insertion *(path: same-line replace OR off-cursor replace)* Copy Section

• File: 12_type_annotation_insertion.py
• Cursor: on line def add(a, b): (anywhere on that line works; end-of-line is easiest).
• Expected editor: strikethrough + ghost showing the typed signature. May render as inline ghost depending on where you place the cursor on the line.

13 — Docstring generation *(path: same-line insert)* Copy Section

• File: 13_docstring_generation.py
• Cursor: empty indented line directly under def parse_iso_date(s): (column 4).
• Expected editor: ghost text starting with """ and a one-line description.

14 — No-op suppression (NEGATIVE) *(path: suppressed)* Copy Section

• File: 14_no_op_suppression.py
• Cursor: end of return a + b.
• Expected editor: NOTHING. No ghost, no decoration.
• Expected channel: either identical replacement — no-op or no RENDER line.
• Fail mode: any visible suggestion is a false positive.

TypeScript Copy Chapter

ts_07 — Array transform *(same-line)* Copy Section

• File: ts_07_array_transform.ts
• Cursor: end of return users inside getActiveUserNames.
• Expected editor: ghost text completing a .filter(...).map(...) chain.

ts_08 — Param type annotations *(off-cursor replace)* Copy Section

• File: ts_08_param_types.ts
• Cursor: end of file (after main();).
• Expected editor: strikethrough on add(a, b) signature + ghost showing the typed version.

ts_09 — React event handler *(same-line insert)* Copy Section

• File: ts_09_jsx_handler.tsx
• Cursor: empty indented line inside handleClick (column 4).
• Expected editor: ghost text incrementing count.

Go Copy Chapter

go_07 — Error handling *(same-line insert, multi-line)* Copy Section

• File: go_07_error_handling.go
• Cursor: empty line right after data, err := os.ReadFile(path).
• Expected editor: ghost text proposing the canonical if err != nil { return nil, err } block.

go_08 — Struct method body *(same-line insert)* Copy Section

• File: go_08_struct_method.go
• Cursor: empty indented line inside Area().
• Expected editor: ghost text computing area from Width and Height.

go_09 — Goroutine + channel *(same-line insert, multi-line)* Copy Section

• File: go_09_goroutine_channel.go
• Cursor: empty indented line inside the goroutine.
• Expected editor: ghost text producing values onto the channel and closing it.

Rust Copy Chapter

rs_07 — Match-arm completion *(same-line)* Copy Section

• File: rs_07_match_arms.rs
• Cursor: empty indented line inside the match s { body, after the Square arm (column 8).
• Expected editor: ghost text proposing the missing Rectangle and Triangle arms.

rs_08 — Result chaining *(same-line ghost)* Copy Section

• File: rs_08_result_chain.rs
• Cursor: end of the line let n = s.trim() (no semicolon yet).
• Expected editor: ghost text continuing the chain into a parsed i32.

rs_09 — Lifetime annotation *(off-cursor replace)* Copy Section

• File: rs_09_lifetimes.rs
• Cursor: end of the file (after main's closing }).
• Expected editor: strikethrough on the fn longest(...) signature + ghost showing the lifetime-annotated version.

JavaScript Copy Chapter

js_07 — Async/await *(same-line insert, multi-line)* Copy Section

• File: js_07_async_await.js
• Cursor: empty indented line inside the try { block (column 8).
• Expected editor: ghost text completing fetch + json parse.

js_08 — Express route handler *(same-line insert, multi-line)* Copy Section

• File: js_08_express_route.js
• Cursor: empty indented line inside the GET handler (column 4).
• Expected editor: ghost text implementing get-by-id (lookup, 404, json response).

SQL Copy Chapter

sql_07 — JOIN clause *(same-line ghost)* Copy Section

• File: sql_07_join.sql
• Cursor: end of the line FROM orders o.
• Expected editor: ghost text completing the JOIN against customers.

sql_08 — WHERE filter *(same-line ghost)* Copy Section

• File: sql_08_where_filter.sql
• Cursor: end of the bare WHERE line.
• Expected editor: ghost text proposing a predicate.

Markdown (negative) Copy Chapter

md_07 — Prose, should stay quiet *(suppressed)* Copy Section

• File: md_07_prose_negative.md
• Cursor: end of the last sentence.
• Expected editor: NOTHING (ideally). If Mercury does propose a continuation of the prose, note it as a soft fail — code models writing your README isn't the v0 product.

Troubleshooting Copy Chapter

• No log lines appearing: confirm the output channel is "Kilo Code · Next Edit". Also confirm you reloaded the Dev Host after rebuilding.
• [NES] skip — no API key resolved: setting wasn't saved. Re-paste the key, hit Enter, reload.
• [NES] <- 400: regression on prompt shape — capture the body in the channel and ping the integration owner.
• Visible suggestion that's not in this doc: write it down. Unexpected wins (or false positives) are the most useful signal.

Packages Kilo Vscode Docs Nes Examples Md 07 Prose Negative (`packages/kilo-vscode/docs/nes-examples/md_07_prose_negative.md`) Copy Section

Mercury Edit 2 — Quick Notes

Mercury Edit 2 is a small, fast model trained to predict the user's
next single edit given the current file, cursor position, and recent
edit history. It targets latency under 200 ms on typical files and
returns a unified-diff-like patch scoped to a window around the cursor.

Unlike chat-style completions, the model is biased toward minimal,
local changes — finishing a function body, fixing a typo, propagating
a rename — rather than generating new files from scratch.

Packages Kilo Vscode Docs Non Agent Features Authentication Organization Enterprise Enforcement (`packages/kilo-vscode/docs/non-agent-features/authentication-organization-enterprise-enforcement.md`) Copy Section

Authentication / Organization / Enterprise Enforcement

Priority: P1

Remaining Work Copy Chapter

• Dropdown to choose between org or personal account, passing the selection via kilo serve to the backend when using the Kilo gateway
• Organization feature flags (restrict features based on org plan/tier)
• MDM policy enforcement (managed device policies, enterprise admin controls, restriction enforcement)

Packages Kilo Vscode Docs Non Agent Features Auto Purge (`packages/kilo-vscode/docs/non-agent-features/auto-purge.md`) Copy Section

Auto-Purge (Task Storage Cleanup)

Priority: P3

Remaining Work Copy Chapter

• Scheduled cleanup of old task/history storage to prevent uncontrolled disk growth
• Decide storage ownership (CLI server vs extension) and implement purge accordingly
• Configurable retention period
• Safe deletion with user confirmation for bulk purge

Packages Kilo Vscode Docs Non Agent Features Cloud Task Support (`packages/kilo-vscode/docs/non-agent-features/cloud-task-support.md`) Copy Section

Cloud Task Support

Priority: P2

Remaining Work Copy Chapter

• Upload/sync local sessions to cloud
• Real-time sync between devices
• Conflict resolution when sessions are modified on multiple devices

Packages Kilo Vscode Docs Non Agent Features Code Reviews (`packages/kilo-vscode/docs/non-agent-features/code-reviews.md`) Copy Section

Code Reviews (Local and Cloud Workflows)

Priority: P2

Remaining Work Copy Chapter

• Local "Review Mode" for AI review of uncommitted changes
• Branch vs base branch review (main/master/develop detection)
• Automated AI review on PR open/update (cloud workflow)
• VS Code review UX integration
• Reuse CLI review templates/prompts where available

Packages Kilo Vscode Docs Non Agent Features Codebase Indexing Semantic Search (`packages/kilo-vscode/docs/non-agent-features/codebase-indexing-semantic-search.md`) Copy Section

Codebase Indexing & Semantic Search

Priority: P2

Remaining Work Copy Chapter

• Vector-based indexing with embeddings (local and/or cloud)
• Semantic search over the repository
• Incremental updates via file watchers and hashing
• Multiple embedding providers and storage backends
• Integration with existing CLI grep/glob for hybrid search

Primary Implementation Anchors (kilocode-legacy) Copy Chapter

These exist in the kilocode-legacy repo, not in this extension:

• src/services/code-index/

Packages Kilo Vscode Docs Non Agent Features Contribution Tracking (`packages/kilo-vscode/docs/non-agent-features/contribution-tracking.md`) Copy Section

Contribution Tracking (AI Attribution)

Priority: P3

Remaining Work Copy Chapter

• Track AI-assisted modifications for organizational reporting
• Formatting-aware diffing
• Line hashing/fingerprinting
• Token/JWT handling for attribution APIs
• Reporting UI

Primary Implementation Anchors (kilocode-legacy) Copy Chapter

These exist in the kilocode-legacy repo, not in this extension:

• src/services/contribution-tracking/

Packages Kilo Vscode Docs Non Agent Features Custom Command System (`packages/kilo-vscode/docs/non-agent-features/custom-command-system.md`) Copy Section

Custom Command System

Priority: P2

Remaining Work Copy Chapter

• Slash command input handling in chat (detect / prefix, show command list)
• Project-level command discovery (scan .kilocode/commands/ or similar)
• YAML frontmatter metadata support
• Symlink-aware command discovery
• VS Code command palette entry points
• Wire to CLI's custom command system for execution

Primary Implementation Anchors (kilocode-legacy) Copy Chapter

These exist in the kilocode-legacy repo, not in this extension:

• src/services/command/

Packages Kilo Vscode Docs Non Agent Features Marketplace (`packages/kilo-vscode/docs/non-agent-features/marketplace.md`) Copy Section

Marketplace (Installable Modes, MCP Servers, Skills)

Priority: P2

Toolbar button exists but renders a stub.

Remaining Work Copy Chapter

• Catalog browsing (Modes, MCP servers, Skills)
• Install/uninstall/update capabilities
• Marketplace API endpoints (may need backend work)
• Search and filtering within the catalog

Packages Kilo Vscode Docs Non Agent Features Mcp And Mcp Hub (`packages/kilo-vscode/docs/non-agent-features/mcp-and-mcp-hub.md`) Copy Section

MCP (Model Context Protocol) & MCP Hub

Priority: P1

Settings UI supports viewing, removing, and toggling MCP servers with live connection status. Add/edit is not yet available.

Remaining Work Copy Chapter

• Add/edit MCP server controls in the settings UI
• Tool allowlisting/disablement per server
• Auto-reconnect and error history display
• MCP Hub for discovering available MCP servers

Packages Kilo Vscode Docs Non Agent Features Repository Initialization (`packages/kilo-vscode/docs/non-agent-features/repository-initialization.md`) Copy Section

Repository Initialization

Priority: P3

Remaining Work Copy Chapter

• Command or button to initialize a repository for agentic engineering
• Creates configuration files (e.g., AGENTS.md, .kilocode/ directory)
• Detects existing project structure and tailors initialization
• May scaffold rules, workflows, or skill configurations
• Accessible from VS Code command palette and/or chat UI
• Determine if this calls a CLI /init endpoint or replicates CLI logic
• Progress/status feedback during initialization

Packages Kilo Vscode Docs Non Agent Features Rules And Workflows (`packages/kilo-vscode/docs/non-agent-features/rules-and-workflows.md`) Copy Section

Rules & Workflows

Priority: P3

Rules subtab exists and works. Workflows subtab is a stub.

Remaining Work Copy Chapter

• Workflow management UI (currently a `` stub in AgentBehaviour settings)
• Workflow definition and execution format
• UI for browsing .kilocode/rules/ and similar rule sources
• Determine CLI endpoints for workflow CRUD

Packages Kilo Vscode Docs Non Agent Features Settings Sync Integration (`packages/kilo-vscode/docs/non-agent-features/settings-sync-integration.md`) Copy Section

Settings Sync Integration

Priority: P3

Remaining Work Copy Chapter

• Register allowlist of extension state/settings for VS Code Settings Sync
• Determine which settings should sync (extension settings in settings.json vs CLI config)
• Optionally mirror a subset of settings into CLI config

Packages Kilo Vscode Docs Non Agent Features Settings Ui (`packages/kilo-vscode/docs/non-agent-features/settings-ui.md`) Copy Section

Settings UI

Priority: P1

12 of 14 tabs are functional. Import/export settings is available in the About tab.

Remaining Work Copy Chapter

• Terminal tab: Shows "Not implemented" message
• Prompts tab: Shows "Not implemented" message
• Workflows subtab (inside AgentBehaviour): Renders a `` with no functionality

Related Docs Copy Chapter

• Agent Behaviour tab (all sub-tabs) → Agent Behaviour Tab Parity
• Workflows subtab → Rules & Workflows Sub-Tabs Parity

Packages Kilo Vscode Docs Non Agent Features Skills System (`packages/kilo-vscode/docs/non-agent-features/skills-system.md`) Copy Section

Skills System

Priority: P2

Config UI for skill paths/URLs exists in AgentBehaviour settings.

Remaining Work Copy Chapter

• Skill execution runtime integration in the extension
• Skill discovery (browse available skills)
• Hot-reload when skill files change

Packages Kilo Vscode Docs Non Agent Features Speech To Text (`packages/kilo-vscode/docs/non-agent-features/speech-to-text.md`) Copy Section

Speech-to-Text (Voice Input)

Priority: P3

Remaining Work Copy Chapter

• Microphone capture in webview
• Streaming STT integration
• Voice input button in prompt area
• Determine STT provider (browser API, CLI-compatible, or external service)

Primary Implementation Anchors (kilocode-legacy) Copy Chapter

These exist in the kilocode-legacy repo, not in this extension:

• src/services/stt/

Packages Kilo Vscode Docs Ui Polish Approval Box Full Path (`packages/kilo-vscode/docs/ui-polish/approval-box-full-path.md`) Copy Section

Approval Box Missing Full Path for Out-of-Workspace Requests

Priority: P1
Issue: #6092

Permission prompt shows whatever CLI sends — no explicit full path display logic.

Remaining Work Copy Chapter

• Always display the full absolute path for file system operations in the permission/approval rendering
• For paths inside the workspace, relative path is acceptable but append a visual indicator if outside the workspace
• For paths outside the workspace, never truncate — show the complete absolute path
• Consider truncating only the beginning of very long paths with an ellipsis

Packages Kilo Vscode Docs Ui Polish Chat Input Narrow Sidebar Overflow (`packages/kilo-vscode/docs/ui-polish/chat-input-narrow-sidebar-overflow.md`) Copy Section

Chat Input Overflows on Narrow Sidebar

Priority: P2
Issue: #6273

Remaining Work Copy Chapter

• Make the chat input toolbar responsive: wrap controls to a second row when sidebar is narrow
• Send button should always remain visible and anchored to the bottom-right
• Use CSS flexbox flex-wrap: wrap or container queries / ResizeObserver
• Test at sidebar widths of ~200px, ~280px, and ~350px

Packages Kilo Vscode Docs Ui Polish Markdown Rendering Improvements (`packages/kilo-vscode/docs/ui-polish/markdown-rendering-improvements.md`) Copy Section

Markdown Rendering Improvements

Priority: P1
Issue: #6088

Headings h1-h6 render at the same visual size as body text. kilo-ui CSS only resets margins, no distinct font sizes/weights.

Remaining Work Copy Chapter

• Add CSS rules for heading elements (h1-h6) with distinct font sizes, weights, and vertical spacing
• Scope heading styles to the markdown content area
• Verify styles across light, dark, and high-contrast VS Code themes
• Also verify: bullet lists, numbered lists, blockquotes, horizontal rules, and bold/italic

Packages Kilo Vscode Docs Ui Polish Profile View Back Button (`packages/kilo-vscode/docs/ui-polish/profile-view-back-button.md`) Copy Section

Profile View Missing Back Button

Priority: P2
Issue: #6140

Profile now opens in a separate editor panel via SettingsEditorProvider, so navigation is handled by VS Code's tab system. Evaluate whether a back button is still needed or if this issue is resolved by the panel-based approach.

Remaining Work Copy Chapter

• Determine if the editor panel approach resolves the original navigation issue
• If not, add a back button to the Profile view header matching the Settings view pattern

Packages Opencode Src Kilocode Docs Migration (`packages/opencode/src/kilocode/docs/migration.md`) Copy Section

Kilocode Migration

This document explains how Kilocode configurations are automatically migrated to Opencode.

Table of Contents Copy Chapter

• Modes Migration
• Skills Discovery
• Rules Migration
• Workflows Migration
• MCP Migration
• Kilo Notifications

Modes Migration

This section explains how Kilocode custom modes are automatically migrated to Opencode agents.

Overview Copy Chapter

Kilocode stores custom modes in YAML files. When Opencode starts, it reads these files and converts them to Opencode's agent format, injecting them via the OPENCODE_CONFIG_CONTENT mechanism.

Source Locations Copy Chapter

The migrator reads custom modes from these locations (in order, later entries override earlier ones):

Global Modes (VSCode Extension Storage) Copy Section

Project Modes Copy Section

Field Mapping Copy Chapter

Migrated Fields Copy Section

Permission Mapping Copy Section

Kilocode uses "groups" to define what tools a mode can access. These are converted to Opencode's permission system:

Important: Permissions that are NOT in the groups list are explicitly set to "deny". This ensures that a mode with only read and edit groups cannot run shell commands or access MCP servers.

File Restrictions Copy Section

Kilocode supports restricting edit access to specific file patterns:

groups:
  - read
  - - edit
    - fileRegex: "\\.md$"
      description: "Markdown files only"

This converts to:

{
  "permission": {
    "read": "allow",
    "edit": {
      "\\.md$": "allow",
      "*": "deny"
    },
    "bash": "deny",
    "mcp": "deny"
  }
}

Note: bash and mcp are explicitly denied because they weren't in the original groups list.

Default Modes Copy Chapter

The following Kilocode default modes are skipped during migration because Opencode has native equivalents:

Example Conversion Copy Chapter

Kilocode Mode (YAML) Copy Section

customModes:
  - slug: translate
    name: Translate
    roleDefinition: You are a linguistic specialist focused on translation.
    customInstructions: |
      When translating:
      - Maintain consistent terminology
      - Preserve formatting
    groups:
      - read
      - - edit
        - fileRegex: "src/i18n/.*\\.json$"
          description: "Translation files only"
    description: Translate content between languages

Opencode Agent (JSON) Copy Section

{
  "agent": {
    "translate": {
      "mode": "primary",
      "description": "Translate content between languages",
      "prompt": "You are a linguistic specialist focused on translation.\n\nWhen translating:\n- Maintain consistent terminology\n- Preserve formatting",
      "permission": {
        "read": "allow",
        "edit": {
          "src/i18n/.*\\.json$": "allow",
          "*": "deny"
        }
      }
    }
  }
}

Not Migrated (Future Phases) Copy Chapter

The following Kilocode features are not yet migrated:

Troubleshooting Copy Chapter

Mode not appearing Copy Section

1. Check the file exists at the expected location
2. Verify YAML syntax is valid
3. Ensure the mode has a unique slug
4. Check it's not a default mode (which are skipped)

Permissions not working Copy Section

1. Verify the groups array is correctly formatted
2. For file restrictions, ensure fileRegex is a valid regex
3. Check the permission mapping table above

Related Files Copy Chapter

• modes-migrator.ts - Core migration logic
• config-injector.ts - Config building and injection

Skills Discovery

Kilocode skills are automatically discovered and made available in Opencode. This is not a migration - skills remain in their original locations and can be managed independently by the Kilo VSCode extension.

How It Works Copy Chapter

Kilo scans canonical .kilo/skill/ and .kilo/skills/ directories alongside legacy .kilocode/ equivalents. The KilocodePaths.skillDirectories() function provides these paths.

Source Locations Copy Chapter

Skills are discovered from these locations (in order, later entries override earlier ones):

Project Skills (Walk-up Discovery) Copy Section

The scanner walks up from the current directory to the git worktree root, finding all .kilocode/skills/ directories:

your-project/
├── .kilocode/
│   └── skills/
│       └── project-skill/
│           └── SKILL.md
└── packages/
    └── my-package/           # If you run from here
        └── .kilocode/
            └── skills/
                └── package-skill/
                    └── SKILL.md

Running from packages/my-package/ discovers both package-skill and project-skill.

Global Skills Copy Section

VSCode Extension Storage (Marketplace Skills) Copy Section

Skill File Format Copy Chapter

Skills use the same SKILL.md format as Opencode:

---
name: my-skill
description: When to use this skill
---

# Instructions

Detailed instructions for the agent...

Priority / Override Behavior Copy Chapter

When the same skill name exists in multiple locations, last one wins. Canonical .kilo/ skills take precedence over legacy .kilocode/ skills at the same project level. Explicit external skill paths and compatibility directories are loaded according to the configured scan order.

Mode-Specific Skills Copy Chapter

Kilocode supports mode-specific skills in skills-{mode}/ directories (e.g., skills-code/, skills-architect/). These are not currently migrated to Opencode.

If you need mode-specific behavior, use Opencode's agent permission system:

{
  "agent": {
    "build": {
      "permission": {
        "skill": {
          "translation": "deny"
        }
      }
    }
  }
}

Symlink Support Copy Chapter

Skills can be symlinked from a shared location:

.agents/skills/shared-skill/          # Actual skill
.kilocode/skills/shared-skill -> ...  # Legacy symlink
.kilo/skill/shared-skill -> ...       # Canonical symlink

The scanner follows symlinks, so a skill installed once can be available to both Kilo VSCode and Opencode CLI.

Related Files Copy Chapter

• paths.ts - skillDirectories() function
• skill.ts - Skill scanning logic

Rules Migration

Kilocode rules are migrated to Opencode's instructions array. See rules-migrator.ts.

Source Locations Copy Chapter

Workflows Migration

Kilocode workflows are migrated to Opencode commands. See workflows-migrator.ts.

Source Locations Copy Chapter

MCP Migration

Kilocode MCP server configurations are migrated to Opencode's mcp config. See mcp-migrator.ts.

Config file location Copy Chapter

The CLI reads global config from ~/.config/kilo/ (see global/index.ts: Global.Path.config = xdgConfig + "kilo"). It merges, in order, config.json, opencode.json, and opencode.jsonc in that directory. You can put MCP config in opencode.json or opencode.jsonc.

• macOS / Linux: ~/.config/kilo/opencode.json (or opencode.jsonc)
• Windows: Config directory depends on xdg-basedir (often under %LOCALAPPDATA% or %USERPROFILE%); filename is still opencode.json or opencode.jsonc.

Use a top-level "mcp" object. Each key is the server name. For a local server, value must have type: "local" and command: ["executable", "arg1", ...]. Optional: environment (env vars), enabled (boolean), timeout (ms). See Config.McpLocal in config.ts. Restart the CLI after editing.

Source Location (migration from Kilocode) Copy Chapter

Kilo Notifications

When connected to Kilo Gateway, the CLI fetches and displays notifications from the Kilo API. This allows Kilo to communicate important announcements, feature updates, and tips to users.

How It Works Copy Chapter

1. On startup, if the user is authenticated with Kilo Gateway, the CLI fetches notifications from https://api.kilo.ai/api/users/notifications
2. Filtering: Only notifications with showIn containing "cli" (or no showIn restriction) are displayed
3. Display: The first notification is shown as a toast notification after a 2-second delay

Notification Data Structure Copy Chapter

interface KilocodeNotification {
  id: string // Unique identifier
  title: string // Notification title (e.g., "Agent skills now supported!")
  message: string // Description text
  action?: {
    actionText: string // Link text (e.g., "Learn More")
    actionURL: string // URL destination
  }
  showIn?: string[] // Target platforms: ["cli", "vscode"]
}

Example Notification Copy Chapter

Title: Agent skills now supported!
Message: Define reusable skills and workflows for your AI agent.
Action: Learn More -> https://docs.kilo.ai/skills

Display Conditions Copy Chapter

Related Files Copy Chapter

• notifications.ts - Fetch function and types
• routes.ts - Server endpoint /kilo/notifications
• app.tsx - TUI notification display logic

Packages Opencode Src Kilocode Docs Rules Migration (`packages/opencode/src/kilocode/docs/rules-migration.md`) Copy Section

Kilocode Rules Migration

This document explains how Kilocode rules are automatically migrated to Opencode's instructions config array.

Overview Copy Chapter

Kilocode stores rules in various file locations. When Opencode starts, it reads these files and injects their paths into the instructions config array, which Opencode then loads as part of the system prompt.

Key Guarantees Copy Chapter

1. Read-Only Migration Copy Section

The migration never modifies project files. We only:

• Read existing rule files from disk
• Inject file paths into the config's instructions array
• Never write to the project or modify any files

2. Combines with Existing Config (Never Overwrites) Copy Section

If you have existing opencode config with instructions, the Kilocode rules are combined, not replaced:

// Example: User has opencode.json with:
{ "instructions": ["AGENTS.md", "custom-rules.md"] }

// Kilocode rules add:
{ "instructions": [".kilocoderules", ".kilocode/rules/coding.md"] }

// Result (combined, deduplicated):
{ "instructions": ["AGENTS.md", "custom-rules.md", ".kilocoderules", ".kilocode/rules/coding.md"] }

3. Restart to Pick Up Changes Copy Section

If you change your Kilocode configuration (e.g., edit .kilocoderules), simply restart kilo-cli to pick up the new config. No manual migration or conversion needed.

Source Locations Copy Chapter

The migrator reads rules from these locations:

Project Rules Copy Section

Global Rules Copy Section

File Mapping Copy Chapter

AGENTS.md Compatibility Copy Chapter

AGENTS.md is loaded natively by Opencode - no migration needed. Opencode automatically loads:

• AGENTS.md in project root
• CLAUDE.md in project root
• ~/.config/kilo/AGENTS.md (global)

Not Migrated Copy Chapter

The following are not migrated:

• .roorules - Roo-specific rules
• .clinerules - Cline-specific rules

Only Kilocode-specific files (.kilocoderules, .kilocode/rules/) are migrated.

Mode-Specific Rules Copy Chapter

Mode-specific rules (e.g., .kilocoderules-code, .kilocode/rules-architect/) are included by default. All mode-specific rules are loaded regardless of the current mode.

Warnings Copy Chapter

The migrator generates warnings for:

• Legacy files: When .kilocoderules is found, a warning suggests migrating to .kilocode/rules/ directory structure

Example Copy Chapter

Before (Kilocode) Copy Section

project/
├── .kilocoderules           # Legacy rules
├── .kilocoderules-code      # Code-mode specific
└── .kilocode/
    └── rules/
        ├── coding.md        # Coding standards
        └── testing.md       # Testing guidelines

After (Opencode Config) Copy Section

{
  "instructions": [
    "/path/to/project/.kilocode/rules/coding.md",
    "/path/to/project/.kilocode/rules/testing.md",
    "/path/to/project/.kilocoderules",
    "/path/to/project/.kilocoderules-code"
  ]
}

Troubleshooting Copy Chapter

Rules not appearing Copy Section

1. Check the file exists at the expected location
2. Ensure markdown files have .md extension
3. Restart kilo-cli to pick up changes

Duplicate rules Copy Section

The mergeConfigConcatArrays function automatically deduplicates the instructions array using Array.from(new Set([...])).

Related Files Copy Chapter

• rules-migrator.ts - Core migration logic
• config-injector.ts - Config building and injection
• modes-migration.md - Modes migration documentation

--- METRICS ---

• Files Extracted: 53
• Estimated Token Budget: ~29105 tokens
• Canonical Reference: https://codewiki.google/github.com/Kilo-Org/kilocode