From c4898d78d164638628836d9186661dadccaec779 Mon Sep 17 00:00:00 2001 From: Thomas Brugman Date: Sun, 15 Mar 2026 10:25:52 +0100 Subject: [PATCH 001/308] fix: always deny task permission in subagent sessions --- packages/opencode/src/tool/task.ts | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/packages/opencode/src/tool/task.ts b/packages/opencode/src/tool/task.ts index 8c8cf827aba..dacbdaca5f7 100644 --- a/packages/opencode/src/tool/task.ts +++ b/packages/opencode/src/tool/task.ts @@ -61,8 +61,6 @@ export const TaskTool = Tool.define("task", async (ctx) => { const agent = await Agent.get(params.subagent_type) if (!agent) throw new Error(`Unknown agent type: ${params.subagent_type} is not a valid agent type`) - const hasTaskPermission = agent.permission.some((rule) => rule.permission === "task") - const session = await iife(async () => { if (params.task_id) { const found = await Session.get(params.task_id).catch(() => {}) @@ -83,15 +81,11 @@ export const TaskTool = Tool.define("task", async (ctx) => { pattern: "*", action: "deny", }, - ...(hasTaskPermission - ? [] - : [ - { - permission: "task" as const, - pattern: "*" as const, - action: "deny" as const, - }, - ]), + { + permission: "task" as const, + pattern: "*" as const, + action: "deny" as const, + }, ...(config.experimental?.primary_tools?.map((t) => ({ pattern: "*", action: "allow" as const, @@ -136,7 +130,7 @@ export const TaskTool = Tool.define("task", async (ctx) => { tools: { todowrite: false, todoread: false, - ...(hasTaskPermission ? {} : { task: false }), + task: false, ...Object.fromEntries((config.experimental?.primary_tools ?? []).map((t) => [t, false])), }, parts: promptParts, From 4ee4d49d92f125a45bfb4ca026a3ed61bb7d9efb Mon Sep 17 00:00:00 2001 From: Thomas Brugman Date: Sun, 15 Mar 2026 10:32:46 +0100 Subject: [PATCH 002/308] fix: deny task in subagent sessions unless agent explicitly allows it --- packages/opencode/src/tool/task.ts | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/packages/opencode/src/tool/task.ts b/packages/opencode/src/tool/task.ts index dacbdaca5f7..a76eb9f756b 100644 --- a/packages/opencode/src/tool/task.ts +++ b/packages/opencode/src/tool/task.ts @@ -61,6 +61,8 @@ export const TaskTool = Tool.define("task", async (ctx) => { const agent = await Agent.get(params.subagent_type) if (!agent) throw new Error(`Unknown agent type: ${params.subagent_type} is not a valid agent type`) + const allowsTask = agent.permission.some((rule) => rule.permission === "task" && rule.action === "allow") + const session = await iife(async () => { if (params.task_id) { const found = await Session.get(params.task_id).catch(() => {}) @@ -81,11 +83,15 @@ export const TaskTool = Tool.define("task", async (ctx) => { pattern: "*", action: "deny", }, - { - permission: "task" as const, - pattern: "*" as const, - action: "deny" as const, - }, + ...(allowsTask + ? [] + : [ + { + permission: "task" as const, + pattern: "*" as const, + action: "deny" as const, + }, + ]), ...(config.experimental?.primary_tools?.map((t) => ({ pattern: "*", action: "allow" as const, @@ -130,7 +136,7 @@ export const TaskTool = Tool.define("task", async (ctx) => { tools: { todowrite: false, todoread: false, - task: false, + ...(allowsTask ? {} : { task: false }), ...Object.fromEntries((config.experimental?.primary_tools ?? []).map((t) => [t, false])), }, parts: promptParts, From 175562c34ff30f88230474b762c2b50dd47fae1f Mon Sep 17 00:00:00 2001 From: Alex Gold Date: Sun, 15 Mar 2026 08:41:37 -0400 Subject: [PATCH 003/308] Answer some questions about KiloClaw --- packages/kilo-docs/pages/kiloclaw/dashboard.md | 4 ++++ .../kilo-docs/pages/kiloclaw/troubleshooting.md | 14 ++++++++++++++ 2 files changed, 18 insertions(+) diff --git a/packages/kilo-docs/pages/kiloclaw/dashboard.md b/packages/kilo-docs/pages/kiloclaw/dashboard.md index 9904f07bc74..246e7682778 100644 --- a/packages/kilo-docs/pages/kiloclaw/dashboard.md +++ b/packages/kilo-docs/pages/kiloclaw/dashboard.md @@ -74,6 +74,10 @@ If the gateway crashes, it's automatically restarted. The machine itself can be Gateway process info is only available when the machine is running. {% /callout %} +## Instance Specs + +The specs of your instance, including number of CPUs, memory, and storage, are visibile at the top right of the instance controls section. + ## Settings ### Changing the Model diff --git a/packages/kilo-docs/pages/kiloclaw/troubleshooting.md b/packages/kilo-docs/pages/kiloclaw/troubleshooting.md index 4d158a5b869..7129bb19652 100644 --- a/packages/kilo-docs/pages/kiloclaw/troubleshooting.md +++ b/packages/kilo-docs/pages/kiloclaw/troubleshooting.md @@ -73,6 +73,20 @@ Direct filesystem access is not available at this time. You can interact with fi For security reasons, SSH access is currently disabled for all KiloClaw instances. Our primary goal is to provide a secure environment for all users, and restricting direct SSH access is one of the many measures we take to ensure the platform remains safe and protected for everyone. +### Can I install tailscale on my KiloClaw instance? + +Not at this time. + +### Can I update the version of Node on my instance? + +Not at this time. + +### Can I upgrade the version of OpenClaw myself? + +We do not recommend upgrading the version of OpenClaw yourself. Different versions of OpenClaw may have different requirements and dependencies, and manually upgrading could potentially lead to compatibility issues or break your setup. + +If you upgrade to a version of OpenClaw that breaks your setup, you can use the version pinning dialog at the bottom of the settings tab on the [KiloClaw Dashboard](https://app.kilo.ai/claw) to revert to an earlier version of OpenClaw. + ### How can I update my OpenClaw? Do **not** click **Update Now** inside the OpenClaw Control UI — this is not supported for KiloClaw instances and may break your setup. From 876e439726585c83c02a8353b02ef0d8d6c2965c Mon Sep 17 00:00:00 2001 From: Alex Gold Date: Sun, 15 Mar 2026 08:46:30 -0400 Subject: [PATCH 004/308] simplify upgrade answer --- packages/kilo-docs/pages/kiloclaw/troubleshooting.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/packages/kilo-docs/pages/kiloclaw/troubleshooting.md b/packages/kilo-docs/pages/kiloclaw/troubleshooting.md index 7129bb19652..ab96736a308 100644 --- a/packages/kilo-docs/pages/kiloclaw/troubleshooting.md +++ b/packages/kilo-docs/pages/kiloclaw/troubleshooting.md @@ -81,17 +81,11 @@ Not at this time. Not at this time. -### Can I upgrade the version of OpenClaw myself? +### How do I upgrade the OpenClaw version? -We do not recommend upgrading the version of OpenClaw yourself. Different versions of OpenClaw may have different requirements and dependencies, and manually upgrading could potentially lead to compatibility issues or break your setup. +Use **Upgrade & Redeploy** from the [KiloClaw Dashboard](https://app.kilo.ai/claw). Do **not** click **Update Now** inside the OpenClaw Control UI — this is not supported for KiloClaw instances and may break your setup. -If you upgrade to a version of OpenClaw that breaks your setup, you can use the version pinning dialog at the bottom of the settings tab on the [KiloClaw Dashboard](https://app.kilo.ai/claw) to revert to an earlier version of OpenClaw. - -### How can I update my OpenClaw? - -Do **not** click **Update Now** inside the OpenClaw Control UI — this is not supported for KiloClaw instances and may break your setup. - -Updates are managed by the KiloClaw platform team to ensure stability. When a new version is available, it will be announced in the **Changelog** on your dashboard. To apply the update, click **Upgrade & Redeploy** from the [KiloClaw Dashboard](/docs/kiloclaw/dashboard#redeploy). +When a new version is available, it will be announced in the **Changelog** on your dashboard. If you need to roll back, use the [version pinning](/docs/kiloclaw/version-pinning) dialog in the Settings tab. ## Architecture Notes From 4560c48aa32a0a325c38a504e177b32530db9206 Mon Sep 17 00:00:00 2001 From: Alex Gold Date: Sun, 15 Mar 2026 08:50:43 -0400 Subject: [PATCH 005/308] clarify --- packages/kilo-docs/pages/kiloclaw/troubleshooting.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/packages/kilo-docs/pages/kiloclaw/troubleshooting.md b/packages/kilo-docs/pages/kiloclaw/troubleshooting.md index ab96736a308..73f2147288c 100644 --- a/packages/kilo-docs/pages/kiloclaw/troubleshooting.md +++ b/packages/kilo-docs/pages/kiloclaw/troubleshooting.md @@ -81,11 +81,13 @@ Not at this time. Not at this time. -### How do I upgrade the OpenClaw version? +### How do I upgrade the OpenClaw version? Can I upgrade it myself? -Use **Upgrade & Redeploy** from the [KiloClaw Dashboard](https://app.kilo.ai/claw). Do **not** click **Update Now** inside the OpenClaw Control UI — this is not supported for KiloClaw instances and may break your setup. +Updates are managed by the KiloClaw platform team to ensure stability and dependency availability. When a new version is available, it will be announced in the **Changelog** on your dashboard. -When a new version is available, it will be announced in the **Changelog** on your dashboard. If you need to roll back, use the [version pinning](/docs/kiloclaw/version-pinning) dialog in the Settings tab. +To apply the update, click **Upgrade & Redeploy** from the [KiloClaw Dashboard](https://app.kilo.ai/claw). Do **not** click **Update Now** inside the OpenClaw Control UI — this is not supported for KiloClaw instances and may break your setup. + +If you need to roll back, use the [version pinning](/docs/kiloclaw/version-pinning) dialog in the Settings tab. ## Architecture Notes From ebeb463ab076ddd3259ae2cb645e1c3ea1df8cfb Mon Sep 17 00:00:00 2001 From: Alex Gold Date: Mon, 16 Mar 2026 09:09:03 -0400 Subject: [PATCH 006/308] Update packages/kilo-docs/pages/kiloclaw/dashboard.md Co-authored-by: kilo-code-bot[bot] <240665456+kilo-code-bot[bot]@users.noreply.github.com> --- packages/kilo-docs/pages/kiloclaw/dashboard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/kilo-docs/pages/kiloclaw/dashboard.md b/packages/kilo-docs/pages/kiloclaw/dashboard.md index 246e7682778..9e75225fdd0 100644 --- a/packages/kilo-docs/pages/kiloclaw/dashboard.md +++ b/packages/kilo-docs/pages/kiloclaw/dashboard.md @@ -76,7 +76,7 @@ Gateway process info is only available when the machine is running. ## Instance Specs -The specs of your instance, including number of CPUs, memory, and storage, are visibile at the top right of the instance controls section. +The specs of your instance, including number of CPUs, memory, and storage, are visible at the top right of the instance controls section. ## Settings From f59a274d8a5d572a9ea6d2a7720ce0df44a74eff Mon Sep 17 00:00:00 2001 From: theQuert Date: Wed, 18 Mar 2026 12:04:01 +0800 Subject: [PATCH 007/308] feat: add Apertis provider to VS Code legacy migration mapping Move Apertis from UNSUPPORTED_PROVIDERS to PROVIDER_MAP with proper field mappings (apertisApiKey, apertisModelId, apertisBaseUrl) so legacy VS Code extension settings migrate correctly to the new CLI backend. --- .../kilo-vscode/src/legacy-migration/provider-mapping.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/packages/kilo-vscode/src/legacy-migration/provider-mapping.ts b/packages/kilo-vscode/src/legacy-migration/provider-mapping.ts index 817cdeb9775..53de6773af5 100644 --- a/packages/kilo-vscode/src/legacy-migration/provider-mapping.ts +++ b/packages/kilo-vscode/src/legacy-migration/provider-mapping.ts @@ -240,6 +240,13 @@ export const PROVIDER_MAP: Record = { key: "syntheticApiKey", name: "Synthetic", }, + apertis: { + id: "apertis", + key: "apertisApiKey", + name: "Apertis", + modelField: "apertisModelId", + urlField: "apertisBaseUrl", + }, } /** Providers that have no equivalent in the new CLI backend */ @@ -256,7 +263,6 @@ export const UNSUPPORTED_PROVIDERS = new Set([ "nano-gpt", "poe", "aihubmix", - "apertis", "zenmux", ]) From 1fc0e644dd103805387d4f192f9bf497ff5c0f82 Mon Sep 17 00:00:00 2001 From: Josh Holmer Date: Mon, 16 Mar 2026 20:15:56 -0400 Subject: [PATCH 008/308] fix(cli): use configured Code model when implementing a plan --- .../opencode/src/kilocode/plan-followup.ts | 45 +++- .../test/kilocode/plan-followup.test.ts | 209 ++++++++++++++++-- 2 files changed, 237 insertions(+), 17 deletions(-) diff --git a/packages/opencode/src/kilocode/plan-followup.ts b/packages/opencode/src/kilocode/plan-followup.ts index ab11e366f0c..a95f9a69c85 100644 --- a/packages/opencode/src/kilocode/plan-followup.ts +++ b/packages/opencode/src/kilocode/plan-followup.ts @@ -2,6 +2,8 @@ import { Telemetry } from "@kilocode/kilo-telemetry" import { Agent } from "@/agent/agent" import { Bus } from "@/bus" import { TuiEvent } from "@/cli/cmd/tui/event" +import { Flag } from "@/flag/flag" +import { Global } from "@/global" import { Identifier } from "@/id/id" import { Provider } from "@/provider/provider" import { Question } from "@/question" @@ -10,6 +12,8 @@ import { LLM } from "@/session/llm" import { MessageV2 } from "@/session/message-v2" import { Todo } from "@/session/todo" import { Log } from "@/util/log" +import fs from "fs/promises" +import path from "path" function toText(item: MessageV2.WithParts): string { return item.parts @@ -111,6 +115,41 @@ export namespace PlanFollowup { export const ANSWER_NEW_SESSION = "Start new session" export const ANSWER_CONTINUE = "Continue here" + async function resolveCodeModel(model: MessageV2.User["model"]) { + const saved = + Flag.KILO_CLIENT === "cli" + ? await fs + .readFile(path.join(Global.Path.state, "model.json"), "utf-8") + .then( + (item) => + JSON.parse(item) as { + model?: Record< + string, + { + providerID: string + modelID: string + } + > + }, + ) + .then((item) => item.model?.code) + .catch(() => undefined) + : undefined + if (saved) { + const match = await Provider.getModel(saved.providerID, saved.modelID).catch(() => undefined) + if (match) { + return { + providerID: saved.providerID, + modelID: saved.modelID, + } + } + } + + const agent = await Agent.get("code") + if (agent?.model) return agent.model + return model + } + async function resolvePlan(input: { assistant?: MessageV2.WithParts messages: MessageV2.WithParts[] @@ -211,6 +250,7 @@ export namespace PlanFollowup { model: MessageV2.User["model"] abort?: AbortSignal }) { + const model = await resolveCodeModel(input.model) const [handover, todos] = await Promise.all([ generateHandover({ messages: input.messages, model: input.model, abort: input.abort }), Todo.get(input.sessionID), @@ -231,7 +271,7 @@ export namespace PlanFollowup { await inject({ sessionID: next.id, agent: "code", - model: input.model, + model, text: sections.join("\n\n"), synthetic: false, }) @@ -289,10 +329,11 @@ export namespace PlanFollowup { if (answer === ANSWER_CONTINUE) { Telemetry.trackPlanFollowup(input.sessionID, "continue") + const model = await resolveCodeModel(user.model) await inject({ sessionID: input.sessionID, agent: "code", - model: user.model, + model, text: "Implement the plan above.", }) return "continue" diff --git a/packages/opencode/test/kilocode/plan-followup.test.ts b/packages/opencode/test/kilocode/plan-followup.test.ts index 593b258906b..badc8c42ced 100644 --- a/packages/opencode/test/kilocode/plan-followup.test.ts +++ b/packages/opencode/test/kilocode/plan-followup.test.ts @@ -12,19 +12,42 @@ import { LLM } from "../../src/session/llm" import { MessageV2 } from "../../src/session/message-v2" import { SessionPrompt } from "../../src/session/prompt" import { Todo } from "../../src/session/todo" +import { Global } from "../../src/global" import { Log } from "../../src/util/log" +import path from "path" +import fs from "fs/promises" import { tmpdir } from "../fixture/fixture" Log.init({ print: false }) +process.env.KILO_CLIENT = "cli" const model = { providerID: "openai", modelID: "gpt-4", } +const saved = { + providerID: "openai", + modelID: "gpt-5", +} + +const config = { + providerID: "openai", + modelID: "gpt-4.1", +} + +const statePath = path.join(Global.Path.state, "model.json") + async function withInstance(fn: () => Promise) { await using tmp = await tmpdir({ git: true }) - await Instance.provide({ directory: tmp.path, fn }) + await fs.rm(statePath, { force: true }).catch(() => {}) + await Instance.provide({ + directory: tmp.path, + fn: async () => { + await fs.rm(statePath, { force: true }).catch(() => {}) + await fn() + }, + }) } async function seed(input: { @@ -126,6 +149,20 @@ async function sessions() { return Array.fromAsync(Session.list()) } +async function waitQuestion(sessionID: string) { + for (let i = 0; i < 50; i++) { + const list = await Question.list() + const item = list.find((q) => q.sessionID === sessionID) + if (item) return item + await Bun.sleep(10) + } +} + +async function writeState(input: { model?: Record }) { + await fs.mkdir(Global.Path.state, { recursive: true }) + await fs.writeFile(statePath, JSON.stringify(input)) +} + const fakeAgent: Agent.Info = { name: "compaction", mode: "subagent", @@ -171,15 +208,33 @@ describe("plan follow-up", () => { abort: AbortSignal.any([]), }) - const list = await Question.list() - expect(list).toHaveLength(1) - await Question.reject(list[0].id) + const item = await waitQuestion(seeded.sessionID) + expect(item).toBeDefined() + if (!item) return + await Question.reject(item.id) await expect(pending).resolves.toBe("break") })) test("ask - returns continue and creates code message on Continue here", () => withInstance(async () => { + const get = spyOn(Agent, "get").mockImplementation(async (name: string) => { + if (name === "code") { + return { + name: "code", + mode: "primary", + permission: [], + options: {}, + model: saved, + } as any + } + return undefined as any + }) + using _ = { + [Symbol.dispose]() { + get.mockRestore() + }, + } const seeded = await seed({ text: "1. Build\n2. Test" }) const pending = PlanFollowup.ask({ sessionID: seeded.sessionID, @@ -187,9 +242,11 @@ describe("plan follow-up", () => { abort: AbortSignal.any([]), }) - const list = await Question.list() + const item = await waitQuestion(seeded.sessionID) + expect(item).toBeDefined() + if (!item) return await Question.reply({ - requestID: list[0].id, + requestID: item.id, answers: [[PlanFollowup.ANSWER_CONTINUE]], }) @@ -199,6 +256,7 @@ describe("plan follow-up", () => { expect(user?.info.role).toBe("user") if (!user || user.info.role !== "user") return expect(user.info.agent).toBe("code") + expect(user.info.model).toEqual(saved) const part = user.parts.find((item) => item.type === "text") expect(part?.type).toBe("text") @@ -216,8 +274,11 @@ describe("plan follow-up", () => { abort: AbortSignal.any([]), }) + const item = await waitQuestion(seeded.sessionID) + expect(item).toBeDefined() + if (!item) return await Question.reply({ - requestID: (await Question.list())[0].id, + requestID: item.id, answers: [["Add rollback support too"]], }) @@ -237,6 +298,24 @@ describe("plan follow-up", () => { test("ask - creates a new session on Start new session with handover and todos", () => withInstance(async () => { + const get = spyOn(Agent, "get").mockImplementation(async (name: string) => { + if (name === "code") { + return { + name: "code", + mode: "primary", + permission: [], + options: {}, + model: saved, + } as any + } + if (name === "compaction") return fakeAgent as any + return undefined as any + }) + using _file = { + [Symbol.dispose]() { + get.mockRestore() + }, + } const loop = spyOn(SessionPrompt, "loop").mockResolvedValue({ info: { id: "msg_test", @@ -268,9 +347,19 @@ describe("plan follow-up", () => { }, parts: [], }) - using _mocks = mockHandoverDeps( - "## Discoveries\n\nFound REST endpoints in src/api.ts\n\n## Relevant Files\n\n- src/api.ts: REST endpoints\n- src/db.ts: Database layer", - ) + const modelSpy = spyOn(Provider, "getModel").mockResolvedValue(fakeModel) + const llmSpy = spyOn(LLM, "stream").mockResolvedValue({ + text: Promise.resolve( + "## Discoveries\n\nFound REST endpoints in src/api.ts\n\n## Relevant Files\n\n- src/api.ts: REST endpoints\n- src/db.ts: Database layer", + ), + } as any) + using _mocks = { + llmSpy, + [Symbol.dispose]() { + modelSpy.mockRestore() + llmSpy.mockRestore() + }, + } using _loop = { [Symbol.dispose]() { loop.mockRestore() @@ -300,8 +389,11 @@ describe("plan follow-up", () => { abort: AbortSignal.any([]), }) + const item = await waitQuestion(seeded.sessionID) + expect(item).toBeDefined() + if (!item) return await Question.reply({ - requestID: (await Question.list())[0].id, + requestID: item.id, answers: [[PlanFollowup.ANSWER_NEW_SESSION]], }) @@ -323,6 +415,7 @@ describe("plan follow-up", () => { expect(user?.info.role).toBe("user") if (!user || user.info.role !== "user") throw new Error("expected seeded user message") expect(user.info.agent).toBe("code") + expect(user.info.model).toEqual(saved) const part = user.parts.find((item) => item.type === "text") expect(part?.type).toBe("text") @@ -344,6 +437,85 @@ describe("plan follow-up", () => { SessionPrompt.cancel(newSessionID) })) + test("ask - falls back to configured code model when saved CLI code model is unavailable", () => + withInstance(async () => { + await writeState({ model: { code: { providerID: "missing", modelID: "ghost" } } }) + const get = spyOn(Agent, "get").mockImplementation(async (name: string) => { + if (name === "code") { + return { + name: "code", + mode: "primary", + permission: [], + options: {}, + model: config, + } as any + } + return undefined as any + }) + using _ = { + [Symbol.dispose]() { + get.mockRestore() + }, + } + const seeded = await seed({ text: "1. Build\n2. Test" }) + const pending = PlanFollowup.ask({ + sessionID: seeded.sessionID, + messages: seeded.messages, + abort: AbortSignal.any([]), + }) + + const item = await waitQuestion(seeded.sessionID) + expect(item).toBeDefined() + if (!item) return + await Question.reply({ + requestID: item.id, + answers: [[PlanFollowup.ANSWER_CONTINUE]], + }) + + await expect(pending).resolves.toBe("continue") + + const user = await latestUser(seeded.sessionID) + expect(user?.info.role).toBe("user") + if (!user || user.info.role !== "user") return + expect(user.info.agent).toBe("code") + expect(user.info.model).toEqual(config) + })) + + test("ask - falls back to planning model when no saved or configured code model exists", () => + withInstance(async () => { + const get = spyOn(Agent, "get").mockImplementation(async (name: string) => { + if (name === "code") return undefined as any + return undefined as any + }) + using _ = { + [Symbol.dispose]() { + get.mockRestore() + }, + } + const seeded = await seed({ text: "1. Build\n2. Test" }) + const pending = PlanFollowup.ask({ + sessionID: seeded.sessionID, + messages: seeded.messages, + abort: AbortSignal.any([]), + }) + + const item = await waitQuestion(seeded.sessionID) + expect(item).toBeDefined() + if (!item) return + await Question.reply({ + requestID: item.id, + answers: [[PlanFollowup.ANSWER_CONTINUE]], + }) + + await expect(pending).resolves.toBe("continue") + + const user = await latestUser(seeded.sessionID) + expect(user?.info.role).toBe("user") + if (!user || user.info.role !== "user") return + expect(user.info.agent).toBe("code") + expect(user.info.model).toEqual(model) + })) + test("ask - new session omits handover section when LLM returns empty", () => withInstance(async () => { const loop = spyOn(SessionPrompt, "loop").mockResolvedValue({ @@ -387,8 +559,11 @@ describe("plan follow-up", () => { abort: AbortSignal.any([]), }) + const item = await waitQuestion(seeded.sessionID) + expect(item).toBeDefined() + if (!item) return await Question.reply({ - requestID: (await Question.list())[0].id, + requestID: item.id, answers: [[PlanFollowup.ANSWER_NEW_SESSION]], }) @@ -444,8 +619,9 @@ describe("plan follow-up", () => { abort: abort.signal, }) - const list = await Question.list() - expect(list).toHaveLength(1) + const item = await waitQuestion(seeded.sessionID) + expect(item).toBeDefined() + if (!item) return abort.abort() @@ -462,8 +638,11 @@ describe("plan follow-up", () => { abort: AbortSignal.any([]), }) + const item = await waitQuestion(seeded.sessionID) + expect(item).toBeDefined() + if (!item) return await Question.reply({ - requestID: (await Question.list())[0].id, + requestID: item.id, answers: [[" "]], }) From 040284034a4dbec78c917ad54e6dd617f10f2867 Mon Sep 17 00:00:00 2001 From: Josh Holmer Date: Mon, 16 Mar 2026 20:46:45 -0400 Subject: [PATCH 009/308] fix(cli): preserve selected variant as well --- .../opencode/src/kilocode/plan-followup.ts | 69 ++++++++---- .../test/kilocode/plan-followup.test.ts | 102 +++++++++++++++++- 2 files changed, 148 insertions(+), 23 deletions(-) diff --git a/packages/opencode/src/kilocode/plan-followup.ts b/packages/opencode/src/kilocode/plan-followup.ts index a95f9a69c85..4dc71b89411 100644 --- a/packages/opencode/src/kilocode/plan-followup.ts +++ b/packages/opencode/src/kilocode/plan-followup.ts @@ -115,39 +115,55 @@ export namespace PlanFollowup { export const ANSWER_NEW_SESSION = "Start new session" export const ANSWER_CONTINUE = "Continue here" - async function resolveCodeModel(model: MessageV2.User["model"]) { - const saved = + function resolveVariant(input: { value: string | undefined; model: Provider.Model | undefined }) { + if (!input.value) return undefined + if (!input.model?.variants?.[input.value]) return undefined + return input.value + } + + async function resolveCodeModel(input: Pick) { + const state = Flag.KILO_CLIENT === "cli" ? await fs .readFile(path.join(Global.Path.state, "model.json"), "utf-8") .then( (item) => JSON.parse(item) as { - model?: Record< - string, - { - providerID: string - modelID: string - } - > + model?: Record + variant?: Record }, ) - .then((item) => item.model?.code) .catch(() => undefined) : undefined + const saved = state?.model?.code if (saved) { - const match = await Provider.getModel(saved.providerID, saved.modelID).catch(() => undefined) - if (match) { + const full = await Provider.getModel(saved.providerID, saved.modelID).catch(() => undefined) + if (full) { + const key = `${saved.providerID}/${saved.modelID}` return { - providerID: saved.providerID, - modelID: saved.modelID, + model: saved, + variant: resolveVariant({ + value: state?.variant?.[key], + model: full, + }), } } } const agent = await Agent.get("code") - if (agent?.model) return agent.model - return model + if (agent?.model) { + const full = agent.variant + ? await Provider.getModel(agent.model.providerID, agent.model.modelID).catch(() => undefined) + : undefined + return { + model: agent.model, + variant: resolveVariant({ + value: agent.variant, + model: full, + }), + } + } + return input } async function resolvePlan(input: { @@ -180,6 +196,7 @@ export namespace PlanFollowup { sessionID: string agent: string model: MessageV2.User["model"] + variant?: MessageV2.User["variant"] text: string synthetic?: boolean }) { @@ -192,6 +209,7 @@ export namespace PlanFollowup { }, agent: input.agent, model: input.model, + variant: input.variant, } await Session.updateMessage(msg) await Session.updatePart({ @@ -248,9 +266,13 @@ export namespace PlanFollowup { plan: string messages: MessageV2.WithParts[] model: MessageV2.User["model"] + variant?: MessageV2.User["variant"] abort?: AbortSignal }) { - const model = await resolveCodeModel(input.model) + const code = await resolveCodeModel({ + model: input.model, + variant: input.variant, + }) const [handover, todos] = await Promise.all([ generateHandover({ messages: input.messages, model: input.model, abort: input.abort }), Todo.get(input.sessionID), @@ -271,7 +293,8 @@ export namespace PlanFollowup { await inject({ sessionID: next.id, agent: "code", - model, + model: code.model, + variant: code.variant, text: sections.join("\n\n"), synthetic: false, }) @@ -322,6 +345,7 @@ export namespace PlanFollowup { plan, messages: input.messages, model: user.model, + variant: user.variant, abort: input.abort, }) return "break" @@ -329,11 +353,15 @@ export namespace PlanFollowup { if (answer === ANSWER_CONTINUE) { Telemetry.trackPlanFollowup(input.sessionID, "continue") - const model = await resolveCodeModel(user.model) + const code = await resolveCodeModel({ + model: user.model, + variant: user.variant, + }) await inject({ sessionID: input.sessionID, agent: "code", - model, + model: code.model, + variant: code.variant, text: "Implement the plan above.", }) return "continue" @@ -344,6 +372,7 @@ export namespace PlanFollowup { sessionID: input.sessionID, agent: "plan", model: user.model, + variant: user.variant, text: answer, }) return "continue" diff --git a/packages/opencode/test/kilocode/plan-followup.test.ts b/packages/opencode/test/kilocode/plan-followup.test.ts index badc8c42ced..bc19cdbc5ce 100644 --- a/packages/opencode/test/kilocode/plan-followup.test.ts +++ b/packages/opencode/test/kilocode/plan-followup.test.ts @@ -31,12 +31,18 @@ const saved = { modelID: "gpt-5", } +const savedVar = "high" + const config = { providerID: "openai", modelID: "gpt-4.1", } +const configVar = "max" +const planVar = "medium" + const statePath = path.join(Global.Path.state, "model.json") +const savedKey = `${saved.providerID}/${saved.modelID}` async function withInstance(fn: () => Promise) { await using tmp = await tmpdir({ git: true }) @@ -52,6 +58,7 @@ async function withInstance(fn: () => Promise) { async function seed(input: { text: string + variant?: string tools?: Array<{ tool: string; input: Record; output: string }> }) { const session = await Session.create({}) @@ -64,6 +71,7 @@ async function seed(input: { }, agent: "plan", model, + variant: input.variant, }) await Session.updatePart({ id: Identifier.ascending("part"), @@ -158,7 +166,10 @@ async function waitQuestion(sessionID: string) { } } -async function writeState(input: { model?: Record }) { +async function writeState(input: { + model?: Record + variant?: Record +}) { await fs.mkdir(Global.Path.state, { recursive: true }) await fs.writeFile(statePath, JSON.stringify(input)) } @@ -178,6 +189,19 @@ const fakeModel = { capabilities: {}, } as Provider.Model +function full(input: { providerID: string; modelID: string }, vars: string[]) { + return { + ...fakeModel, + id: input.modelID, + providerID: input.providerID, + variants: Object.fromEntries(vars.map((item) => [item, {}])), + } as Provider.Model +} + +const savedFull = full(saved, [savedVar, "low"]) +const savedConfigFull = full(saved, [configVar, "low"]) +const configFull = full(config, [configVar, "low"]) + function mockHandoverDeps(text: string, opts?: { agent?: Agent.Info | null }) { const agentSpy = spyOn(Agent, "get").mockResolvedValue( (opts?.agent === null ? undefined : (opts?.agent ?? fakeAgent)) as any, @@ -226,13 +250,16 @@ describe("plan follow-up", () => { permission: [], options: {}, model: saved, + variant: configVar, } as any } return undefined as any }) + const modelSpy = spyOn(Provider, "getModel").mockResolvedValue(savedConfigFull) using _ = { [Symbol.dispose]() { get.mockRestore() + modelSpy.mockRestore() }, } const seeded = await seed({ text: "1. Build\n2. Test" }) @@ -257,6 +284,7 @@ describe("plan follow-up", () => { if (!user || user.info.role !== "user") return expect(user.info.agent).toBe("code") expect(user.info.model).toEqual(saved) + expect(user.info.variant).toBe(configVar) const part = user.parts.find((item) => item.type === "text") expect(part?.type).toBe("text") @@ -306,6 +334,7 @@ describe("plan follow-up", () => { permission: [], options: {}, model: saved, + variant: configVar, } as any } if (name === "compaction") return fakeAgent as any @@ -347,7 +376,10 @@ describe("plan follow-up", () => { }, parts: [], }) - const modelSpy = spyOn(Provider, "getModel").mockResolvedValue(fakeModel) + const modelSpy = spyOn(Provider, "getModel").mockImplementation(async (providerID: string, modelID: string) => { + if (providerID === saved.providerID && modelID === saved.modelID) return savedConfigFull + return fakeModel + }) const llmSpy = spyOn(LLM, "stream").mockResolvedValue({ text: Promise.resolve( "## Discoveries\n\nFound REST endpoints in src/api.ts\n\n## Relevant Files\n\n- src/api.ts: REST endpoints\n- src/db.ts: Database layer", @@ -416,6 +448,7 @@ describe("plan follow-up", () => { if (!user || user.info.role !== "user") throw new Error("expected seeded user message") expect(user.info.agent).toBe("code") expect(user.info.model).toEqual(saved) + expect(user.info.variant).toBe(configVar) const part = user.parts.find((item) => item.type === "text") expect(part?.type).toBe("text") @@ -437,6 +470,61 @@ describe("plan follow-up", () => { SessionPrompt.cancel(newSessionID) })) + test("ask - prefers saved code variant over configured code variant", () => + withInstance(async () => { + await writeState({ + model: { code: saved }, + variant: { [savedKey]: savedVar }, + }) + const get = spyOn(Agent, "get").mockImplementation(async (name: string) => { + if (name === "code") { + return { + name: "code", + mode: "primary", + permission: [], + options: {}, + model: config, + variant: configVar, + } as any + } + return undefined as any + }) + const modelSpy = spyOn(Provider, "getModel").mockImplementation(async (providerID: string, modelID: string) => { + if (providerID === saved.providerID && modelID === saved.modelID) return savedFull + if (providerID === config.providerID && modelID === config.modelID) return configFull + throw new Error(`unexpected model lookup ${providerID}/${modelID}`) + }) + using _ = { + [Symbol.dispose]() { + get.mockRestore() + modelSpy.mockRestore() + }, + } + const seeded = await seed({ text: "1. Build\n2. Test" }) + const pending = PlanFollowup.ask({ + sessionID: seeded.sessionID, + messages: seeded.messages, + abort: AbortSignal.any([]), + }) + + const item = await waitQuestion(seeded.sessionID) + expect(item).toBeDefined() + if (!item) return + await Question.reply({ + requestID: item.id, + answers: [[PlanFollowup.ANSWER_CONTINUE]], + }) + + await expect(pending).resolves.toBe("continue") + + const user = await latestUser(seeded.sessionID) + expect(user?.info.role).toBe("user") + if (!user || user.info.role !== "user") return + expect(user.info.agent).toBe("code") + expect(user.info.model).toEqual(saved) + expect(user.info.variant).toBe(savedVar) + })) + test("ask - falls back to configured code model when saved CLI code model is unavailable", () => withInstance(async () => { await writeState({ model: { code: { providerID: "missing", modelID: "ghost" } } }) @@ -448,13 +536,19 @@ describe("plan follow-up", () => { permission: [], options: {}, model: config, + variant: configVar, } as any } return undefined as any }) + const modelSpy = spyOn(Provider, "getModel").mockImplementation(async (providerID: string, modelID: string) => { + if (providerID === "missing" && modelID === "ghost") throw new Error("missing model") + return configFull + }) using _ = { [Symbol.dispose]() { get.mockRestore() + modelSpy.mockRestore() }, } const seeded = await seed({ text: "1. Build\n2. Test" }) @@ -479,6 +573,7 @@ describe("plan follow-up", () => { if (!user || user.info.role !== "user") return expect(user.info.agent).toBe("code") expect(user.info.model).toEqual(config) + expect(user.info.variant).toBe(configVar) })) test("ask - falls back to planning model when no saved or configured code model exists", () => @@ -492,7 +587,7 @@ describe("plan follow-up", () => { get.mockRestore() }, } - const seeded = await seed({ text: "1. Build\n2. Test" }) + const seeded = await seed({ text: "1. Build\n2. Test", variant: planVar }) const pending = PlanFollowup.ask({ sessionID: seeded.sessionID, messages: seeded.messages, @@ -514,6 +609,7 @@ describe("plan follow-up", () => { if (!user || user.info.role !== "user") return expect(user.info.agent).toBe("code") expect(user.info.model).toEqual(model) + expect(user.info.variant).toBe(planVar) })) test("ask - new session omits handover section when LLM returns empty", () => From b74d4b4481814f776ce1369aa4e1a589a6e4a484 Mon Sep 17 00:00:00 2001 From: Josh Holmer Date: Thu, 19 Mar 2026 10:47:05 -0400 Subject: [PATCH 010/308] fix(cli): improve agent handling --- .../opencode/src/kilocode/plan-followup.ts | 20 ++++++++++--------- .../test/kilocode/plan-followup.test.ts | 6 +++++- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/packages/opencode/src/kilocode/plan-followup.ts b/packages/opencode/src/kilocode/plan-followup.ts index 4dc71b89411..cc6408b6655 100644 --- a/packages/opencode/src/kilocode/plan-followup.ts +++ b/packages/opencode/src/kilocode/plan-followup.ts @@ -152,15 +152,17 @@ export namespace PlanFollowup { const agent = await Agent.get("code") if (agent?.model) { - const full = agent.variant - ? await Provider.getModel(agent.model.providerID, agent.model.modelID).catch(() => undefined) - : undefined - return { - model: agent.model, - variant: resolveVariant({ - value: agent.variant, - model: full, - }), + const full = await Provider.getModel(agent.model.providerID, agent.model.modelID).catch(() => undefined) + if (full) { + return { + model: agent.model, + variant: agent.variant + ? resolveVariant({ + value: agent.variant, + model: full, + }) + : undefined, + } } } return input diff --git a/packages/opencode/test/kilocode/plan-followup.test.ts b/packages/opencode/test/kilocode/plan-followup.test.ts index bc19cdbc5ce..5ee3475e539 100644 --- a/packages/opencode/test/kilocode/plan-followup.test.ts +++ b/packages/opencode/test/kilocode/plan-followup.test.ts @@ -51,7 +51,11 @@ async function withInstance(fn: () => Promise) { directory: tmp.path, fn: async () => { await fs.rm(statePath, { force: true }).catch(() => {}) - await fn() + try { + await fn() + } finally { + await fs.rm(statePath, { force: true }).catch(() => {}) + } }, }) } From 714e1f5acc349f4fa36cdc4f4d6997dbbd1f3b92 Mon Sep 17 00:00:00 2001 From: Christiaan Arnoldus Date: Mon, 23 Mar 2026 12:00:30 +0100 Subject: [PATCH 011/308] Fix merge --- .../kilo-vscode/src/legacy-migration/provider-mapping.ts | 5 ----- 1 file changed, 5 deletions(-) diff --git a/packages/kilo-vscode/src/legacy-migration/provider-mapping.ts b/packages/kilo-vscode/src/legacy-migration/provider-mapping.ts index 21bc0fd0a62..02c67a2357b 100644 --- a/packages/kilo-vscode/src/legacy-migration/provider-mapping.ts +++ b/packages/kilo-vscode/src/legacy-migration/provider-mapping.ts @@ -302,11 +302,6 @@ export const UNSUPPORTED_PROVIDERS = new Set([ "virtual-quota-fallback", "glama", "roo", - "nano-gpt", - "poe", - "aihubmix", - "zenmux", - "apertis", ]) /** Built-in default mode slugs that should not be migrated */ From b9fd360d925783b8124392dc0dc8d6e94183455e Mon Sep 17 00:00:00 2001 From: Mark IJbema Date: Mon, 23 Mar 2026 12:09:45 +0100 Subject: [PATCH 012/308] fix(vscode): remove beta label from welcome screen Remove the beta badge from the migration wizard's "What's New" screen, along with the associated CSS and i18n keys across all 17 locales. Closes #7182 --- .../src/components/migration/MigrationWizard.tsx | 5 +---- .../src/components/migration/migration.css | 12 ------------ packages/kilo-vscode/webview-ui/src/i18n/ar.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/br.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/bs.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/da.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/de.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/en.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/es.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/fr.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/ja.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/ko.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/nl.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/no.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/pl.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/ru.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/th.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/zh.ts | 1 - packages/kilo-vscode/webview-ui/src/i18n/zht.ts | 1 - 19 files changed, 1 insertion(+), 33 deletions(-) diff --git a/packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx b/packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx index 87a27fea7fb..1358048b543 100644 --- a/packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx +++ b/packages/kilo-vscode/webview-ui/src/components/migration/MigrationWizard.tsx @@ -477,10 +477,7 @@ const MigrationWizard: Component = (props) => {
-

- {language.t("migration.whatsNew.title")}{" "} - {language.t("migration.whatsNew.badge")} -

+

{language.t("migration.whatsNew.title")}

{language.t("migration.whatsNew.subtitle")}

diff --git a/packages/kilo-vscode/webview-ui/src/components/migration/migration.css b/packages/kilo-vscode/webview-ui/src/components/migration/migration.css index 5a18f5f1477..e4440e06796 100644 --- a/packages/kilo-vscode/webview-ui/src/components/migration/migration.css +++ b/packages/kilo-vscode/webview-ui/src/components/migration/migration.css @@ -67,18 +67,6 @@ width: 100%; } -.migration-wizard__badge { - font-size: 11px; - font-weight: 600; - letter-spacing: 0.5px; - padding: 3px 9px; - border-radius: 6px; - background: color-mix(in srgb, var(--vscode-button-background) 15%, transparent); - color: var(--vscode-button-background); - vertical-align: middle; - text-transform: uppercase; -} - .migration-wizard__header p { font-size: 13px; color: var(--vscode-descriptionForeground); diff --git a/packages/kilo-vscode/webview-ui/src/i18n/ar.ts b/packages/kilo-vscode/webview-ui/src/i18n/ar.ts index 243bce11b44..bd748c59563 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/ar.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/ar.ts @@ -1127,7 +1127,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "ما الجديد في Kilo Code", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "لقد أعدنا بناء الإضافة على أساس أسرع وأكثر كفاءة.", "migration.whatsNew.features.performance.title": "أداء أسرع للوكيل", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/br.ts b/packages/kilo-vscode/webview-ui/src/i18n/br.ts index f96f8903724..b45d6bda539 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/br.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/br.ts @@ -1150,7 +1150,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "O Que Há de Novo no Kilo Code", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "Reconstruímos a extensão sobre uma base mais rápida e eficiente.", "migration.whatsNew.features.performance.title": "Desempenho de Agente Mais Rápido", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/bs.ts b/packages/kilo-vscode/webview-ui/src/i18n/bs.ts index 8b42dea7a48..3b890673197 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/bs.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/bs.ts @@ -1149,7 +1149,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "Šta je novo u Kilo Code", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "Ponovo smo izgradili ekstenziju na bržem i efikasnijem temelju.", "migration.whatsNew.features.performance.title": "Brže performanse agenta", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/da.ts b/packages/kilo-vscode/webview-ui/src/i18n/da.ts index 411a5b69802..1a97d97c7fa 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/da.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/da.ts @@ -1141,7 +1141,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "Nyheder i Kilo Code", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "Vi har genopbygget udvidelsen på et hurtigere og mere effektivt fundament.", "migration.whatsNew.features.performance.title": "Hurtigere agentydelse", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/de.ts b/packages/kilo-vscode/webview-ui/src/i18n/de.ts index 4cc653db9b5..fe55ba18fd0 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/de.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/de.ts @@ -1162,7 +1162,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "Neuigkeiten in Kilo Code", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "Wir haben die Erweiterung auf einer schnelleren, effizienteren Grundlage neu aufgebaut.", "migration.whatsNew.features.performance.title": "Schnellere Agentenleistung", diff --git a/packages/kilo-vscode/webview-ui/src/i18n/en.ts b/packages/kilo-vscode/webview-ui/src/i18n/en.ts index 50f7404f527..f8f3ff5c907 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/en.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/en.ts @@ -1154,7 +1154,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "What's New in Kilo Code", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "We've rebuilt the extension on a faster, more efficient foundation.", "migration.whatsNew.features.performance.title": "Faster Agent Performance", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/es.ts b/packages/kilo-vscode/webview-ui/src/i18n/es.ts index 7e6f5e350ff..12835933b5a 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/es.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/es.ts @@ -1152,7 +1152,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "Novedades en Kilo Code", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "Hemos reconstruido la extensión sobre una base más rápida y eficiente.", "migration.whatsNew.features.performance.title": "Rendimiento de agente más rápido", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/fr.ts b/packages/kilo-vscode/webview-ui/src/i18n/fr.ts index dca7e206262..e2c33aaf51e 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/fr.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/fr.ts @@ -1164,7 +1164,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "Nouveautés de Kilo Code", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "Nous avons reconstruit l'extension sur une base plus rapide et plus efficace.", "migration.whatsNew.features.performance.title": "Performance accélérée de l'agent", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/ja.ts b/packages/kilo-vscode/webview-ui/src/i18n/ja.ts index 3a24e4cbd49..fa1364c4c1d 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/ja.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/ja.ts @@ -1139,7 +1139,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "Kilo Codeの新機能", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "より高速で効率的な基盤上に拡張機能を再構築しました。", "migration.whatsNew.features.performance.title": "高速なエージェントパフォーマンス", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/ko.ts b/packages/kilo-vscode/webview-ui/src/i18n/ko.ts index b8517874f0b..a662c8d9a22 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/ko.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/ko.ts @@ -1130,7 +1130,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "Kilo Code의 새로운 기능", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "더 빠르고 효율적인 기반 위에 확장 프로그램을 재구축했습니다.", "migration.whatsNew.features.performance.title": "더 빠른 에이전트 성능", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/nl.ts b/packages/kilo-vscode/webview-ui/src/i18n/nl.ts index 73605307b10..a214ee18010 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/nl.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/nl.ts @@ -1170,7 +1170,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "Wat is er Nieuw in Kilo Code", - "migration.whatsNew.badge": "Bèta", "migration.whatsNew.subtitle": "We hebben de extensie opnieuw opgebouwd op een snellere, efficiëntere basis.", "migration.whatsNew.features.performance.title": "Snellere Agent Prestaties", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/no.ts b/packages/kilo-vscode/webview-ui/src/i18n/no.ts index aa4bbd50ed2..d359eca1d64 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/no.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/no.ts @@ -1142,7 +1142,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "Hva er nytt i Kilo Code", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "Vi har bygget utvidelsen på nytt med et raskere og mer effektivt grunnlag.", "migration.whatsNew.features.performance.title": "Raskere agentytelse", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/pl.ts b/packages/kilo-vscode/webview-ui/src/i18n/pl.ts index c44109ed9f3..3b7ae37a87b 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/pl.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/pl.ts @@ -1147,7 +1147,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "Co nowego w Kilo Code", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "Przebudowaliśmy rozszerzenie na szybszym i wydajniejszym fundamencie.", "migration.whatsNew.features.performance.title": "Szybsza wydajność agenta", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/ru.ts b/packages/kilo-vscode/webview-ui/src/i18n/ru.ts index 854fdf704eb..7aae962324d 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/ru.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/ru.ts @@ -1146,7 +1146,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "Что нового в Kilo Code", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "Мы перестроили расширение на более быстрой и эффективной основе.", "migration.whatsNew.features.performance.title": "Более быстрая работа агента", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/th.ts b/packages/kilo-vscode/webview-ui/src/i18n/th.ts index 4365eaffe02..a0ed2c579c4 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/th.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/th.ts @@ -1126,7 +1126,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "มีอะไรใหม่ใน Kilo Code", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "เราได้สร้างส่วนขยายใหม่บนรากฐานที่เร็วและมีประสิทธิภาพมากขึ้น", "migration.whatsNew.features.performance.title": "ประสิทธิภาพเอเจนต์ที่เร็วขึ้น", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/zh.ts b/packages/kilo-vscode/webview-ui/src/i18n/zh.ts index 9a1ec2d5b38..d8b0a452ba5 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/zh.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/zh.ts @@ -1111,7 +1111,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "Kilo Code 新功能", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "我们在更快、更高效的基础上重新构建了扩展。", "migration.whatsNew.features.performance.title": "更快的智能体性能", "migration.whatsNew.features.performance.detail": diff --git a/packages/kilo-vscode/webview-ui/src/i18n/zht.ts b/packages/kilo-vscode/webview-ui/src/i18n/zht.ts index 2cb4d97de5f..124a0a59670 100644 --- a/packages/kilo-vscode/webview-ui/src/i18n/zht.ts +++ b/packages/kilo-vscode/webview-ui/src/i18n/zht.ts @@ -1112,7 +1112,6 @@ export const dict = { // Screen 1 — What's New "migration.whatsNew.title": "Kilo Code 新功能", - "migration.whatsNew.badge": "Beta", "migration.whatsNew.subtitle": "我們在更快、更高效的基礎上重新建構了擴充功能。", "migration.whatsNew.features.performance.title": "更快的 Agent 效能", "migration.whatsNew.features.performance.detail": From 1a7b6f9fbcea0409ba20cafd940081234de27829 Mon Sep 17 00:00:00 2001 From: theQuert Date: Tue, 24 Mar 2026 00:23:20 +0800 Subject: [PATCH 013/308] feat: register Apertis as CLI provider with dynamic model fetching Add Apertis provider to the CLI backend so the migration mapping (id: "apertis") has a matching provider to consume the stored API key. - Inject apertis in ModelsDev.get() using @ai-sdk/openai-compatible - Add model fetching from api.apertis.ai/v1/models (OpenAI format) - Add auth resolution: Config > Auth store > APERTIS_API_KEY env var --- packages/opencode/src/provider/model-cache.ts | 90 +++++++++++++++++++ packages/opencode/src/provider/models.ts | 22 +++++ 2 files changed, 112 insertions(+) diff --git a/packages/opencode/src/provider/model-cache.ts b/packages/opencode/src/provider/model-cache.ts index 1d1a2d4e129..d902a40e881 100644 --- a/packages/opencode/src/provider/model-cache.ts +++ b/packages/opencode/src/provider/model-cache.ts @@ -164,11 +164,69 @@ export namespace ModelCache { return fetchKiloModels(options) } + // kilocode_change start + if (providerID === "apertis") { + return fetchApertisModels(options) + } + // kilocode_change end + // Other providers not implemented yet log.debug("provider not implemented", { providerID }) return {} } + // kilocode_change start + const APERTIS_BASE_URL = "https://api.apertis.ai/v1" + + async function fetchApertisModels(options: any): Promise> { + const baseURL = options.baseURL ?? APERTIS_BASE_URL + const apiKey = options.apiKey + + if (!apiKey) { + log.debug("no API key for apertis, skipping model fetch") + return {} + } + + const url = `${baseURL.replace(/\/+$/, "")}/models` + const response = await fetch(url, { + headers: { + Authorization: `Bearer ${apiKey}`, + }, + signal: AbortSignal.timeout(10_000), + }) + + if (!response.ok) { + log.error("apertis model fetch failed", { status: response.status }) + return {} + } + + const json = (await response.json()) as { data?: Array<{ id: string; owned_by?: string }> } + const models: Record = {} + + for (const model of json.data ?? []) { + models[model.id] = { + id: model.id, + name: model.id, + family: model.owned_by ?? "", + release_date: "", + attachment: false, + reasoning: false, + temperature: true, + tool_call: true, + cost: { input: 0, output: 0 }, + limit: { context: 128000, output: 4096 }, + options: {}, + modalities: { + input: ["text"], + output: ["text"], + }, + } + } + + return models + } + // kilocode_change end + /** * Get authentication options from multiple sources * Priority: Config > Auth > Env @@ -223,6 +281,38 @@ export namespace ModelCache { }) } + // kilocode_change start + if (providerID === "apertis") { + const config = await Config.get() + const providerConfig = config.provider?.[providerID] + if (providerConfig?.options?.apiKey) { + options.apiKey = providerConfig.options.apiKey + } + if (providerConfig?.options?.baseURL) { + options.baseURL = providerConfig.options.baseURL + } + + const auth = await Auth.get(providerID) + if (auth && auth.type === "api") { + options.apiKey = auth.key + } + + const env = Env.all() + if (env.APERTIS_API_KEY) { + options.apiKey = env.APERTIS_API_KEY + } + if (env.APERTIS_BASE_URL) { + options.baseURL = env.APERTIS_BASE_URL + } + + log.debug("apertis auth options resolved", { + providerID, + hasKey: !!options.apiKey, + hasBaseURL: !!options.baseURL, + }) + } + // kilocode_change end + return options } } diff --git a/packages/opencode/src/provider/models.ts b/packages/opencode/src/provider/models.ts index 2751547c675..3044d97f853 100644 --- a/packages/opencode/src/provider/models.ts +++ b/packages/opencode/src/provider/models.ts @@ -168,6 +168,28 @@ export namespace ModelsDev { } } + // Inject Apertis provider with dynamic model fetching + if (!providers["apertis"]) { + const apertisConfigObj = await Config.get() + const apertisConfig = apertisConfigObj.provider?.apertis?.options + const apertisBaseURL = apertisConfig?.baseURL ?? "https://api.apertis.ai/v1" + const apertisFetchOptions = { + ...(apertisConfig?.baseURL ? { baseURL: apertisConfig.baseURL } : {}), + } + const apertisModels = await ModelCache.fetch("apertis", apertisFetchOptions).catch(() => ({})) + providers["apertis"] = { + id: "apertis", + name: "Apertis", + env: ["APERTIS_API_KEY"], + api: apertisBaseURL, + npm: "@ai-sdk/openai-compatible", + models: apertisModels, + } + if (Object.keys(apertisModels).length === 0) { + ModelCache.refresh("apertis", apertisFetchOptions).catch(() => {}) + } + } + return providers // kilocode_change end } From 70633f5d504e07db459f66115ef4ffb05941ec82 Mon Sep 17 00:00:00 2001 From: "kiloconnect[bot]" <240665456+kiloconnect[bot]@users.noreply.github.com> Date: Tue, 24 Mar 2026 08:55:57 +0000 Subject: [PATCH 014/308] fix(cli,vscode): include subagent costs in total session cost display The session cost displayed in the header/sidebar only summed costs from the root session's assistant messages, ignoring costs from subagent (child) sessions spawned via the task tool. This made the displayed cost misleading when subagents were used. Update all cost calculation sites to also aggregate costs from child sessions by filtering sessions with parentID matching the current session and summing their assistant message costs. Affected surfaces: - CLI TUI header and sidebar - VS Code extension (adds parentID to SessionInfo, aggregates in totalCost) - Web app (session-context-metrics, session-context-usage, session-context-tab) - ACP agent usage updates Closes #7495 --- .../src/components/session-context-usage.tsx | 15 +++++++++++- .../session/session-context-metrics.ts | 12 ++++++---- .../session/session-context-tab.tsx | 15 +++++++++++- .../kilo-vscode/src/kilo-provider-utils.ts | 1 + .../webview-ui/src/context/session.tsx | 8 ++++++- .../webview-ui/src/types/messages.ts | 1 + packages/opencode/src/acp/agent.ts | 20 +++++++++++++++- .../src/cli/cmd/tui/routes/session/header.tsx | 23 +++++++++++++++---- .../cli/cmd/tui/routes/session/sidebar.tsx | 13 ++++++++++- 9 files changed, 95 insertions(+), 13 deletions(-) diff --git a/packages/app/src/components/session-context-usage.tsx b/packages/app/src/components/session-context-usage.tsx index 08ae4d3194e..8a1a9ff5b12 100644 --- a/packages/app/src/components/session-context-usage.tsx +++ b/packages/app/src/components/session-context-usage.tsx @@ -45,7 +45,20 @@ export function SessionContextUsage(props: SessionContextUsageProps) { }), ) - const metrics = createMemo(() => getSessionContextMetrics(messages(), sync.data.provider.all)) + // kilocode_change start - include subagent session costs in total + const childCost = createMemo(() => { + const id = params.id + if (!id) return 0 + return sync.data.session + .filter((s) => s.parentID === id) + .reduce( + (acc, child) => + acc + (sync.data.message[child.id] ?? []).reduce((sum, m) => sum + (m.role === "assistant" ? m.cost : 0), 0), + 0, + ) + }) + // kilocode_change end + const metrics = createMemo(() => getSessionContextMetrics(messages(), sync.data.provider.all, childCost())) const context = createMemo(() => metrics().context) const cost = createMemo(() => { return usd().format(metrics().totalCost) diff --git a/packages/app/src/components/session/session-context-metrics.ts b/packages/app/src/components/session/session-context-metrics.ts index 4bdcff52ebb..78e09425f91 100644 --- a/packages/app/src/components/session/session-context-metrics.ts +++ b/packages/app/src/components/session/session-context-metrics.ts @@ -47,8 +47,10 @@ const lastAssistantWithTokens = (messages: Message[]) => { } } -const build = (messages: Message[] = [], providers: Provider[] = []): Metrics => { - const totalCost = messages.reduce((sum, msg) => sum + (msg.role === "assistant" ? msg.cost : 0), 0) +// kilocode_change start - accept optional child cost to include subagent costs +const build = (messages: Message[] = [], providers: Provider[] = [], childCost = 0): Metrics => { + const totalCost = messages.reduce((sum, msg) => sum + (msg.role === "assistant" ? msg.cost : 0), 0) + childCost + // kilocode_change end const message = lastAssistantWithTokens(messages) if (!message) return { totalCost, context: undefined } @@ -77,6 +79,8 @@ const build = (messages: Message[] = [], providers: Provider[] = []): Metrics => } } -export function getSessionContextMetrics(messages: Message[] = [], providers: Provider[] = []) { - return build(messages, providers) +// kilocode_change start - accept optional child cost to include subagent costs +export function getSessionContextMetrics(messages: Message[] = [], providers: Provider[] = [], childCost = 0) { + return build(messages, providers, childCost) } +// kilocode_change end diff --git a/packages/app/src/components/session/session-context-tab.tsx b/packages/app/src/components/session/session-context-tab.tsx index be5118c2eaf..15c5b08e474 100644 --- a/packages/app/src/components/session/session-context-tab.tsx +++ b/packages/app/src/components/session/session-context-tab.tsx @@ -134,7 +134,20 @@ export function SessionContextTab() { }), ) - const metrics = createMemo(() => getSessionContextMetrics(messages(), sync.data.provider.all)) + // kilocode_change start - include subagent session costs in total + const childCost = createMemo(() => { + const id = params.id + if (!id) return 0 + return sync.data.session + .filter((s) => s.parentID === id) + .reduce( + (acc, child) => + acc + (sync.data.message[child.id] ?? []).reduce((sum, m) => sum + (m.role === "assistant" ? m.cost : 0), 0), + 0, + ) + }) + // kilocode_change end + const metrics = createMemo(() => getSessionContextMetrics(messages(), sync.data.provider.all, childCost())) const ctx = createMemo(() => metrics().context) const formatter = createMemo(() => createSessionContextFormatter(language.intl())) diff --git a/packages/kilo-vscode/src/kilo-provider-utils.ts b/packages/kilo-vscode/src/kilo-provider-utils.ts index 6449f43f917..6eabed0d39e 100644 --- a/packages/kilo-vscode/src/kilo-provider-utils.ts +++ b/packages/kilo-vscode/src/kilo-provider-utils.ts @@ -61,6 +61,7 @@ export function getErrorMessage(error: unknown): string { export function sessionToWebview(session: Session) { return { id: session.id, + parentID: session.parentID ?? null, title: session.title, createdAt: new Date(session.time.created).toISOString(), updatedAt: new Date(session.time.updated).toISOString(), diff --git a/packages/kilo-vscode/webview-ui/src/context/session.tsx b/packages/kilo-vscode/webview-ui/src/context/session.tsx index ba7a6fbd862..a784c83ae04 100644 --- a/packages/kilo-vscode/webview-ui/src/context/session.tsx +++ b/packages/kilo-vscode/webview-ui/src/context/session.tsx @@ -1532,7 +1532,13 @@ export const SessionProvider: ParentComponent = (props) => { .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()), ) - const totalCost = createMemo(() => calcTotalCost(messages())) + const totalCost = createMemo(() => { + const id = currentSessionID() + const cost = calcTotalCost(messages()) + if (!id) return cost + const children = Object.values(store.sessions).filter((s) => s.parentID === id) + return children.reduce((acc, child) => acc + calcTotalCost(store.messages[child.id] ?? []), cost) + }) // Status text derived from last assistant message parts const statusText = createMemo(() => { diff --git a/packages/kilo-vscode/webview-ui/src/types/messages.ts b/packages/kilo-vscode/webview-ui/src/types/messages.ts index 6a51ec31edf..432231f180c 100644 --- a/packages/kilo-vscode/webview-ui/src/types/messages.ts +++ b/packages/kilo-vscode/webview-ui/src/types/messages.ts @@ -128,6 +128,7 @@ export interface SessionFileDiff { // Session info (simplified for webview) export interface SessionInfo { id: string + parentID?: string | null title?: string createdAt: string updatedAt: string diff --git a/packages/opencode/src/acp/agent.ts b/packages/opencode/src/acp/agent.ts index 59ecfcc6dbe..7436d789dbf 100644 --- a/packages/opencode/src/acp/agent.ts +++ b/packages/opencode/src/acp/agent.ts @@ -106,7 +106,25 @@ export namespace ACP { } const used = msg.tokens.input + (msg.tokens.cache?.read ?? 0) - const totalCost = assistantMessages.reduce((sum, m) => sum + m.info.cost, 0) + // kilocode_change start - include subagent session costs in total + const children = await sdk.session + .children({ sessionID, directory }, { throwOnError: true }) + .then((x) => x.data ?? []) + .catch(() => [] as { id: string }[]) + const childCost = await Promise.all( + children.map((child) => + sdk.session + .messages({ sessionID: child.id, directory }, { throwOnError: true }) + .then((x) => + (x.data ?? []) + .filter((m): m is (typeof assistantMessages)[number] => m.info.role === "assistant") + .reduce((sum, m) => sum + m.info.cost, 0), + ) + .catch(() => 0), + ), + ).then((costs) => costs.reduce((a, b) => a + b, 0)) + const totalCost = assistantMessages.reduce((sum, m) => sum + m.info.cost, 0) + childCost + // kilocode_change end await connection .sessionUpdate({ diff --git a/packages/opencode/src/cli/cmd/tui/routes/session/header.tsx b/packages/opencode/src/cli/cmd/tui/routes/session/header.tsx index 7999e392288..b1e9a9fb081 100644 --- a/packages/opencode/src/cli/cmd/tui/routes/session/header.tsx +++ b/packages/opencode/src/cli/cmd/tui/routes/session/header.tsx @@ -48,10 +48,25 @@ export function Header() { const messages = createMemo(() => sync.data.message[route.sessionID] ?? []) const cost = createMemo(() => { - const total = pipe( - messages(), - sumBy((x) => (x.role === "assistant" ? x.cost : 0)), - ) + // kilocode_change start - include subagent session costs in total + const sid = route.sessionID + const total = + pipe( + messages(), + sumBy((x) => (x.role === "assistant" ? x.cost : 0)), + ) + + sync.data.session + .filter((s) => s.parentID === sid) + .reduce( + (acc, child) => + acc + + pipe( + sync.data.message[child.id] ?? [], + sumBy((x) => (x.role === "assistant" ? x.cost : 0)), + ), + 0, + ) + // kilocode_change end return new Intl.NumberFormat("en-US", { style: "currency", currency: "USD", diff --git a/packages/opencode/src/cli/cmd/tui/routes/session/sidebar.tsx b/packages/opencode/src/cli/cmd/tui/routes/session/sidebar.tsx index 45824208bfe..5c71bd8af06 100644 --- a/packages/opencode/src/cli/cmd/tui/routes/session/sidebar.tsx +++ b/packages/opencode/src/cli/cmd/tui/routes/session/sidebar.tsx @@ -41,7 +41,18 @@ export function Sidebar(props: { sessionID: string; overlay?: boolean }) { ) const cost = createMemo(() => { - const total = messages().reduce((sum, x) => sum + (x.role === "assistant" ? x.cost : 0), 0) + // kilocode_change start - include subagent session costs in total + const total = + messages().reduce((sum, x) => sum + (x.role === "assistant" ? x.cost : 0), 0) + + sync.data.session + .filter((s) => s.parentID === props.sessionID) + .reduce( + (acc, child) => + acc + + (sync.data.message[child.id] ?? []).reduce((sum, x) => sum + (x.role === "assistant" ? x.cost : 0), 0), + 0, + ) + // kilocode_change end return new Intl.NumberFormat("en-US", { style: "currency", currency: "USD", From 181e3a24f8429d5f1fa5963f757e5ad308aaaf96 Mon Sep 17 00:00:00 2001 From: Josh Lambert Date: Tue, 24 Mar 2026 08:37:12 -0400 Subject: [PATCH 015/308] docs(kilo-docs): add platform tabs infrastructure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add the foundation for platform-specific documentation: - Platform type (legacy/new/all) in NavLink interface - PageVersionSwitcher banner for legacy-only and new-only pages - PlatformBadge component in SideNav with Legacy/New labels - Tabs hydration fix (SSR-safe useState + useEffect) - _app.tsx reads frontmatter.platform and renders banner No content changes — frontmatter markers and nav tags will be added in their respective section PRs. --- .../components/PageVersionSwitcher.tsx | 44 +++++++++++++++++++ packages/kilo-docs/components/SideNav.tsx | 38 +++++++++++++++- packages/kilo-docs/components/Tabs.tsx | 4 +- packages/kilo-docs/components/index.js | 1 + packages/kilo-docs/lib/types.ts | 3 ++ packages/kilo-docs/pages/_app.tsx | 5 ++- 6 files changed, 91 insertions(+), 4 deletions(-) create mode 100644 packages/kilo-docs/components/PageVersionSwitcher.tsx diff --git a/packages/kilo-docs/components/PageVersionSwitcher.tsx b/packages/kilo-docs/components/PageVersionSwitcher.tsx new file mode 100644 index 00000000000..1ff9ec3a91a --- /dev/null +++ b/packages/kilo-docs/components/PageVersionSwitcher.tsx @@ -0,0 +1,44 @@ +import React from "react" +import type { Platform } from "../lib/types" + +interface Props { + platform?: Platform +} + +export function PageVersionSwitcher({ platform }: Props) { + if (!platform || platform === "all") return null + + const legacy = platform === "legacy" + return ( +
+ {legacy ? "\u24D8" : "\u2728"} + + {legacy + ? "This page documents the legacy VSCode extension. The current VSCode extension & CLI does not have an equivalent page yet." + : "This page documents the current VSCode extension & CLI. There is no equivalent page for the legacy VSCode extension."} + + + +
+ ) +} diff --git a/packages/kilo-docs/components/SideNav.tsx b/packages/kilo-docs/components/SideNav.tsx index 1960fa1f842..2897576d3fb 100644 --- a/packages/kilo-docs/components/SideNav.tsx +++ b/packages/kilo-docs/components/SideNav.tsx @@ -1,7 +1,7 @@ import React, { useState, useEffect } from "react" import { useRouter } from "next/router" import Link from "next/link" -import { SectionNav } from "../lib/types" +import { Platform, SectionNav } from "../lib/types" import { Nav } from "../lib/nav" // Define navigation items for each major section @@ -67,6 +67,16 @@ const ChevronLeft = () => ( ) +function PlatformBadge({ platform }: { platform?: Platform }) { + if (!platform || platform === "all") return null + const label = platform === "legacy" ? "Legacy" : "New" + return ( + + {label} + + ) +} + interface SideNavProps { isMobileOpen?: boolean onMobileClose?: () => void @@ -268,6 +278,7 @@ export function SideNav({ isMobileOpen = false, onMobileClose }: SideNavProps) {
{link.children} +
) diff --git a/packages/kilo-docs/components/Tabs.tsx b/packages/kilo-docs/components/Tabs.tsx index 43fe16707ca..6cc69abda61 100644 --- a/packages/kilo-docs/components/Tabs.tsx +++ b/packages/kilo-docs/components/Tabs.tsx @@ -27,16 +27,16 @@ export function Tabs({ children }: TabsProps) { ) const indexFromHash = () => { - if (typeof window === "undefined") return 0 const hash = window.location.hash.slice(1) if (!hash) return 0 const found = tabs.findIndex((tab) => slugify(tab.props.label) === hash) return found >= 0 ? found : 0 } - const [activeIndex, setActiveIndex] = useState(indexFromHash) + const [activeIndex, setActiveIndex] = useState(0) useEffect(() => { + setActiveIndex(indexFromHash()) const onHashChange = () => setActiveIndex(indexFromHash()) window.addEventListener("hashchange", onHashChange) return () => window.removeEventListener("hashchange", onHashChange) diff --git a/packages/kilo-docs/components/index.js b/packages/kilo-docs/components/index.js index 9bb2cc21b24..9297d31ab0e 100644 --- a/packages/kilo-docs/components/index.js +++ b/packages/kilo-docs/components/index.js @@ -7,6 +7,7 @@ export * from "./Icon" export * from "./Image" export * from "./KiloCodeIcon" export * from "./PageFooter" +export * from "./PageVersionSwitcher" export * from "./SideNav" export * from "./Table" export * from "./TableOfContents" diff --git a/packages/kilo-docs/lib/types.ts b/packages/kilo-docs/lib/types.ts index 7e5fdf7a22e..5feef035784 100644 --- a/packages/kilo-docs/lib/types.ts +++ b/packages/kilo-docs/lib/types.ts @@ -1,6 +1,9 @@ +export type Platform = "legacy" | "new" | "all" + export interface NavLink { href: string children: string + platform?: Platform // "legacy" = stable VSCode only, "new" = new VSCode + CLI only, omitted = universal subLinks?: NavLink[] // Optional nested links for second-level navigation } diff --git a/packages/kilo-docs/pages/_app.tsx b/packages/kilo-docs/pages/_app.tsx index 6d45a81782c..245ab29af70 100644 --- a/packages/kilo-docs/pages/_app.tsx +++ b/packages/kilo-docs/pages/_app.tsx @@ -3,7 +3,7 @@ import Head from "next/head" import { useRouter } from "next/router" import posthog from "posthog-js" -import { CopyPageButton, PageFooter, SideNav, TableOfContents, TopNav } from "../components" +import { CopyPageButton, PageFooter, PageVersionSwitcher, SideNav, TableOfContents, TopNav } from "../components" import "prismjs" import "prismjs/components/prism-bash.min" @@ -129,6 +129,8 @@ export default function MyApp({ Component, pageProps }: AppProps) { const toc = pageProps.markdoc?.content ? collectHeadings(pageProps.markdoc.content) : [] + const platform = markdoc?.frontmatter?.platform + return ( <> @@ -179,6 +181,7 @@ export default function MyApp({ Component, pageProps }: AppProps) {
+ {markdoc && } {markdoc && }
From 57d378e0c85af566f783d006dda99135a6b1271c Mon Sep 17 00:00:00 2001 From: Josh Lambert Date: Tue, 24 Mar 2026 05:04:39 -0400 Subject: [PATCH 016/308] docs(kilo-docs): add platform tabs to code-with-ai agents pages Add VSCode (Pre-release) and CLI tabs to 5 agents pages: - chat-interface.md: Tabbed quick setup, chat UI, suggested responses - using-modes.md: Modes vs agents callout, switching methods, built-in agents - context-mentions.md: Tool-based context model, editor context, @-mentions - model-selection.md: Model config per platform - orchestrator-mode.md: task tool subagent sessions vs new_task/attempt_completion Fixes from validation: - Fix tab order in model-selection (VSCode > Pre-release > CLI) - Fix indentation in model-selection tabs - Soften plan agent description (not a replacement for Architect) - Move orphaned footnotes that referenced classic-only tools Part of the docs platform tabs effort (PR 3 of 8). Depends on #7497 for infrastructure. --- .../code-with-ai/agents/chat-interface.md | 108 ++++++++++++++++++ .../code-with-ai/agents/context-mentions.md | 94 +++++++++++++++ .../code-with-ai/agents/model-selection.md | 26 +++++ .../code-with-ai/agents/orchestrator-mode.md | 27 ++++- .../pages/code-with-ai/agents/using-modes.md | 97 ++++++++++++++-- 5 files changed, 338 insertions(+), 14 deletions(-) diff --git a/packages/kilo-docs/pages/code-with-ai/agents/chat-interface.md b/packages/kilo-docs/pages/code-with-ai/agents/chat-interface.md index 351af9549ec..7f0980cf8be 100644 --- a/packages/kilo-docs/pages/code-with-ai/agents/chat-interface.md +++ b/packages/kilo-docs/pages/code-with-ai/agents/chat-interface.md @@ -15,10 +15,26 @@ If you're typing code in the editor and want AI to finish your line or block, ch ## Quick Setup +{% tabs %} +{% tab label="VSCode (Legacy)" %} + Find the Kilo Code icon ({% kilo-code-icon /%}) in VS Code's Primary Side Bar. Click it to open the chat panel. **Lost the panel?** Go to View > Open View... and search for "Kilo Code" +{% /tab %} +{% tab label="VSCode" %} + +Click the Kilo Code icon ({% kilo-code-icon /%}) in VS Code's Primary Side Bar to open the sidebar chat. You can also pop it out into an editor tab for a larger workspace. + +{% /tab %} +{% tab label="CLI" %} + +Open your terminal and run `kilo` to launch the interactive TUI. You'll see a prompt where you can start typing requests immediately. The TUI is fully keyboard-driven — no mouse required. + +{% /tab %} +{% /tabs %} + ## How to Talk to Kilo Code **The key insight:** Just type what you want in normal English. No special commands needed. @@ -46,6 +62,9 @@ Find the Kilo Code icon ({% kilo-code-icon /%}) in VS Code's Primary Side Bar. C ## The Chat Interface +{% tabs %} +{% tab label="VSCode (Legacy)" %} + {% image src="/docs/img/the-chat-interface/the-chat-interface-1.png" alt="Chat interface components labeled with callouts" width="800" caption="Everything you need is right here" /%} **Essential controls:** @@ -56,6 +75,48 @@ Find the Kilo Code icon ({% kilo-code-icon /%}) in VS Code's Primary Side Bar. C - **Plus button** - Start a new task session - **Mode selector** - Choose how Kilo should approach your task +**Providing context with @-mentions:** + +Reference files and other context directly in your message using `@`: + +- `@file` - Reference a specific file +- `@url` - Include content from a URL +- `@problems` - Include current VS Code problems +- `@terminal` - Include terminal output +- `@git-changes` - Include uncommitted changes +- `@commit` - Reference a specific commit + +{% /tab %} +{% tab label="VSCode" %} + +**Essential controls:** + +- **Input prompt** - Type your requests and press Enter to send +- **Action buttons** - Approve or reject proposed changes +- **Agent dropdown** - Switch between agents (e.g. Code, Ask, Plan) from the sidebar +- **Session management** - Start new sessions or resume previous ones + +**Providing context:** + +The extension automatically passes context from your editor, including your open tabs and active file. You can type `@` in the chat input to get file autocomplete suggestions, or mention file paths naturally in your message (e.g., "update src/utils.ts to add a helper function"). The agent can also discover files on its own using its built-in tools. + +{% /tab %} +{% tab label="CLI" %} + +**Essential controls:** + +- **Input prompt** - Type your requests and press Enter to send +- **Action buttons** - Approve or reject proposed changes +- **Agent cycling** - Switch between agents using keybinds or slash commands +- **Session management** - Start new sessions or resume previous ones + +**Providing context:** + +Type `@` in the TUI to get file autocomplete suggestions, or mention file paths directly in your message (e.g., "look at src/utils.ts") and the agent will read them. When using the non-interactive `kilo run` command, you can pass `-f path/to/file.ts` to explicitly include files (this flag is not available in the TUI). The agent also has `glob`, `grep`, and `read` tools to discover files on its own. + +{% /tab %} +{% /tabs %} + ## Quick Interactions **Click to act:** @@ -87,6 +148,9 @@ Find the Kilo Code icon ({% kilo-code-icon /%}) in VS Code's Primary Side Bar. C When Kilo Code needs more information to complete a task, it uses the [`ask_followup_question`](/docs/automate/tools/ask-followup-question) tool. To make responding easier and faster, Kilo Code often provides suggested answers alongside the question. +{% tabs %} +{% tab label="VSCode (Legacy)" %} + {% image src="/docs/img/suggested-responses/suggested-responses.png" alt="Example of Kilo Code asking a question with suggested response buttons below it" width="800" caption="Suggested responses appear as clickable buttons below questions" /%} **How it works:** @@ -109,6 +173,18 @@ You have two options for using suggested responses: - _Alternatively_, hover over the suggestion button and click the pencil icon ({% codicon name="edit" /%}) that appears - **Result**: The text of the suggestion is copied into the chat input box. You can then modify the text as needed before pressing Enter to send your customized response. This is useful when a suggestion is close but needs minor adjustments. +{% /tab %} +{% tab label="VSCode & CLI" %} + +**How it works:** + +1. **Question Appears** - Kilo Code asks a question using the `question` tool +2. **Options Displayed** - Selectable options are presented that you can choose from +3. **Selection** - Pick an option or type a custom response + +{% /tab %} +{% /tabs %} + **Benefits:** - **Speed** - Quickly respond without typing full answers @@ -119,6 +195,9 @@ This feature streamlines the interaction when Kilo Code requires clarification, ## Tips for Better Workflow +{% tabs %} +{% tab label="VSCode (Legacy)" %} + {% callout type="tip" %} **Move Kilo Code to the Secondary Side Bar** for a better layout. Right-click on the Kilo Code icon in the Activity Bar and select **Move To → Secondary Side Bar**. This lets you see the Explorer, Search, Source Control, etc. alongside Kilo Code. @@ -129,4 +208,33 @@ This feature streamlines the interaction when Kilo Code requires clarification, **Drag files directly into chat.** Once you have Kilo Code in a separate sidebar from the file explorer, you can drag files from the explorer into the chat window (even multiple at once). Just hold down the Shift key after you start dragging the files. {% /callout %} +{% /tab %} +{% tab label="VSCode" %} + +{% callout type="tip" %} +**Use agents instead of modes.** Switch between agents like Code, Ask, and Plan using the agent dropdown or slash commands. Each agent is tuned for a different type of task. +{% /callout %} + +{% callout type="tip" %} +**Your editor context is automatic.** The extension reads your open tabs and active file, so you don't need to manually reference every file. Focus your message on what you want done. +{% /callout %} + +{% callout type="tip" %} +**Pop out to an editor tab.** If the sidebar feels cramped, pop the chat into a full editor tab for more room. +{% /callout %} + +{% /tab %} +{% tab label="CLI" %} + +{% callout type="tip" %} +**Use agents instead of modes.** Switch between agents like Code, Ask, and Plan using keybinds or slash commands. Each agent is tuned for a different type of task. +{% /callout %} + +{% callout type="tip" %} +**The TUI is keyboard-driven.** Navigate, approve changes, and switch agents entirely from the keyboard — no mouse needed. +{% /callout %} + +{% /tab %} +{% /tabs %} + Ready to start coding? Open the chat panel and describe what you want to build! diff --git a/packages/kilo-docs/pages/code-with-ai/agents/context-mentions.md b/packages/kilo-docs/pages/code-with-ai/agents/context-mentions.md index e4bf59580b0..eab8848c54f 100644 --- a/packages/kilo-docs/pages/code-with-ai/agents/context-mentions.md +++ b/packages/kilo-docs/pages/code-with-ai/agents/context-mentions.md @@ -5,6 +5,11 @@ description: "How to provide context to Kilo Code using mentions" # Context Mentions +Providing the right context helps Kilo Code understand your project and perform tasks accurately. How you provide that context depends on which version of Kilo Code you're using — the **VSCode (Legacy)** version uses `@`-mentions in the chat input, while the current **VSCode & CLI** version uses a tool-based approach where the agent automatically discovers the context it needs. + +{% tabs %} +{% tab label="VSCode (Legacy)" %} + Context mentions are a powerful way to provide Kilo Code with specific information about your project, allowing it to perform tasks more accurately and efficiently. You can use mentions to refer to files, folders, problems, and Git commits. Context mentions start with the `@` symbol. {% image src="/docs/img/context-mentions/context-mentions.png" alt="Context Mentions Overview - showing the @ symbol dropdown menu in the chat interface" width="600" caption="Context mentions overview showing the @ symbol dropdown menu in the chat interface." /%} @@ -116,3 +121,92 @@ The dropdown automatically suggests: | **Click mentions** | Click mentions in chat history to open files or view content | | **Eliminate copy-pasting** | Use mentions instead of manually copying code or errors | | **Combine mentions** | "Fix @problems in @/src/component.ts using the pattern from commit @a1b2c3d" | + +{% /tab %} +{% tab label="VSCode" %} + +The current **VSCode** version uses a fundamentally different context model compared to the **VSCode (Legacy)** version. The agent **automatically discovers and reads the context it needs** using built-in tools. You can also type `@` in the chat input to get file autocomplete suggestions, but the agent can also find files on its own using its tools. + +## How Context Works + +When you describe a task, the agent uses its tools — `read`, `grep`, `glob`, and others — to find and read relevant files on its own. You don't need to explicitly point it at files in most cases; just describe what you want done and the agent will locate the right code. + +### Automatic Editor Context + +The agent automatically receives context from your editor: + +| Context | Details | +| --------------- | -------------------------------------------------- | +| **Active file** | The file currently open and focused in your editor | +| **Open tabs** | Files you have open in editor tabs | + +This context is passed to the agent without any explicit mentions — it's included automatically with each message you send. + +{% callout type="note" %} +**Selection** and **diagnostics** are not sent automatically with each message. They are available through VS Code Code Actions (e.g., selecting code and using the lightbulb menu), but are not part of the default editor context. +{% /callout %} + +### Tool-Based File Access + +Rather than attaching file contents up front, the agent reads files on demand during its work: + +| Tool | Purpose | Example | +| -------- | --------------------------------------------- | ------------------------------------------- | +| **read** | Read the contents of a specific file | Agent reads `src/utils.ts` to understand it | +| **glob** | Find files matching a pattern | Agent searches for `**/*.test.ts` | +| **grep** | Search file contents for a pattern | Agent searches for `function handleError` | +| **bash** | Run shell commands including `git` operations | Agent runs `git diff` or `git log` | + +This means the agent can explore your entire project as needed, rather than being limited to files you explicitly mention. + +## Best Practices + +| Practice | Description | +| ------------------------------ | -------------------------------------------------------------------------------------------------- | +| **Describe the task clearly** | The agent finds context on its own — focus on _what_ you want done rather than _where_ the code is | +| **Mention files when helpful** | If you know the exact file, mention its path to save the agent a search step | +| **Keep editor tabs relevant** | Open tabs are passed as context, so keep relevant files open | +| **Trust the agent's tools** | The agent can search, read, and explore your codebase — let it do the discovery work | + +{% /tab %} +{% tab label="CLI" %} + +The CLI uses a tool-based context model. The agent **automatically discovers and reads the context it needs** using built-in tools. In the TUI, you can type `@` to get file autocomplete suggestions for quick file references. + +## How Context Works + +When you describe a task, the agent uses its tools — `read`, `grep`, `glob`, and others — to find and read relevant files on its own. You don't need to explicitly point it at files in most cases; just describe what you want done and the agent will locate the right code. + +### Providing File Context + +In the terminal-based TUI, you can provide context in several ways: + +- **Type `@` for file autocomplete** — In the TUI, type `@` followed by a filename to get autocomplete suggestions for quick file references. +- **Mention file paths in your message** — Simply refer to files by path in your conversation text (e.g., "look at src/utils.ts") and the agent will read them. +- **Use `kilo run -f`** — When using the non-interactive `kilo run` command, pass `-f path/to/file.ts` to explicitly include a file's contents in the context. This flag is not available in the interactive TUI. +- **Let the agent find files itself** — The agent has access to `glob` (find files by pattern), `grep` (search file contents), and `read` (read file contents) tools. Describe what you're looking for and it will locate the relevant code. + +### Tool-Based File Access + +Rather than attaching file contents up front, the agent reads files on demand during its work: + +| Tool | Purpose | Example | +| -------- | --------------------------------------------- | ------------------------------------------- | +| **read** | Read the contents of a specific file | Agent reads `src/utils.ts` to understand it | +| **glob** | Find files matching a pattern | Agent searches for `**/*.test.ts` | +| **grep** | Search file contents for a pattern | Agent searches for `function handleError` | +| **bash** | Run shell commands including `git` operations | Agent runs `git diff` or `git log` | + +This means the agent can explore your entire project as needed, rather than being limited to files you explicitly mention. + +## Best Practices + +| Practice | Description | +| ------------------------------ | -------------------------------------------------------------------------------------------------- | +| **Describe the task clearly** | The agent finds context on its own — focus on _what_ you want done rather than _where_ the code is | +| **Mention files when helpful** | If you know the exact file, mention its path to save the agent a search step | +| **Use `kilo run -f`** | Pass key files with `-f` when using `kilo run` for immediate context (not available in the TUI) | +| **Trust the agent's tools** | The agent can search, read, and explore your codebase — let it do the discovery work | + +{% /tab %} +{% /tabs %} diff --git a/packages/kilo-docs/pages/code-with-ai/agents/model-selection.md b/packages/kilo-docs/pages/code-with-ai/agents/model-selection.md index bf090ac3404..ee22b39cf31 100644 --- a/packages/kilo-docs/pages/code-with-ai/agents/model-selection.md +++ b/packages/kilo-docs/pages/code-with-ai/agents/model-selection.md @@ -19,6 +19,32 @@ This isn't benchmarks from some lab. It's real usage data from developers like y While the specifics change constantly, some principles stay consistent: +### How to Select and Switch Models + +{% tabs %} +{% tab label="VSCode (Legacy)" %} + +- Use the **model dropdown** in the chat panel to select a model for each conversation. +- Configure **API profiles** in Settings to group provider + model combinations and switch between them quickly. +- Models are **sticky per mode** — each mode (Code, Architect, Debug, etc.) remembers the last model you selected. + +{% /tab %} +{% tab label="VSCode" %} + +- Open the **Settings webview** in the extension sidebar to select a model. +- Alternatively, set models directly in the `kilo.json` config file (the extension reads the same config as the CLI). + +{% /tab %} +{% tab label="CLI" %} + +- Set the default model with the `model` key in your `kilo.json` config file. +- In the TUI, use the **model picker** (keybind to cycle through configured models). +- For non-interactive use, pass `--model` flag to `kilo run` (e.g., `kilo run --model claude-sonnet-4-20250514`). +- Configure per-agent models in the agents section of your config. + +{% /tab %} +{% /tabs %} + **For complex coding tasks**: Premium models (Claude Sonnet/Opus, GPT-5 class, Gemini Pro) typically handle nuanced requirements, large refactors, and architectural decisions better. **For everyday coding**: Mid-tier models often provide the best balance of speed, cost, and quality. They're fast enough to keep your flow state intact and capable enough for most tasks. diff --git a/packages/kilo-docs/pages/code-with-ai/agents/orchestrator-mode.md b/packages/kilo-docs/pages/code-with-ai/agents/orchestrator-mode.md index 9fca04b85c2..84762da247d 100644 --- a/packages/kilo-docs/pages/code-with-ai/agents/orchestrator-mode.md +++ b/packages/kilo-docs/pages/code-with-ai/agents/orchestrator-mode.md @@ -7,8 +7,6 @@ description: "Using Orchestrator mode for complex multi-step tasks" Orchestrator Mode (formerly known as Boomerang Tasks) allows you to break down complex projects into smaller, manageable pieces. Think of it like delegating parts of your work to specialized assistants. Each subtask runs in its own context, often using a different Kilo Code mode tailored for that specific job (like [`code`](/docs/code-with-ai/agents/using-modes#code-mode-default), [`architect`](/docs/code-with-ai/agents/using-modes#architect-mode), or [`debug`](/docs/code-with-ai/agents/using-modes#debug-mode)). -{% youtube url="https://www.youtube.com/watch?v=20MmJNeOODo" caption="Orchestrator Mode explained and demonstrated" /%} - ## Why Use Orchestrator Mode? - **Tackle Complexity:** Break large, multi-step projects (e.g., building a full feature) into focused subtasks (e.g., design, implementation, documentation). @@ -37,6 +35,25 @@ Orchestrator Mode provides a powerful way to manage complex development workflow Use subtasks to maintain clarity. If a request significantly shifts focus or requires a different expertise (mode), consider creating a subtask rather than overloading the current one. {% /callout %} -1. This context is passed via the `message` parameter of the [`new_task`](/docs/automate/tools/new-task) tool. -2. The mode for the subtask is specified via the `mode` parameter of the [`new_task`](/docs/automate/tools/new-task) tool during initiation. -3. This summary is passed via the `result` parameter of the [`attempt_completion`](/docs/automate/tools/attempt-completion) tool when the subtask finishes. +{% tabs %} +{% tab label="VSCode (Legacy)" %} + +{% youtube url="https://www.youtube.com/watch?v=20MmJNeOODo" caption="Orchestrator Mode explained and demonstrated" /%} + +In the **VSCode** version, orchestrator mode uses two tools to manage subtasks: + +1. The [`new_task`](/docs/automate/tools/new-task) tool creates a subtask. Context is passed via the `message` parameter, and the subtask's mode is specified via the `mode` parameter (e.g., `code`, `architect`, `debug`). +2. When a subtask finishes, it calls [`attempt_completion`](/docs/automate/tools/attempt-completion). The summary is passed back to the parent via the `result` parameter. + +{% /tab %} +{% tab label="VSCode & CLI" %} + +In the new CLI and extension, orchestrator mode uses the `task` tool to launch **subagent sessions**: + +- The `task` tool creates a new child session. The agent name is specified as a parameter (e.g., `general`, `explore`, or custom subagent types you define). +- Child sessions are **fully isolated** — they run in their own conversation context and do not share message history with the parent. +- When the subagent completes its work, it returns a single message back to the parent orchestrator with the result. +- The parent orchestrator can launch multiple subagent sessions concurrently for parallel work. + +{% /tab %} +{% /tabs %} diff --git a/packages/kilo-docs/pages/code-with-ai/agents/using-modes.md b/packages/kilo-docs/pages/code-with-ai/agents/using-modes.md index 1f0c4f1e0d9..3f5953d7e55 100644 --- a/packages/kilo-docs/pages/code-with-ai/agents/using-modes.md +++ b/packages/kilo-docs/pages/code-with-ai/agents/using-modes.md @@ -7,6 +7,10 @@ description: "Understanding and using different modes in Kilo Code" Modes in Kilo Code are specialized personas that tailor the assistant's behavior to your current task. Each mode offers different capabilities, expertise, and access levels to help you accomplish specific goals. +{% callout type="info" %} +The **VSCode (Legacy)** version calls these **modes**, while the current **VSCode & CLI** version calls them **agents**. The concept is the same—specialized personas with distinct tool access and behavior. +{% /callout %} + ## Why Use Different Modes? - **Task specialization:** Get precisely the type of assistance you need for your current task @@ -14,10 +18,13 @@ Modes in Kilo Code are specialized personas that tailor the assistant's behavior - **Focused interactions:** Receive responses optimized for your current activity - **Workflow optimization:** Seamlessly transition between planning, implementing, debugging, and learning -{% youtube url="https://youtu.be/cS4vQfX528w" caption="Explaining the different modes in Kilo Code" /%} - ## Switching Between Modes +{% tabs %} +{% tab label="VSCode (Legacy)" %} + +{% youtube url="https://youtu.be/cS4vQfX528w" caption="Explaining the different modes in Kilo Code" /%} + Four ways to switch modes: 1. **Dropdown menu:** Click the selector to the left of the chat input @@ -49,8 +56,32 @@ Users often confuse `/newtask` and `/smol`. Here's the key difference: {% image src="/docs/img/modes/modes-2.png" alt="Accepting a mode switch suggestion from Kilo Code" width="400" /%} +{% /tab %} +{% tab label="VSCode" %} + +There are several ways to switch agents: + +- **Dropdown menu:** Click the agent selector in the sidebar to switch between agents. +- **Slash commands:** Type `/` in the chat input to switch agents (e.g., `/code`, `/ask`, `/plan`, `/debug`). +- **Keyboard shortcut:** Use a keyboard shortcut to cycle through available agents. + +{% /tab %} +{% tab label="CLI" %} + +There are several ways to switch agents: + +- **Keybinds:** Press the displayed key to cycle through available agents. +- **Slash commands:** Type `/` in the chat input to see available commands, including switching agents (e.g., `/code`, `/ask`, `/plan`, `/debug`). +- **Config file:** Set the `default_agent` key in your configuration to change the default agent on startup. + +{% /tab %} +{% /tabs %} + ## Built-in Modes +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ### Code Mode (Default) | Aspect | Details | @@ -109,13 +140,61 @@ Users often confuse `/newtask` and `/smol`. Here's the key difference: | **Ideal For** | Catching issues early, enforcing code standards, accelerating PR turnaround | | **Special Features** | Code review before committing, surfacing feedback across performance, security, style, and test coverage | +{% /tab %} +{% tab label="VSCode & CLI" %} + +### code (Default) + +| Aspect | Details | +| -------------------- | ----------------------------------------------------------------------------------------------------------------- | +| **Description** | A skilled software engineer with expertise in programming languages, design patterns, and best practices | +| **Tool Access** | Full access to all tools: `read`, `edit`, `glob`, `grep`, `bash`, `task`, `webfetch`, plus tools from MCP servers | +| **Ideal For** | Writing code, implementing features, debugging, and general development | +| **Special Features** | No tool restrictions—full flexibility for all coding tasks | + +### ask + +| Aspect | Details | +| -------------------- | ------------------------------------------------------------------------------------------------- | +| **Description** | A knowledgeable technical assistant focused on answering questions without changing your codebase | +| **Tool Access** | Read-only tools only (cannot edit files or run commands) | +| **Ideal For** | Code explanation, concept exploration, and technical learning | +| **Special Features** | Optimized for informative responses without modifying your project | + +### plan + +| Aspect | Details | +| -------------------- | ---------------------------------------------------------------------------------------------------- | +| **Description** | An experienced technical leader and planner who helps design systems and create implementation plans | +| **Tool Access** | Read-only tools plus restricted file editing (e.g., markdown files only) | +| **Ideal For** | System design, high-level planning, and architecture discussions | +| **Special Features** | Similar to the **VSCode (Legacy)** version's "Architect" mode, with a planning-focused approach | + +### debug + +| Aspect | Details | +| -------------------- | ----------------------------------------------------------------------------------- | +| **Description** | An expert problem solver specializing in systematic troubleshooting and diagnostics | +| **Tool Access** | Full access to all tools | +| **Ideal For** | Tracking down bugs, diagnosing errors, and resolving complex issues | +| **Special Features** | Uses a methodical approach of analyzing, narrowing possibilities, and fixing issues | + +### orchestrator + +| Aspect | Details | +| -------------------- | -------------------------------------------------------------------------------------------------------------------- | +| **Description** | A strategic workflow orchestrator who coordinates complex tasks by delegating them to appropriate specialized agents | +| **Tool Access** | Limited access to create new tasks and coordinate workflows | +| **Ideal For** | Breaking down complex projects into manageable subtasks assigned to specialized agents | +| **Special Features** | Delegates work to other agents; also has access to the **explore** subagent for codebase exploration | + +{% callout type="info" %} +The **VSCode & CLI** version does not include a built-in Review agent. Code review workflows can be handled by the **code** agent or via custom agent configurations. +{% /callout %} + +{% /tab %} +{% /tabs %} + ## Custom Modes Create your own specialized assistants by defining tool access, file permissions, and behavior instructions. Custom modes help enforce team standards or create purpose-specific assistants. See [Custom Modes documentation](/docs/customize/custom-modes) for setup instructions. - - From 064a1f0fc6f8f7a0d9d850f44b6970258f65b790 Mon Sep 17 00:00:00 2001 From: Josh Lambert Date: Tue, 24 Mar 2026 05:08:17 -0400 Subject: [PATCH 017/308] docs(kilo-docs): add platform tabs to code-with-ai features pages Add VSCode (Pre-release) and CLI tabs to 7 features pages: - autocomplete/index.md: FIM with Codestral, snooze, Copilot detection - code-actions.md: Pre-release actions, terminal context menu, AM integration - git-commit-generation.md: SCM button via CLI backend - browser-use.md: Playwright MCP approach, browser settings per platform - checkpoints.md: Snapshot config, CLI revert/unrevert, per-file revert - platforms/vscode.md: Feature comparison between VSCode and Pre-release - platforms/cli.md: Fix stale MCP link, add platform:next frontmatter Part of the docs platform tabs effort (PR 4 of 8). Depends on #7497 for infrastructure. --- .../features/autocomplete/index.md | 42 ++++++++ .../code-with-ai/features/browser-use.md | 96 +++++++++++++++++++ .../code-with-ai/features/checkpoints.md | 64 ++++++++++++- .../code-with-ai/features/code-actions.md | 34 +++++++ .../features/git-commit-generation.md | 17 ++++ .../pages/code-with-ai/platforms/cli.md | 3 +- .../pages/code-with-ai/platforms/vscode.md | 54 +++++++++++ 7 files changed, 304 insertions(+), 6 deletions(-) diff --git a/packages/kilo-docs/pages/code-with-ai/features/autocomplete/index.md b/packages/kilo-docs/pages/code-with-ai/features/autocomplete/index.md index 311ae3e0b87..42c6ebb7afe 100644 --- a/packages/kilo-docs/pages/code-with-ai/features/autocomplete/index.md +++ b/packages/kilo-docs/pages/code-with-ai/features/autocomplete/index.md @@ -7,6 +7,9 @@ description: "AI-powered code autocompletion in Kilo Code" Kilo Code's autocomplete feature provides intelligent code suggestions and completions while you're typing, helping you write code faster and more efficiently. It offers both automatic and manual triggering options. +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ## How Autocomplete Works Autocomplete analyzes your code context and provides: @@ -86,6 +89,45 @@ If using Cursor, go to **Settings** > **Cursor Settings** > **Tab**, and toggle {% image src="https://github.com/user-attachments/assets/fd2eeae2-f770-40ca-8a72-a9d5a1c17d47" alt="Disable Cursor autocomplete" width="800" caption="Disable Cursor autocomplete" /%} +{% /tab %} +{% tab label="VSCode" %} + +{% callout type="info" %} +Autocomplete is an **extension-only** feature. It is not available in the CLI/TUI. +{% /callout %} + +## How Autocomplete Works + +The new extension uses **Fill-in-the-Middle (FIM)** completion powered by Codestral (`mistralai/codestral-2508`). It analyzes the code before and after your cursor to generate contextually accurate inline suggestions. + +## Triggering Options + +### Auto-trigger + +Autocomplete is **enabled by default** and automatically shows inline suggestions as you type. Suggestions appear as ghost text that you can accept with `Tab`. + +### Trigger on keybinding (Cmd+L) + +Press `Cmd+L` (Mac) or `Ctrl+L` (Windows/Linux) to manually request a completion at your cursor position. + +## Status Bar + +The extension displays an **autocomplete status indicator** in the VS Code status bar, including: + +- Current autocomplete state (active/snoozed) +- Cumulative cost tracking for autocomplete requests + +### Snooze / Unsnooze + +You can temporarily disable autocomplete by clicking the status bar item to **snooze** it. Click again to **unsnooze** and re-enable suggestions. + +## Copilot Conflict Detection + +The new extension automatically detects if **GitHub Copilot** inline suggestions are enabled and warns you about potential conflicts. Disable Copilot's inline completions for the best experience with Kilo Code autocomplete. + +{% /tab %} +{% /tabs %} + ## Best Practices 1. **Balance speed and quality**: Faster models provide quicker suggestions but may be less accurate diff --git a/packages/kilo-docs/pages/code-with-ai/features/browser-use.md b/packages/kilo-docs/pages/code-with-ai/features/browser-use.md index 8255cf275b6..34e0c5d8fd1 100644 --- a/packages/kilo-docs/pages/code-with-ai/features/browser-use.md +++ b/packages/kilo-docs/pages/code-with-ai/features/browser-use.md @@ -13,6 +13,9 @@ Browser Use requires an advanced agentic model. It is typically most reliable wi ## How Browser Use Works +{% tabs %} +{% tab label="VSCode (Legacy)" %} + By default, Kilo Code uses a built-in browser that: - Launches automatically when you ask Kilo to visit a website @@ -22,6 +25,35 @@ By default, Kilo Code uses a built-in browser that: All of this happens directly within VS Code, with no setup required. +{% /tab %} +{% tab label="VSCode & CLI" %} + +Kilo Code uses [Playwright](https://playwright.dev/) via MCP (`@playwright/mcp@latest`) for browser automation. The Playwright MCP server is registered dynamically as `kilo-playwright`. + +**In the VS Code extension**, browser automation is auto-configured: + +- Toggle it on from **Settings → Browser** tab +- Configure `browserAutomation.headless` and `browserAutomation.useSystemChrome` settings +- Playwright auto-downloads Chromium on first use + +**In CLI-only mode**, you need to manually add the MCP server to your `kilo.json` configuration: + +```json +{ + "mcp": { + "playwright": { + "type": "local", + "command": ["npx", "-y", "@playwright/mcp@latest"] + } + } +} +``` + +Once configured, Playwright downloads Chromium automatically on first use. + +{% /tab %} +{% /tabs %} + ## Using Browser Use A typical browser interaction follows this pattern: @@ -39,6 +71,9 @@ For example: ## How Browser Actions Work +{% tabs %} +{% tab label="VSCode (Legacy)" %} + The browser_action tool controls a browser instance that returns screenshots and console logs after each action, allowing you to see the results of interactions. Key characteristics: @@ -59,8 +94,38 @@ Key characteristics: | `scroll_up` | Scrolls up by one page | Returning to previous content | | `close` | Closes the browser | Ending a browser session | +{% /tab %} +{% tab label="VSCode & CLI" %} + +The Playwright MCP server provides a set of browser tools for interacting with web pages. These tools return screenshots and accessibility snapshots after each action. + +Key characteristics: + +- The browser launches automatically when a browser tool is invoked +- Multiple browser tools can be used in sequence +- Screenshots are captured after each action for visual feedback + +### Available Browser Tools + +| Tool | Description | When to Use | +| -------------------- | ----------------------------------- | ------------------------------------- | +| `browser_navigate` | Navigates to a URL | Opening a web page | +| `browser_click` | Clicks an element on the page | Interacting with buttons, links, etc. | +| `browser_type` | Types text into an input element | Filling forms, search boxes | +| `browser_screenshot` | Captures a screenshot of the page | Inspecting visual state | +| `browser_scroll` | Scrolls the page or a specific area | Viewing content above or below | +| `browser_hover` | Hovers over an element | Revealing tooltips or menus | +| `browser_select` | Selects an option from a dropdown | Choosing from select elements | +| `browser_drag` | Drags an element to a target | Drag-and-drop interactions | + +{% /tab %} +{% /tabs %} + ## Browser Use Settings +{% tabs %} +{% tab label="VSCode (Legacy)" %} + {% callout type="info" title="Default Browser Settings" %} - **Enable browser tool**: Enabled @@ -161,3 +226,34 @@ Connect to a visible Chrome window to observe Kilo's interactions in real-time: ```bash google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug --no-first-run ``` + +{% /tab %} +{% tab label="VSCode & CLI" %} + +### VS Code Extension Settings + +In the VS Code extension, browser automation settings are available under **Settings → Browser**: + +- **Enable browser automation**: Toggle to enable or disable Playwright browser automation +- **Headless mode** (`browserAutomation.headless`): Run the browser without a visible window (default: disabled) +- **Use system Chrome** (`browserAutomation.useSystemChrome`): Use your installed Chrome instead of the bundled Chromium + +### CLI Configuration + +In CLI-only mode, browser automation requires manual MCP configuration in your `kilo.json` file: + +```json +{ + "mcp": { + "playwright": { + "type": "local", + "command": ["npx", "-y", "@playwright/mcp@latest"] + } + } +} +``` + +No additional settings are needed — the Playwright MCP server manages the browser lifecycle automatically. Chromium is downloaded on first use. + +{% /tab %} +{% /tabs %} diff --git a/packages/kilo-docs/pages/code-with-ai/features/checkpoints.md b/packages/kilo-docs/pages/code-with-ai/features/checkpoints.md index 377f9dc108e..08c4abd7b79 100644 --- a/packages/kilo-docs/pages/code-with-ai/features/checkpoints.md +++ b/packages/kilo-docs/pages/code-with-ai/features/checkpoints.md @@ -27,6 +27,9 @@ Checkpoints let you: ## Configuration Options +{% tabs %} +{% tab label="VSCode (Legacy)" %} + Access checkpoint settings in Kilo Code settings under the "Checkpoints" section: 1. Open Settings by clicking the gear icon {% codicon name="gear" /%} → Checkpoints @@ -34,6 +37,25 @@ Access checkpoint settings in Kilo Code settings under the "Checkpoints" section {% image src="/docs/img/checkpoints/checkpoints.png" alt="Checkpoint settings in Kilo Code configuration" width="500" /%} +{% /tab %} +{% tab label="VSCode & CLI" %} + +Checkpoints are controlled by the `snapshot` boolean: + +- **Settings UI**: Open Settings → Checkpoints tab and toggle the snapshot setting +- **Config file**: Set `"snapshot": true` or `"snapshot": false` in your `kilo.json` configuration file + +```json +{ + "snapshot": true +} +``` + +When enabled, the system automatically captures snapshots at each step of a task. + +{% /tab %} +{% /tabs %} + ## How Checkpoints Work Kilo Code captures snapshots of your project's state using a shadow Git repository, separate from your main version control system. These snapshots, called checkpoints, automatically record changes throughout your AI-assisted workflow—whenever tasks begin, files change, or commands run. @@ -48,6 +70,9 @@ Checkpoints are stored as Git commits in the shadow repository, capturing: ## Working with Checkpoints +{% tabs %} +{% tab label="VSCode (Legacy)" %} + Checkpoints are integrated directly into your workflow through the chat interface. Checkpoints appear directly in your chat history in two forms: @@ -93,12 +118,34 @@ To restore a project to a previous checkpoint state: {% image src="/docs/img/checkpoints/checkpoints-9.png" alt="Confirmation dialog for restoring checkpoint with files & task" width="300" /%} -### Limitations and Considerations +{% /tab %} +{% tab label="VSCode & CLI" %} -- **Scope**: Checkpoints only capture changes made during active Kilo Code tasks -- **External changes**: Modifications made outside of tasks (manual edits, other tools) aren't included -- **Large files**: Very large binary files may impact performance -- **Unsaved work**: Restoration will overwrite any unsaved changes in your workspace +Checkpoints are captured automatically at each step of a task. The system calls `Snapshot.track()` at `start-step` and `finish-step` events, recording Git tree objects via `git write-tree`. + +### CLI TUI + +In the CLI terminal interface, checkpoints appear as revert points in the conversation. You can revert to any point by selecting the corresponding message. + +### Reverting Changes + +The new platform provides flexible revert capabilities: + +- **Full revert**: Use `SessionRevert.revert({ sessionID, messageID, partID })` to revert your workspace to any point in the conversation +- **Undo a revert**: Use `unrevert()` to restore the state before the last revert +- **Per-file revert**: `Snapshot.revert(patches)` can revert individual files via `git checkout -- `, allowing you to selectively undo changes to specific files while keeping others + +### Viewing Differences + +The system provides detailed diff capabilities: + +- `Snapshot.diff()` returns per-file diffs showing what changed at each step +- `Snapshot.diffFull()` returns full before/after file content for detailed review + +In the **Agent Manager** (VS Code extension), these diffs are displayed in a dedicated `DiffPanel` and `FullScreenDiffView`, providing a visual interface for reviewing all file changes made during a session. + +{% /tab %} +{% /tabs %} ## Technical Implementation @@ -183,6 +230,13 @@ Checkpoints do not support nested Git repositories. The working directory must b Operations are queued to prevent concurrent Git operations that might corrupt repository state. This ensures that rapid checkpoint operations complete safely even when requested in quick succession. +### Limitations and Considerations + +- **Scope**: Checkpoints only capture changes made during active Kilo Code tasks +- **External changes**: Modifications made outside of tasks (manual edits, other tools) aren't included +- **Large files**: Very large binary files may impact performance +- **Unsaved work**: Restoration will overwrite any unsaved changes in your workspace + ## Git Installation Checkpoints require Git to be installed on your system. The implementation uses the `simple-git` library, which relies on Git command-line tools to create and manage shadow repositories. diff --git a/packages/kilo-docs/pages/code-with-ai/features/code-actions.md b/packages/kilo-docs/pages/code-with-ai/features/code-actions.md index c36e900e7f6..323b1fe7127 100644 --- a/packages/kilo-docs/pages/code-with-ai/features/code-actions.md +++ b/packages/kilo-docs/pages/code-with-ai/features/code-actions.md @@ -7,6 +7,13 @@ description: "Quick code actions and refactoring with Kilo Code" Code Actions are a powerful feature of VS Code that provide quick fixes, refactorings, and other code-related suggestions directly within the editor. Kilo Code integrates with this system to offer AI-powered assistance for common coding tasks. +{% callout type="info" %} +Code Actions are a **VS Code extension feature** and are not available in the CLI/TUI. +{% /callout %} + +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ## What are Code Actions? Code Actions appear as a lightbulb icon (💡) in the editor gutter (the area to the left of the line numbers). They can also be accessed via the right-click context menu, or via keyboard shortcut. They are triggered when: @@ -90,4 +97,31 @@ You can customize the prompts used for each Code Action by modifying the "Suppor 3. **Edit the Prompts:** Modify the text in the text area for the prompt you want to customize. You can use placeholders like `${filePath}` and `${selectedText}` to include information about the current file and selection. 4. **Click "Done":** Save your changes. +{% /tab %} +{% tab label="VSCode" %} + +## Available Code Actions + +The new extension provides the same core code actions via the editor context menu and lightbulb: + +- **Add to Context:** Adds selected code (with file path and line numbers) to the active chat session. Keyboard shortcut: `Cmd+K Cmd+A` (Mac) or `Ctrl+K Ctrl+A` (Windows/Linux). +- **Explain Code:** Asks Kilo to explain the selected code. +- **Fix Code:** Asks Kilo to fix problems in the selected code. +- **Improve Code:** Asks Kilo to suggest improvements to the selected code. + +### Agent Manager Integration + +If the **Agent Manager** is active, code actions route to the current Agent Manager session rather than the sidebar chat. This allows code actions to work seamlessly within multi-session workflows. + +### Terminal Context Menu + +The new extension also adds code actions to the **terminal context menu**: + +- **Add Terminal Content:** Adds selected terminal output to the chat context. +- **Fix Command:** Asks Kilo to fix a failed terminal command. +- **Explain Command:** Asks Kilo to explain a terminal command or its output. + +{% /tab %} +{% /tabs %} + By using Kilo Code's Code Actions, you can quickly get AI-powered assistance directly within your coding workflow. This can save you time and help you write better code. diff --git a/packages/kilo-docs/pages/code-with-ai/features/git-commit-generation.md b/packages/kilo-docs/pages/code-with-ai/features/git-commit-generation.md index 31582101198..41fa60a17cd 100644 --- a/packages/kilo-docs/pages/code-with-ai/features/git-commit-generation.md +++ b/packages/kilo-docs/pages/code-with-ai/features/git-commit-generation.md @@ -53,6 +53,9 @@ Common types include: ## Configuration +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ### Customizing the Commit Template You can customize how commit messages are generated by modifying the prompt template: @@ -81,6 +84,20 @@ You can configure which API profile to use for commit message generation: Consider creating a dedicated [API configuration profile](/docs/ai-providers) with a faster, more cost-effective model specifically for commit message generation. {% /callout %} +{% /tab %} +{% tab label="VSCode" %} + +The new extension provides the same **SCM button** in the VS Code Source Control panel. Clicking it generates a commit message using the CLI backend's `client.commitMessage.generate()` API. + +Configuration is handled through the extension's settings or the shared `kilo.json` config file. + +{% callout type="info" %} +Git commit message generation is a **VS Code extension feature**. It is not available in the CLI/TUI. +{% /callout %} + +{% /tab %} +{% /tabs %} + ## Best Practices ### Staging Strategy diff --git a/packages/kilo-docs/pages/code-with-ai/platforms/cli.md b/packages/kilo-docs/pages/code-with-ai/platforms/cli.md index 04d6ff8e2a8..f6e80b3e11d 100644 --- a/packages/kilo-docs/pages/code-with-ai/platforms/cli.md +++ b/packages/kilo-docs/pages/code-with-ai/platforms/cli.md @@ -1,6 +1,7 @@ --- title: "Kilo CLI" description: "Using Kilo Code from the command line" +platform: next --- {% callout type="warning" title="Version Notice" %} @@ -167,7 +168,7 @@ Review your code locally before pushing — catch issues early without waiting f Configuration is managed through: - `/connect` command for provider setup (interactive) -- Config files in **`~/.config/kilo/`**: the CLI (Kilo CLI 1.0 from [Kilo-Org/kilocode](https://github.com/Kilo-Org/kilocode)) merges `config.json`, `opencode.json`, and `opencode.jsonc`. Use **`opencode.json`** (or `opencode.jsonc`) for provider, model, permission, and **MCP** settings. Restart the CLI after editing. See [Using MCP in the CLI](/docs/automate/mcp/using-in-cli) for MCP config format. +- Config files in **`~/.config/kilo/`**: the CLI (Kilo CLI 1.0 from [Kilo-Org/kilocode](https://github.com/Kilo-Org/kilocode)) merges `config.json`, `opencode.json`, and `opencode.jsonc`. Use **`opencode.json`** (or `opencode.jsonc`) for provider, model, permission, and **MCP** settings. Restart the CLI after editing. See [Using MCP in Kilo Code](/docs/automate/mcp/using-in-kilo-code) for MCP config format. - `kilo auth` for credential management ## Slash Commands diff --git a/packages/kilo-docs/pages/code-with-ai/platforms/vscode.md b/packages/kilo-docs/pages/code-with-ai/platforms/vscode.md index a06044fe304..8604b5f96f3 100644 --- a/packages/kilo-docs/pages/code-with-ai/platforms/vscode.md +++ b/packages/kilo-docs/pages/code-with-ai/platforms/vscode.md @@ -5,6 +5,60 @@ description: "Using Kilo Code in Visual Studio Code" # VS Code Extension +Kilo Code is available as two VS Code extensions: the **VSCode (Legacy)** extension and the current **VSCode** version built on the Kilo CLI core. + +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ## Installation {% partial file="install-vscode.md" /%} + +## Key Features + +- **Sidebar chat** — AI-powered chat panel in the VS Code activity bar +- **[Autocomplete](/docs/code-with-ai/features/autocomplete)** — Inline code completions as you type +- **[Code Actions](/docs/code-with-ai/features/code-actions)** — Explain, fix, and improve code from the editor context menu +- **[Modes](/docs/code-with-ai/agents/using-modes)** — Code, Ask, Architect, Debug, Orchestrator, and Review modes +- **[Custom Modes](/docs/customize/custom-modes)** — Define custom modes with `.kilocodemodes` YAML files +- **[MCP](/docs/automate/mcp/overview)** — Connect to MCP servers for extended capabilities +- **[Agent Manager](/docs/automate/agent-manager)** — Multi-session orchestration with git worktree isolation +- **[Git Commit Generation](/docs/code-with-ai/features/git-commit-generation)** — AI-powered commit messages from the Source Control panel +- **[Context Mentions](/docs/code-with-ai/agents/context-mentions)** — Reference files, URLs, diagnostics, and git changes with `@` +- **[Checkpoints](/docs/code-with-ai/features/checkpoints)** — Git-based snapshots for undo/redo + +{% /tab %} +{% tab label="VSCode" %} + +## Installation + +1. Open VS Code +2. Go to Extensions (`Ctrl+Shift+X` / `Cmd+Shift+X`) +3. Search for "Kilo Code" +4. Click the dropdown arrow next to **Install** and select **Install Pre-Release Version** + +The extension bundles its own CLI binary and spawns `kilo serve` as a background process. All communication happens over HTTP + SSE. + +## Key Features + +Key features include: + +- **SolidJS-based UI** — Rebuilt sidebar with a modern component architecture +- **[JSONC config files](/docs/getting-started/settings)** — Portable settings in `kilo.json` instead of VS Code settings +- **[Granular permissions](/docs/getting-started/settings/auto-approving-actions)** — Per-tool permission rules with glob patterns +- **[Agents](/docs/code-with-ai/agents/using-modes)** — Customizable agents (`.kilo/agents/*.md`) replacing the modes system +- **[Agent Manager](/docs/automate/agent-manager)** — Enhanced with diff panel, multi-model comparison, PR import, and code review annotations +- **[Autocomplete](/docs/code-with-ai/features/autocomplete)** — FIM-based with Codestral, status bar cost tracking +- **[Workflows](/docs/customize/workflows)** — Repeatable prompt templates as `.md` files +- **[Skills](/docs/customize/skills)** — Load specialized domain knowledge from SKILL.md files +- **[Custom Subagents](/docs/customize/custom-subagents)** — Define specialized sub-agents for the `task` tool +- **Open in Tab** — Pop the chat out into a full editor tab +- **Sub-Agent Viewer** — Read-only panels for viewing child agent sessions +- **Legacy Migration** — Automatic migration wizard for VSCode extension settings + +## Shared Settings + +The extension shares its configuration with the CLI. Settings in `~/.config/kilo/kilo.json` (global) and `./kilo.json` (project) apply to both the CLI and the extension. + +{% /tab %} +{% /tabs %} From f1b606a23c1c090447994ffb09b8ab4c34e1c846 Mon Sep 17 00:00:00 2001 From: Josh Lambert Date: Tue, 24 Mar 2026 05:18:39 -0400 Subject: [PATCH 018/308] docs(kilo-docs): add platform tabs to customize pages Add VSCode (Pre-release) and CLI tabs to 7 customize pages: - custom-modes.md: Agents system, .md frontmatter format, config file format, examples, migration, troubleshooting (massive - 597 lines added) - custom-rules.md: .kilo/rules/ directory, instructions config key - custom-instructions.md: Tabbed instruction methods per platform - agents-md.md: Updated for new agent file format - skills.md: SKILL.md files, skill loading from .kilo/skills/ - context/kilocodeignore.md: Tabbed ignore file configuration - context/context-condensing.md: Tabbed context management Critical fix applied: - Permission YAML format corrected from action-as-key (allow: '*.md') to pattern-as-key ('*.md': 'allow') matching the actual config schema in config.ts:713 (PermissionObject = z.record(string, PermissionAction)) Part of the docs platform tabs effort (PR 5 of 8). Depends on #7497 for infrastructure. --- packages/kilo-docs/lib/nav/customize.ts | 5 +- .../kilo-docs/pages/customize/agents-md.md | 40 +- .../customize/context/codebase-indexing.md | 1 + .../customize/context/context-condensing.md | 101 ++- .../pages/customize/context/kilocodeignore.md | 108 +++- .../pages/customize/context/large-projects.md | 1 + .../pages/customize/custom-instructions.md | 158 ++++- .../kilo-docs/pages/customize/custom-modes.md | 597 +++++++++++++++++- .../kilo-docs/pages/customize/custom-rules.md | 233 ++++++- .../pages/customize/custom-subagents.md | 1 + packages/kilo-docs/pages/customize/skills.md | 250 ++++++-- .../kilo-docs/pages/customize/workflows.md | 1 + 12 files changed, 1409 insertions(+), 87 deletions(-) diff --git a/packages/kilo-docs/lib/nav/customize.ts b/packages/kilo-docs/lib/nav/customize.ts index ca3760e1b5f..7687bad119f 100644 --- a/packages/kilo-docs/lib/nav/customize.ts +++ b/packages/kilo-docs/lib/nav/customize.ts @@ -20,9 +20,10 @@ export const CustomizeNav: NavSection[] = [ { href: "/customize/custom-subagents", children: "Custom Subagents", + platform: "new", }, { href: "/customize/agents-md", children: "agents.md" }, - { href: "/customize/workflows", children: "Workflows" }, + { href: "/customize/workflows", children: "Workflows", platform: "new" }, { href: "/customize/skills", children: "Skills" }, { href: "/customize/prompt-engineering", @@ -36,6 +37,7 @@ export const CustomizeNav: NavSection[] = [ { href: "/customize/context/codebase-indexing", children: "Codebase Indexing", + platform: "legacy", }, { href: "/customize/context/context-condensing", @@ -48,6 +50,7 @@ export const CustomizeNav: NavSection[] = [ { href: "/customize/context/large-projects", children: "Large Projects", + platform: "legacy", }, ], }, diff --git a/packages/kilo-docs/pages/customize/agents-md.md b/packages/kilo-docs/pages/customize/agents-md.md index d451b5e7a7d..ef47a81316a 100644 --- a/packages/kilo-docs/pages/customize/agents-md.md +++ b/packages/kilo-docs/pages/customize/agents-md.md @@ -18,7 +18,7 @@ If you'd like to migrate your memory bank content to AGENTS.md: 1. Examine the contents in `.kilocode/rules/memory-bank/` 2. Move that content into your project's `AGENTS.md` file (or ask Kilo to do it for you) -{% /callout %} + {% /callout %} ## What is AGENTS.md? @@ -138,6 +138,9 @@ When you start a task in Kilo Code: ### Interaction with Other Rules +{% tabs %} +{% tab label="VSCode (Legacy)" %} + AGENTS.md works alongside Kilo Code's other configuration systems: | Feature | Scope | Location | Purpose | Priority | @@ -148,9 +151,28 @@ AGENTS.md works alongside Kilo Code's other configuration systems: | **[Global Custom Rules](/docs/customize/custom-rules)** | Global | `~/.kilocode/rules/` | Global Kilo Code rules | 4 | | **[Custom Instructions](/docs/customize/custom-instructions)** | Global | IDE settings | Personal preferences across all projects | 5 (Lowest) | +{% /tab %} +{% tab label="VSCode & CLI" %} + +In the new platform, AGENTS.md is loaded alongside other instruction sources. The CLI also supports `.claude/` and `.agents/` directories for compatibility with other tools. + +| Source | Scope | Location | Priority | +| ------------------------------------------------ | --------- | ----------------------------------------- | ---------------- | +| **Agent prompt** | Per-agent | `agent..prompt` in config | 1 (Highest) | +| **[Instructions](/docs/customize/custom-rules)** | Project | `instructions` key in project `kilo.json` | 2 | +| **AGENTS.md** | Project | `AGENTS.md` at project root | 3 | +| **[Instructions](/docs/customize/custom-rules)** | Global | `instructions` key in global `kilo.json` | 4 | +| **[Skills](/docs/customize/skills)** | Both | `.kilo/skills/`, config `skills` key | Loaded on demand | + +{% /tab %} +{% /tabs %} + ### Enabling/Disabling AGENTS.md -AGENTS.md support is **enabled by default** in Kilo Code. To disable it, edit `settings.json`: +{% tabs %} +{% tab label="VSCode (Legacy)" %} + +AGENTS.md support is **enabled by default**. To disable it, edit `settings.json`: ```json { @@ -158,6 +180,20 @@ AGENTS.md support is **enabled by default** in Kilo Code. To disable it, edit `s } ``` +{% /tab %} +{% tab label="VSCode & CLI" %} + +AGENTS.md is loaded automatically. To disable external skill directories (`.claude/skills/`, `.agents/skills/`), set the environment variable: + +```bash +export KILO_DISABLE_EXTERNAL_SKILLS=true +``` + +AGENTS.md itself cannot be individually disabled — it is always loaded if present. To override its instructions, use higher-priority sources like the `instructions` config key or agent-specific prompts. + +{% /tab %} +{% /tabs %} + ## Related Features - **[Custom Rules](/docs/customize/custom-rules)** - Kilo Code-specific rules with more control diff --git a/packages/kilo-docs/pages/customize/context/codebase-indexing.md b/packages/kilo-docs/pages/customize/context/codebase-indexing.md index ff6e1312f01..3f38b01a76d 100644 --- a/packages/kilo-docs/pages/customize/context/codebase-indexing.md +++ b/packages/kilo-docs/pages/customize/context/codebase-indexing.md @@ -1,6 +1,7 @@ --- title: "Codebase Indexing" description: "Index your codebase for improved AI understanding" +platform: legacy --- # Codebase Indexing diff --git a/packages/kilo-docs/pages/customize/context/context-condensing.md b/packages/kilo-docs/pages/customize/context/context-condensing.md index 9ab1a2d2a8b..0dfa3136470 100644 --- a/packages/kilo-docs/pages/customize/context/context-condensing.md +++ b/packages/kilo-docs/pages/customize/context/context-condensing.md @@ -17,9 +17,12 @@ Every AI model has a maximum context window - a limit on how much text it can pr - Higher API costs due to increased token usage - Eventually hitting the context limit and being unable to continue +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ## The Solution: Intelligent Condensing -Context Condensing solves this problem by creating a concise summary of your conversation that captures: +**Context Condensing** solves this problem by creating a concise summary of your conversation that captures: - The original task or goal - Key decisions made during the session @@ -63,20 +66,6 @@ Context Condensing uses an AI model to generate summaries. You can configure whi You can configure context condensing thresholds and behavior on a per-profile basis, allowing different settings for different projects or use cases. -## Best Practices - -### When to Condense - -- **Long sessions**: If you've been working for an extended period on a complex task -- **Before major transitions**: When switching to a different aspect of your project -- **When prompted**: When Kilo Code suggests condensing due to context limits - -### Maintaining Context Quality - -- **Be specific in your initial task**: A clear task description helps create better summaries -- **Use AGENTS.md**: Combine with [AGENTS.md](/docs/customize/agents-md) for persistent project context that doesn't need to be condensed -- **Review the summary**: After condensing, the summary is visible in your chat history - ## Troubleshooting ### Context Condensing Error @@ -95,6 +84,88 @@ If the condensed summary doesn't capture important details: - Use clear, specific language when describing your tasks - Important context can be reinforced after condensing by reminding Kilo Code of key details +{% /tab %} +{% tab label="VSCode & CLI" %} + +## The Solution: Auto-Compaction + +The new platform uses a **Compaction** system to manage context automatically. When your conversation approaches the token limit, compaction kicks in and produces a structured summary that captures: + +- The overall goal of the session +- Key discoveries made along the way +- What has been accomplished so far +- Files that were modified + +This summary replaces the earlier conversation history, freeing up context window space while maintaining continuity in your work. + +## How Compaction Works + +### Automatic Compaction + +Compaction triggers automatically when the conversation reaches the `usableWindow` token threshold. The full conversation history is sent to a dedicated **compaction agent**, which produces a structured summary. This happens in the background without interrupting your workflow. + +### Context Pruning + +In addition to compaction, the system can **prune** old tool outputs to reclaim context space incrementally. Tool results older than a 40,000-token recency window are replaced with `"[Old tool result content cleared]"`. This is a lighter-weight mechanism that runs alongside full compaction. + +### Manual Compaction + +You can also trigger compaction manually: + +- **CLI TUI**: Press `c` to compact the current session +- **Extension Webview**: Send a `CompactRequest` message to trigger compaction + +{% callout type="info" %} +There is no `/condense` chat command on the new platform. Use the keybinding or message-based invocation instead. +{% /callout %} + +### The Compaction Process + +When compaction is triggered: + +1. **Threshold Check**: The system detects that context usage has reached the `usableWindow` limit +2. **Agent Summarization**: The full conversation history is sent to a dedicated compaction agent +3. **Structured Summary**: The agent produces a summary covering the goal, discoveries, accomplishments, and modified files +4. **Replacement**: The detailed history is replaced with the compacted summary +5. **Continuation**: You continue working with the freed-up context space + +## Configuration Options + +Compaction is configured in your `kilo.json` file: + +```jsonc +{ + "compaction": { + "auto": true, // Enable or disable automatic compaction + "reserved": 4096, // Number of tokens to reserve (keep free) after compaction + "prune": true, // Enable pruning of old tool outputs beyond the recency window + }, +} +``` + +| Option | Type | Description | +| --------------------- | ------- | ------------------------------------------------------------------------ | +| `compaction.auto` | boolean | Enable or disable automatic compaction when the context threshold is hit | +| `compaction.reserved` | number | Number of tokens to reserve after compaction | +| `compaction.prune` | boolean | Enable pruning of old tool outputs outside the 40K token recency window | + +{% /tab %} +{% /tabs %} + +## Best Practices + +### When to Condense + +- **Long sessions**: If you've been working for an extended period on a complex task +- **Before major transitions**: When switching to a different aspect of your project +- **When prompted**: When Kilo Code suggests condensing or compaction due to context limits + +### Maintaining Context Quality + +- **Be specific in your initial task**: A clear task description helps create better summaries +- **Use AGENTS.md**: Combine with [AGENTS.md](/docs/customize/agents-md) for persistent project context that doesn't need to be condensed +- **Review the summary**: After condensing or compaction, the summary is visible in your chat history + ## Related Features - [AGENTS.md](/docs/customize/agents-md) - Persistent context storage across sessions diff --git a/packages/kilo-docs/pages/customize/context/kilocodeignore.md b/packages/kilo-docs/pages/customize/context/kilocodeignore.md index c929aab46ff..5000534b31e 100644 --- a/packages/kilo-docs/pages/customize/context/kilocodeignore.md +++ b/packages/kilo-docs/pages/customize/context/kilocodeignore.md @@ -13,6 +13,9 @@ If no `.kilocodeignore` file exists, Kilo Code can access all files in the works ## Quick Start +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. Create a `.kilocodeignore` file at the root of your project. 2. Add patterns for files or folders you want Kilo Code to avoid. 3. Save the file. Kilo Code will pick up the changes automatically. @@ -34,6 +37,35 @@ coverage/ !secrets/README.md ``` +{% /tab %} +{% tab label="VSCode & CLI" %} + +The primary mechanism for controlling file access is the **permission system** in `kilo.json`. You define tool-level permissions with glob patterns: + +```json +{ + "permission": { + "read": { "*.env": "deny", "*": "allow" }, + "edit": { "dist/**": "deny", "*": "allow" } + } +} +``` + +If you have an existing `.kilocodeignore` file, it is still supported. The **IgnoreMigrator** automatically converts `.kilocodeignore` patterns into permission `deny` rules on `read` and `edit` tools, so your existing rules continue to work without manual changes. + +You can also exclude paths from the file watcher separately using `config.watcher.ignore`: + +```json +{ + "watcher": { + "ignore": ["tmp/**", "logs/**"] + } +} +``` + +{% /tab %} +{% /tabs %} + ## Pattern Rules `.kilocodeignore` follows the same rules as `.gitignore`: @@ -47,6 +79,9 @@ Patterns are evaluated relative to the workspace root. ## What It Affects +{% tabs %} +{% tab label="VSCode (Legacy)" %} + Kilo Code checks `.kilocodeignore` before accessing files in tools like: - [`read_file`](/docs/automate/tools/read-file) @@ -58,17 +93,82 @@ Kilo Code checks `.kilocodeignore` before accessing files in tools like: If a file is blocked, Kilo Code will return an "access denied" message and suggest updating your `.kilocodeignore` rules. -## Visibility in Lists +{% /tab %} +{% tab label="VSCode & CLI" %} + +File access is controlled through **permission-based access control**. Each tool (`read`, `edit`, `glob`, `grep`, `write`, `bash`, etc.) has its own permission rules evaluated against glob patterns. + +In addition to your explicit permission rules: + +- **Hardcoded directory ignores** — 27 directories are always skipped (e.g. `node_modules`, `.git`, `dist`, `build`, `.cache`, `__pycache__`, `vendor`, and others). +- **Hardcoded file pattern ignores** — 11 file patterns are always skipped (e.g. lock files, binary artifacts). +- **`.gitignore` and `.ignore` files** are also respected when listing and searching files. + +If a file is denied by a permission rule, the tool will report that access was blocked. + +{% /tab %} +{% /tabs %} + +## Configuration Details + +{% tabs %} +{% tab label="VSCode (Legacy)" %} + +### Visibility in Lists By default, ignored files are hidden from file lists. You can show them with a lock icon by enabling: Settings -> Context -> **Show .kilocodeignore'd files in lists and searches** +{% /tab %} +{% tab label="VSCode & CLI" %} + +### Permission Rules + +Permission rules are defined per-tool in `kilo.json`. Patterns are evaluated in order — the last matching rule wins: + +```json +{ + "permission": { + "read": { + "*.env": "deny", + "secrets/**": "deny", + "*": "allow" + }, + "edit": { + "dist/**": "deny", + "*.lock": "deny", + "*": "allow" + } + } +} +``` + +### Migrating from .kilocodeignore + +If you already have a `.kilocodeignore` file, you don't need to do anything — the IgnoreMigrator reads your existing patterns and applies them as `deny` rules on `read` and `edit` tools automatically. You can optionally move your rules into `kilo.json` for more granular control (e.g. denying edits but allowing reads). + +### File Watcher Exclusions + +The `config.watcher.ignore` setting controls which paths the file watcher skips. This is separate from tool permissions and only affects change detection: + +```json +{ + "watcher": { + "ignore": ["tmp/**", "logs/**", ".build/**"] + } +} +``` + +{% /tab %} +{% /tabs %} + ## Checkpoints vs .kilocodeignore -Checkpoint tracking is separate from file access rules. Files blocked by `.kilocodeignore` can still be checkpointed if they are not excluded by `.gitignore`. See the [Checkpoints](/docs/code-with-ai/features/checkpoints) documentation for details. +Checkpoint tracking is separate from file access rules. Files blocked by `.kilocodeignore` or permission rules can still be checkpointed if they are not excluded by `.gitignore`. See the [Checkpoints](/docs/code-with-ai/features/checkpoints) documentation for details. ## Troubleshooting -- **Kilo can't access a file you want:** Remove or narrow the matching rule in `.kilocodeignore`. -- **A file still appears in lists:** Check the setting that shows ignored files in lists and searches. +- **Kilo can't access a file you want:** Remove or narrow the matching rule in `.kilocodeignore` (classic) or adjust the permission rules in `kilo.json` (new extension & CLI). +- **A file still appears in lists:** In the classic extension, check the setting that shows ignored files in lists and searches. In the new extension & CLI, verify your permission and watcher ignore configuration. +- **`.kilocodeignore` patterns not working in the new platform:** Ensure the file is at the workspace root. The IgnoreMigrator reads it automatically — check that your patterns use valid `.gitignore` syntax. diff --git a/packages/kilo-docs/pages/customize/context/large-projects.md b/packages/kilo-docs/pages/customize/context/large-projects.md index a0aab196f0a..101fb1621b6 100644 --- a/packages/kilo-docs/pages/customize/context/large-projects.md +++ b/packages/kilo-docs/pages/customize/context/large-projects.md @@ -1,6 +1,7 @@ --- title: "Large Projects" description: "Best practices for using Kilo Code with large codebases" +platform: legacy --- # Working with Large Projects diff --git a/packages/kilo-docs/pages/customize/custom-instructions.md b/packages/kilo-docs/pages/customize/custom-instructions.md index b7ea7b7d8fb..4682608ba1b 100644 --- a/packages/kilo-docs/pages/customize/custom-instructions.md +++ b/packages/kilo-docs/pages/customize/custom-instructions.md @@ -5,18 +5,21 @@ description: "Provide custom instructions to guide Kilo Code" # Custom Instructions -Custom Instructions allow you to personalize how Kilo Code behaves, providing specific guidance that shapes responses, coding style, and decision-making processes. +Custom Instructions allow you to personalize how Kilo Code behaves, providing specific guidance that shapes responses, coding style, and decision-making processes. Both the **VSCode** and **VSCode & CLI** versions support custom instructions, though the mechanisms differ. ## What Are Custom Instructions? Custom Instructions define specific Extension behaviors, preferences, and constraints beyond Kilo's basic role definition. Examples include coding style, documentation standards, testing requirements, and workflow guidelines. +{% tabs %} +{% tab label="VSCode (Legacy)" %} + +## Setting Custom Instructions + {% callout type="info" title="Custom Instructions vs Rules" %} Custom Instructions are IDE-wide and are applied across all workspaces and maintain your preferences regardless of which project you're working on. Unlike Instructions, [Custom Rules](/docs/customize/custom-rules) are project specific and allow you to setup workspace-based ruleset. {% /callout %} -## Setting Custom Instructions - **How to set them:** {% image src="/docs/img/custom-instructions/custom-instructions.png" alt="Kilo Code Modes tab showing global custom instructions interface" width="600" caption="Kilo Code Modes tab showing global custom instructions interface" /%} @@ -37,8 +40,9 @@ Mode-specific instructions can be set using the Modes Tab * **Save Changes:** Click "Done" to save your changes {% callout type="info" title="Global Mode Rules" %} - If the mode itself is global (not workspace-specific), any custom instructions you set for it will also apply globally for that mode across all workspaces. - {% /callout %} + +If the mode itself is global (not workspace-specific), any custom instructions you set for it will also apply globally for that mode across all workspaces. +{% /callout %} ## Mode-Specific Instructions from Files @@ -51,6 +55,150 @@ For version-controlled mode instructions, use the mode rules file paths document Older naming like `.clinerules-{mode-slug}` is not the recommended path for current Kilo mode-specific instructions. {% /callout %} +{% /tab %} +{% tab label="VSCode" %} + +The new extension provides multiple layers of instruction configuration — from per-agent prompts in the Settings UI to auto-discovered files in your project and global config. + +## Per-Agent Prompts + +Each agent can have its own custom prompt configured through the settings UI: + +1. Open **Settings → Agent Behaviour → Agents** subtab +2. Select the agent you want to customize +3. Enter your instructions in the markdown text area under the agent's `prompt` field +4. Save your changes + +These prompts are injected into the agent's system prompt and apply across all sessions using that agent. + +## Instruction Files + +Kilo automatically discovers instruction files at your project root and in parent directories (via `findUp`). The following filenames are recognized: + +- **`AGENTS.md`** — The primary instruction file for Kilo +- **`CLAUDE.md`** — Also supported for compatibility +- **`CONTEXT.md`** — Additional project context + +Place any of these files at your project root to provide project-wide instructions to the agent. + +### Global Instructions + +For instructions that apply across all your projects, place an `AGENTS.md` file in your global config directory: + +- **Kilo:** `~/.config/kilo/AGENTS.md` +- **Claude-compatible:** `~/.claude/CLAUDE.md` + +Global instructions are loaded before project-level instructions and apply to every session. + +### Per-Directory Instructions + +You can place `AGENTS.md` files in any subdirectory of your project. These are loaded dynamically — when the agent's Read tool accesses a file in that directory, the corresponding `AGENTS.md` is discovered and its contents are injected into the conversation as `` tags. + +This is useful for providing context-specific guidance for different parts of a monorepo or project. + +## Additional Instruction Sources + +The `config.instructions` setting accepts an array of paths, globs, or URLs pointing to additional instruction files. You can manage these in **Settings → Agent Behaviour → Rules** subtab. + +```yaml +# Examples of instruction sources +instructions: + - ./docs/coding-standards.md + - ./teams/frontend-rules.md + - https://example.com/team-instructions.md +``` + +{% callout type="info" title="URL-Based Instructions" %} +URL-based instruction sources are fetched at session start with a 5-second timeout. If the URL is unreachable, the instruction source is silently skipped. +{% /callout %} + +## Legacy `.kilocoderules` Support + +If your project contains `.kilocoderules` files from the VSCode extension, these are still loaded via auto-migration. However, migrating to `AGENTS.md` is recommended for new projects. + +{% /tab %} +{% tab label="CLI" %} + +The CLI provides multiple layers of instruction configuration — from per-agent prompts in agent definition files to auto-discovered files in your project and global config. + +## Per-Agent Prompts + +Each agent can have its own custom prompt defined in its `.md` file (the markdown body) or via the `agent..prompt` key in `kilo.json`: + +```jsonc +// kilo.json +{ + "agent": { + "code": { + "prompt": "You are a Python specialist. Follow PEP8 strictly.", + }, + }, +} +``` + +Or as the markdown body in `.kilo/agents/code.md`: + +```markdown +--- +description: Python specialist +--- + +You are a Python specialist. Follow PEP8 strictly. +``` + +These prompts are injected into the agent's system prompt and apply across all sessions using that agent. + +## Instruction Files + +Kilo automatically discovers instruction files at your project root and in parent directories (via `findUp`). The following filenames are recognized: + +- **`AGENTS.md`** — The primary instruction file for Kilo +- **`CLAUDE.md`** — Also supported for compatibility +- **`CONTEXT.md`** — Additional project context + +Place any of these files at your project root to provide project-wide instructions to the agent. + +### Global Instructions + +For instructions that apply across all your projects, place an `AGENTS.md` file in your global config directory: + +- **Kilo:** `~/.config/kilo/AGENTS.md` +- **Claude-compatible:** `~/.claude/CLAUDE.md` + +Global instructions are loaded before project-level instructions and apply to every session. + +### Per-Directory Instructions + +You can place `AGENTS.md` files in any subdirectory of your project. These are loaded dynamically — when the agent's Read tool accesses a file in that directory, the corresponding `AGENTS.md` is discovered and its contents are injected into the conversation as `` tags. + +This is useful for providing context-specific guidance for different parts of a monorepo or project. + +## Additional Instruction Sources + +The `config.instructions` setting accepts an array of paths, globs, or URLs pointing to additional instruction files. Configure these in your `kilo.json`: + +```jsonc +// kilo.json +{ + "instructions": [ + "./docs/coding-standards.md", + "./teams/frontend-rules.md", + "https://example.com/team-instructions.md", + ], +} +``` + +{% callout type="info" title="URL-Based Instructions" %} +URL-based instruction sources are fetched at session start with a 5-second timeout. If the URL is unreachable, the instruction source is silently skipped. +{% /callout %} + +## Legacy `.kilocoderules` Support + +If your project contains `.kilocoderules` files from the VSCode extension, these are still loaded via auto-migration. However, migrating to `AGENTS.md` is recommended for new projects. + +{% /tab %} +{% /tabs %} + ## Related Features - [Custom Modes](/docs/customize/custom-modes) diff --git a/packages/kilo-docs/pages/customize/custom-modes.md b/packages/kilo-docs/pages/customize/custom-modes.md index 86bcc17a2c4..7713e4e2c39 100644 --- a/packages/kilo-docs/pages/customize/custom-modes.md +++ b/packages/kilo-docs/pages/customize/custom-modes.md @@ -7,10 +7,6 @@ description: "Create and configure custom modes in Kilo Code" Kilo Code allows you to create **custom modes** to tailor Kilo's behavior to specific tasks or workflows. Custom modes can be either **global** (available across all projects) or **project-specific** (defined within a single project). -## Sticky Models for Efficient Workflow - -Each mode—including custom ones—features **Sticky Models**. This means Kilo Code automatically remembers and selects the last model you used with a particular mode. This lets you assign different preferred models to different tasks without constant reconfiguration, as Kilo switches between models when you change modes. - ## Why Use Custom Modes? - **Specialization:** Create modes optimized for specific tasks, like "Documentation Writer," "Test Engineer," or "Refactoring Expert" @@ -18,6 +14,13 @@ Each mode—including custom ones—features **Sticky Models**. This means Kilo - **Experimentation:** Safely experiment with different prompts and configurations without affecting other modes - **Team Collaboration:** Share custom modes with your team to standardize workflows +{% tabs %} +{% tab label="VSCode (Legacy)" %} + +## Sticky Models for Efficient Workflow + +Each mode—including custom ones—features **Sticky Models**. This means Kilo Code automatically remembers and selects the last model you used with a particular mode. This lets you assign different preferred models to different tasks without constant reconfiguration, as Kilo switches between models when you change modes. + {% callout type="tip" %} **Keep custom modes on track:** Limit the types of files that they're allowed to edit using the `fileRegex` option in the `groups` configuration. This prevents modes from accidentally modifying files outside their intended scope. {% /callout %} @@ -135,8 +138,6 @@ If you see both YAML and JSON mode files, this is usually from legacy configurat YAML is now the preferred format for defining custom modes due to better readability, comment support, and cleaner multi-line strings. -### YAML Example - ```yaml customModes: - slug: docs-writer @@ -388,9 +389,456 @@ customModes: - command ``` +{% /tab %} +{% tab label="VSCode (Legacy)" %} + +In the new extension, custom behavioral profiles are called **agents** instead of modes. Agents are defined as Markdown files with YAML frontmatter or as entries in the `agent` key of your config file. + +## What's Included in a Custom Agent? + +| Property | Description | +| --------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| **name** (filename) | The agent's identifier, derived from the `.md` filename (e.g., `docs-writer.md` creates an agent named `docs-writer`) | +| **description** | A short summary displayed in the agent picker and used by the orchestrator for delegation | +| **model** | Pin a specific model in `provider/model` format (e.g., `anthropic/claude-sonnet-4-20250514`) | +| **prompt** (markdown body) | The system prompt text — the markdown body of the file, injected into the agent's system prompt | +| **mode** | Role classification: `primary` (user-selectable), `subagent` (only invoked by other agents), or `all` (both) | +| **permission** | Per-agent permission overrides controlling which tools the agent can use (e.g., deny `edit`, `bash`) | +| **color** | Hex color (`#FF5733`) or theme keyword (`primary`, `accent`, `warning`, etc.) for the agent picker UI | +| **steps** | Maximum agentic iterations before forcing a text-only response | +| **temperature** / **top_p** | Sampling parameters for the agent's model | +| **variant** | Default model variant | +| **hidden** | If `true`, the agent is hidden from the UI (only meaningful for subagents) | +| **disable** | If `true`, removes the agent entirely | + +## Methods for Creating and Configuring Agents + +### 1. Ask Kilo! (Recommended) + +Ask Kilo to create an agent for you: + +``` +Create a new agent called "docs-writer" that can only read files and edit Markdown files. +``` + +Kilo will generate the agent definition and write it to `.kilo/agent/` in your project. + +### 2. Using the Settings UI + +You can manage agents through the **Settings → Agent Behaviour → Agents** subtab in the extension. This lets you view, create, and edit agent configurations — including the agent's prompt, model, permissions, and other properties. + +### 3. Markdown Files with YAML Frontmatter + +Create `.md` files in any of these directories: + +``` +.kilo/agents/my-agent.md +.kilo/agent/my-agent.md +.opencode/agents/my-agent.md +``` + +For global agents, place files in your global config directory: + +``` +~/.config/kilo/agent/my-agent.md +``` + +The **filename** (minus `.md`) becomes the agent name. Nested directories create namespaced names (e.g., `agents/backend/sql.md` becomes agent `backend/sql`). + +**Example agent file** (`.kilo/agents/docs-writer.md`): + +```markdown +--- +description: Specialized for writing and editing technical documentation +mode: primary +color: "#10B981" +permission: + edit: + "*.md": "allow" + "*": "deny" + bash: deny +--- + +You are a technical documentation specialist. Your expertise includes: + +- Writing clear, well-structured documentation +- Following markdown best practices +- Creating helpful code examples + +Focus on clarity and completeness. Only edit Markdown files. +``` + +### 4. Config File (`kilo.json`) + +Define agents under the `agent` key in your project's `kilo.json` (or `opencode.jsonc`): + +```jsonc +{ + "agent": { + "docs-writer": { + "description": "Specialized for writing and editing technical documentation", + "mode": "primary", + "color": "#10B981", + "prompt": "You are a technical documentation specialist...", + "permission": { + "edit": "deny", + "bash": "deny", + }, + }, + // Override a built-in agent + "code": { + "model": "anthropic/claude-sonnet-4-20250514", + "temperature": 0.3, + }, + }, +} +``` + +## Agent Property Reference + +### `mode` + +Controls where the agent appears: + +| Value | Behavior | +| ---------- | -------------------------------------------------------------------------------------- | +| `primary` | Shown in the agent picker — the user can select it directly | +| `subagent` | Only invokable by other agents via the `task` tool | +| `all` | Available both as a top-level pick and as a subagent (default for user-defined agents) | + +### `permission` + +An ordered set of rules controlling tool access. Permissions support three actions: `allow`, `deny`, and `ask` (prompt the user). You can use glob patterns to scope rules to specific files or commands: + +```yaml +permission: + edit: + "*.md": "allow" + "*": "deny" + bash: deny + read: allow +``` + +Known permission types include: `read`, `edit`, `bash`, `glob`, `grep`, `list`, `task`, `webfetch`, `websearch`, `codesearch`, `todowrite`, `todoread`, and more. + +### `model` + +Pin a specific model using the `provider/model` format: + +```yaml +model: anthropic/claude-sonnet-4-20250514 +``` + +### `steps` + +Limits the number of agentic iterations (tool call rounds) before the agent is forced to respond with text only. Useful for preventing runaway agents: + +```yaml +steps: 25 +``` + +## Configuration Precedence + +Agent configurations merge from lowest to highest priority: + +1. Built-in (native) agent defaults +2. Global config (`~/.config/kilo/kilo.json`) +3. Project config (`kilo.json` at project root) +4. `.kilo/` / `.opencode/` directory configs and agent `.md` files +5. Environment variable overrides (`KILO_CONFIG_CONTENT`) + +When the same agent name appears at multiple levels, properties are merged (not replaced wholesale), so you can override just a model or temperature without redefining the entire agent. + +## Overriding Built-in Agents + +Override any built-in agent (**code**, **plan**, **debug**, **ask**, **orchestrator**, **explore**, **general**) by defining an agent with the same name: + +```jsonc +// kilo.json — override the built-in "code" agent +{ + "agent": { + "code": { + "model": "openai/gpt-4o", + "temperature": 0.2, + "permission": { + "edit": { + "*.py": "allow", + "*": "deny", + }, + }, + }, + }, +} +``` + +Or as a `.md` file (`.kilo/agents/code.md`): + +```markdown +--- +model: openai/gpt-4o +temperature: 0.2 +permission: + edit: + "*.py": "allow" + "*": "deny" +--- + +You are a Python specialist. Only edit Python files. +``` + +## Migration from VSCode Extension Modes + +If you have existing `.kilocodemodes` or `custom_modes.yaml` files from the VSCode extension, the new extension automatically migrates them on startup. The migration converts: + +- `slug` to the agent name (key) +- `roleDefinition` + `customInstructions` to `prompt` +- `groups` (e.g., `["read", "edit", "browser"]`) to `permission` rules +- `whenToUse` / `description` to `description` +- Mode is set to `primary` + +Built-in mode slugs (`code`, `ask`, `debug`, `orchestrator`) are skipped since they have native agent equivalents. + +{% /tab %} +{% tab label="CLI" %} + +In the CLI, custom behavioral profiles are called **agents** instead of modes. Agents are defined as Markdown files with YAML frontmatter or as entries in the `agent` key of your config file. + +## What's Included in a Custom Agent? + +| Property | Description | +| --------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| **name** (filename) | The agent's identifier, derived from the `.md` filename (e.g., `docs-writer.md` creates an agent named `docs-writer`) | +| **description** | A short summary displayed in the agent picker and used by the orchestrator for delegation | +| **model** | Pin a specific model in `provider/model` format (e.g., `anthropic/claude-sonnet-4-20250514`) | +| **prompt** (markdown body) | The system prompt text — the markdown body of the file, injected into the agent's system prompt | +| **mode** | Role classification: `primary` (user-selectable), `subagent` (only invoked by other agents), or `all` (both) | +| **permission** | Per-agent permission overrides controlling which tools the agent can use (e.g., deny `edit`, `bash`) | +| **color** | Hex color (`#FF5733`) or theme keyword (`primary`, `accent`, `warning`, etc.) for the agent picker UI | +| **steps** | Maximum agentic iterations before forcing a text-only response | +| **temperature** / **top_p** | Sampling parameters for the agent's model | +| **variant** | Default model variant | +| **hidden** | If `true`, the agent is hidden from the UI (only meaningful for subagents) | +| **disable** | If `true`, removes the agent entirely | + +## Methods for Creating and Configuring Agents + +### 1. Ask Kilo! (Recommended) + +Ask Kilo to create an agent for you: + +``` +Create a new agent called "docs-writer" that can only read files and edit Markdown files. +``` + +Kilo will generate the agent definition and write it to `.kilo/agent/` in your project. + +### 2. Using `kilo agent create` + +The CLI provides an interactive command: + +```bash +kilo agent create +``` + +This walks you through selecting a description, mode, and tools, then uses an LLM to generate the agent's system prompt and writes a `.md` file with YAML frontmatter. + +### 3. Markdown Files with YAML Frontmatter + +Create `.md` files in any of these directories: + +``` +.kilo/agents/my-agent.md +.kilo/agent/my-agent.md +.opencode/agents/my-agent.md +``` + +For global agents, place files in your global config directory: + +``` +~/.config/kilo/agent/my-agent.md +``` + +The **filename** (minus `.md`) becomes the agent name. Nested directories create namespaced names (e.g., `agents/backend/sql.md` becomes agent `backend/sql`). + +**Example agent file** (`.kilo/agents/docs-writer.md`): + +```markdown +--- +description: Specialized for writing and editing technical documentation +mode: primary +color: "#10B981" +permission: + edit: + "*.md": "allow" + "*": "deny" + bash: deny +--- + +You are a technical documentation specialist. Your expertise includes: + +- Writing clear, well-structured documentation +- Following markdown best practices +- Creating helpful code examples + +Focus on clarity and completeness. Only edit Markdown files. +``` + +### 4. Config File (`kilo.json`) + +Define agents under the `agent` key in your project's `kilo.json` (or `opencode.jsonc`): + +```jsonc +{ + "agent": { + "docs-writer": { + "description": "Specialized for writing and editing technical documentation", + "mode": "primary", + "color": "#10B981", + "prompt": "You are a technical documentation specialist...", + "permission": { + "edit": "deny", + "bash": "deny", + }, + }, + // Override a built-in agent + "code": { + "model": "anthropic/claude-sonnet-4-20250514", + "temperature": 0.3, + }, + }, +} +``` + +## Agent Property Reference + +### `mode` + +Controls where the agent appears: + +| Value | Behavior | +| ---------- | -------------------------------------------------------------------------------------- | +| `primary` | Shown in the agent picker — the user can select it directly | +| `subagent` | Only invokable by other agents via the `task` tool | +| `all` | Available both as a top-level pick and as a subagent (default for user-defined agents) | + +### `permission` + +An ordered set of rules controlling tool access. Permissions support three actions: `allow`, `deny`, and `ask` (prompt the user). You can use glob patterns to scope rules to specific files or commands: + +```yaml +permission: + edit: + "*.md": "allow" + "*": "deny" + bash: deny + read: allow +``` + +Known permission types include: `read`, `edit`, `bash`, `glob`, `grep`, `list`, `task`, `webfetch`, `websearch`, `codesearch`, `todowrite`, `todoread`, and more. + +### `model` + +Pin a specific model using the `provider/model` format: + +```yaml +model: anthropic/claude-sonnet-4-20250514 +``` + +### `steps` + +Limits the number of agentic iterations (tool call rounds) before the agent is forced to respond with text only. Useful for preventing runaway agents: + +```yaml +steps: 25 +``` + +## Configuration Precedence + +Agent configurations merge from lowest to highest priority: + +1. Built-in (native) agent defaults +2. Global config (`~/.config/kilo/kilo.json`) +3. Project config (`kilo.json` at project root) +4. `.kilo/` / `.opencode/` directory configs and agent `.md` files +5. Environment variable overrides (`KILO_CONFIG_CONTENT`) + +When the same agent name appears at multiple levels, properties are merged (not replaced wholesale), so you can override just a model or temperature without redefining the entire agent. + +## Overriding Built-in Agents + +Override any built-in agent (**code**, **plan**, **debug**, **ask**, **orchestrator**, **explore**, **general**) by defining an agent with the same name: + +```jsonc +// kilo.json — override the built-in "code" agent +{ + "agent": { + "code": { + "model": "openai/gpt-4o", + "temperature": 0.2, + "permission": { + "edit": { + "*.py": "allow", + "*": "deny", + }, + }, + }, + }, +} +``` + +Or as a `.md` file (`.kilo/agents/code.md`): + +```markdown +--- +model: openai/gpt-4o +temperature: 0.2 +permission: + edit: + "*.py": "allow" + "*": "deny" +--- + +You are a Python specialist. Only edit Python files. +``` + +## Migration from VSCode Extension Modes + +If you have existing `.kilocodemodes` or `custom_modes.yaml` files from the VSCode extension, the CLI automatically migrates them on startup. The migration converts: + +- `slug` to the agent name (key) +- `roleDefinition` + `customInstructions` to `prompt` +- `groups` (e.g., `["read", "edit", "browser"]`) to `permission` rules +- `whenToUse` / `description` to `description` +- Mode is set to `primary` + +Built-in mode slugs (`code`, `ask`, `debug`, `orchestrator`) are skipped since they have native agent equivalents. + +{% /tab %} +{% /tabs %} + ## Understanding Regex in Custom Modes -Regular expressions (`fileRegex`) offer fine-grained control over file editing permissions. +{% tabs %} +{% tab label="VSCode (Legacy)" %} + +Regular expressions (`fileRegex`) in the **VSCode** version offer fine-grained control over file editing permissions within tool groups. + +{% /tab %} +{% tab label="VSCode & CLI" %} + +The new extension and CLI use **permission rules with glob patterns** instead of regex. Permissions are defined per-tool (e.g., `edit`, `bash`, `read`) and support `allow`, `deny`, and `ask` actions with glob matching: + +```yaml +permission: + edit: + "*.md": "allow" + "*": "deny" +``` + +The **VSCode** version's `fileRegex` approach is automatically converted to permission rules during migration. + +{% /tab %} +{% /tabs %} {% callout type="tip" %} @@ -445,6 +893,9 @@ When a mode attempts to edit a file that doesn't match its `fileRegex` pattern, ## Example Configurations +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ### Basic Documentation Writer (YAML) ```yaml @@ -498,8 +949,101 @@ customModes: - browser ``` +{% /tab %} +{% tab label="VSCode & CLI" %} + +### Basic Documentation Writer (`.kilo/agents/docs-writer.md`) + +```markdown +--- +description: Specialized for writing and editing technical documentation +mode: primary +color: "#10B981" +permission: + edit: + "*.md": "allow" + "*": "deny" + bash: deny +--- + +You are a technical writer specializing in clear documentation. +Focus on clear explanations and examples. +``` + +### Test Engineer (`.kilo/agents/test-engineer.md`) + +```markdown +--- +description: Focused on writing and maintaining test suites +mode: primary +color: "#F59E0B" +permission: + edit: + "*.{test,spec}.{js,ts}": "allow" + "*": "deny" +--- + +You are a test engineer focused on code quality. +Use for writing tests, debugging test failures, and improving test coverage. +``` + +### Security Reviewer (`.kilo/agents/security-review.md`) + +```markdown +--- +description: Read-only security analysis and vulnerability assessment +mode: primary +color: "#EF4444" +permission: + edit: deny + bash: deny +--- + +You are a security specialist reviewing code for vulnerabilities. + +Focus on: + +- Input validation issues +- Authentication and authorization flaws +- Data exposure risks +- Injection vulnerabilities +``` + +### Config File Example (`kilo.json`) + +```jsonc +{ + "agent": { + "docs-writer": { + "description": "Specialized for writing and editing technical documentation", + "mode": "primary", + "color": "#10B981", + "prompt": "You are a technical writer specializing in clear documentation.", + "permission": { + "edit": { "*.md": "allow", "*": "deny" }, + "bash": "deny", + }, + }, + "test-engineer": { + "description": "Focused on writing and maintaining test suites", + "mode": "primary", + "prompt": "You are a test engineer focused on code quality.", + "permission": { + "edit": { "*.{test,spec}.{js,ts}": "allow", "*": "deny" }, + }, + }, + }, +} +``` + +{% /tab %} +{% /tabs %} + ## Troubleshooting +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ### Common Issues - **Mode not appearing:** After creating or importing a mode, you may need to reload the VS Code window @@ -514,6 +1058,43 @@ customModes: - **Hyphens for List Items:** List items start with a hyphen and a space (e.g., `- read`) - **Validate Your YAML:** Use online YAML validators or your editor's built-in validation +{% /tab %} +{% tab label="VSCode (Legacy)" %} + +### Common Issues + +- **Agent not appearing:** Ensure the `.md` file is in a recognized directory (`.kilo/agents/`, `.kilo/agent/`, `.opencode/agents/`). Check that the `mode` property is `primary` or `all` if you expect it in the agent picker. +- **Permission errors:** Permission rules are evaluated last-match-wins. If an agent can't use a tool you expect, check that an `allow` rule appears after any `deny` rules for that permission. +- **YAML frontmatter parse errors:** Ensure the frontmatter block starts and ends with `---` on its own line. Validate that YAML keys match expected property names (e.g., `top_p` not `topP`). +- **Agent overrides not working:** Config merges from global to project level. If a global config sets a property, your project config can override it, but both must use the same agent name. + +### Tips for Agent Definitions + +- **Keep prompts focused:** The markdown body is your system prompt — write it as if briefing a colleague +- **Use `mode: subagent`** for helper agents that shouldn't be directly selectable by users +- **Use the Settings UI** to view and edit agents through the **Settings → Agent Behaviour → Agents** subtab +- **Legacy modes are auto-migrated:** If you have `.kilocodemodes` files, they'll be converted on startup — no manual migration needed + +{% /tab %} +{% tab label="CLI" %} + +### Common Issues + +- **Agent not appearing:** Ensure the `.md` file is in a recognized directory (`.kilo/agents/`, `.kilo/agent/`, `.opencode/agents/`). Check that the `mode` property is `primary` or `all` if you expect it in the agent picker. +- **Permission errors:** Permission rules are evaluated last-match-wins. If an agent can't use a tool you expect, check that an `allow` rule appears after any `deny` rules for that permission. +- **YAML frontmatter parse errors:** Ensure the frontmatter block starts and ends with `---` on its own line. Validate that YAML keys match expected property names (e.g., `top_p` not `topP`). +- **Agent overrides not working:** Config merges from global to project level. If a global config sets a property, your project config can override it, but both must use the same agent name. + +### Tips for Agent Definitions + +- **Keep prompts focused:** The markdown body is your system prompt — write it as if briefing a colleague +- **Use `mode: subagent`** for helper agents that shouldn't be directly selectable by users +- **Test with `kilo agent create`** to see how the CLI generates agent definitions, then customize from there +- **Legacy modes are auto-migrated:** If you have `.kilocodemodes` files, they'll be converted on startup — no manual migration needed + +{% /tab %} +{% /tabs %} + ## Community Gallery -Ready to explore more? Check out the [Show and Tell](https://github.com/Kilo-Org/kilocode/discussions/categories/show-and-tell) to discover and share custom modes created by the community! +Ready to explore more? Check out the [Show and Tell](https://github.com/Kilo-Org/kilocode/discussions/categories/show-and-tell) to discover and share custom modes and agents created by the community! diff --git a/packages/kilo-docs/pages/customize/custom-rules.md b/packages/kilo-docs/pages/customize/custom-rules.md index ccecb0528ec..d89be15ed5e 100644 --- a/packages/kilo-docs/pages/customize/custom-rules.md +++ b/packages/kilo-docs/pages/customize/custom-rules.md @@ -26,12 +26,11 @@ Kilo Code supports two types of custom rules: - **Project Rules**: Apply only to the current project workspace - **Global Rules**: Apply across all projects and workspaces -{% callout type="note" title="UI Support" %} -The built-in rules management UI is available for general rules only. Mode-specific rules must be managed through the file system. -{% /callout %} - ## Rule Location +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ### Project Rules Custom rules are primarily loaded from the **`.kilocode/rules/` directory**. This is the recommended approach for organizing your project-specific rules. Each rule is typically placed in its own Markdown file with a descriptive name: @@ -59,8 +58,86 @@ Global rules are stored in your home directory and apply to all projects: │ └── documentation_style.md ``` +{% /tab %} +{% tab label="VSCode (Legacy)" %} + +### Project Rules + +Project rules are configured via the `instructions` key in your project's `kilo.json` file. You can edit this file directly or use the **Settings** webview to manage the `instructions` configuration. Each entry points to a file path or glob pattern: + +```jsonc +// kilo.json +{ + "instructions": [".kilo/rules/formatting.md", ".kilo/rules/*.md"], +} +``` + +You can also place rule files in the **`.kilo/`** directory structure: + +``` +project/ +├── .kilo/ +│ ├── rules/ +│ │ ├── formatting.md +│ │ ├── restricted_files.md +│ │ └── naming_conventions.md +├── kilo.json +├── src/ +└── ... +``` + +### Global Rules + +Global rules are configured via the `instructions` key in your global `kilo.json` config file (typically at `~/.config/kilo/kilo.json`). + +{% callout type="note" title="Migration" %} +The new extension is backward compatible with `.kilocode/rules/` directories. Existing rules will continue to work, but migrating to `kilo.json` is recommended. +{% /callout %} + +{% /tab %} +{% tab label="CLI" %} + +### Project Rules + +Project rules are configured via the `instructions` key in your project's `kilo.json` file. Each entry points to a file path or glob pattern: + +```jsonc +// kilo.json +{ + "instructions": [".kilo/rules/formatting.md", ".kilo/rules/*.md"], +} +``` + +You can also place rule files in the **`.kilo/`** directory structure: + +``` +project/ +├── .kilo/ +│ ├── rules/ +│ │ ├── formatting.md +│ │ ├── restricted_files.md +│ │ └── naming_conventions.md +├── kilo.json +├── src/ +└── ... +``` + +### Global Rules + +Global rules are configured via the `instructions` key in your global `kilo.json` config file (typically at `~/.config/kilo/kilo.json`). + +{% callout type="note" title="Migration" %} +The CLI is backward compatible with `.kilocode/rules/` directories. Existing rules will continue to work, but migrating to `kilo.json` is recommended. +{% /callout %} + +{% /tab %} +{% /tabs %} + ## Managing Rules Through the UI +{% tabs %} +{% tab label="VSCode (Legacy)" %} + Kilo Code provides a built-in interface for managing your custom rules without manually editing files in the `.kilocode/rules/` directories. To access the UI, click on the icon in the **bottom right corner** of the Kilo Code window. You can access the rules management UI to: @@ -70,8 +147,58 @@ You can access the rules management UI to: - Create and edit rules directly in the interface - Organize rules by category and priority +{% callout type="note" title="UI Support" %} +The built-in rules management UI is available for general rules only. Mode-specific rules must be managed through the file system. +{% /callout %} + +{% /tab %} +{% tab label="VSCode (Legacy)" %} + +Rules are managed by editing the `instructions` array in your `kilo.json` config file. You can also use the **Settings** webview in VS Code to edit the configuration. + +- **Add a rule**: Add a file path or glob pattern to the `instructions` array +- **Remove a rule**: Remove the entry from the array +- **Disable a rule temporarily**: Comment out the line in `kilo.json` (JSONC supports `//` comments) + +```jsonc +// kilo.json +{ + "instructions": [ + ".kilo/rules/formatting.md", + // ".kilo/rules/experimental.md" -- temporarily disabled + ".kilo/rules/naming_conventions.md", + ], +} +``` + +{% /tab %} +{% tab label="CLI" %} + +Rules are managed by editing the `instructions` array in your `kilo.json` config file directly. + +- **Add a rule**: Add a file path or glob pattern to the `instructions` array +- **Remove a rule**: Remove the entry from the array +- **Disable a rule temporarily**: Comment out the line in `kilo.json` (JSONC supports `//` comments) + +```jsonc +// kilo.json +{ + "instructions": [ + ".kilo/rules/formatting.md", + // ".kilo/rules/experimental.md" -- temporarily disabled + ".kilo/rules/naming_conventions.md", + ], +} +``` + +{% /tab %} +{% /tabs %} + ## Rule Loading Order +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ### General Rules (Any Mode) Rules are loaded in the following priority order: @@ -86,21 +213,40 @@ Rules are loaded in the following priority order: When both global and project rules exist, they are combined with project rules taking precedence over global rules for conflicting directives. {% callout type="note" %} -We strongly recommend keeping your rules in the `.kilocode/rules/` folder as it provides better organization and is the preferred approach for future versions. The folder-based structure allows for more granular rule organization and clearer separation of concerns. The legacy file-based approach is maintained for backward compatibility but may be subject to change in future releases. +We strongly recommend keeping your rules in the `.kilocode/rules/` folder as it provides better organization and is the preferred approach for future versions. The legacy file-based approach is maintained for backward compatibility but may be subject to change in future releases. {% /callout %} ### Mode-Specific Rules -Additionally, the system supports mode-specific rules, which are loaded separately and have their own priority order: +The system also supports mode-specific rules with their own priority order: 1. First, it checks for `.kilocode/rules-${mode}/` directory 2. If that doesn't exist or is empty, it falls back to `.kilocoderules-${mode}` file (deprecated) -Currently, mode-specific rules are only supported at the project level. -When both generic rules and mode-specific rules exist, the mode-specific rules are given priority in the final output. +Mode-specific rules are only supported at the project level. When both generic and mode-specific rules exist, mode-specific rules take priority. + +{% /tab %} +{% tab label="VSCode & CLI" %} + +Rules are loaded in the order they appear in the `instructions` array in `kilo.json`: + +1. **Global instructions** from the global `kilo.json` config +2. **Project instructions** from the project's `kilo.json` + +Files matched by glob patterns are loaded in filesystem order. Project-level instructions take precedence over global instructions for conflicting directives. + +{% callout type="note" title="Backward Compatibility" %} +If `.kilocode/rules/` directories exist in your project, their contents are automatically included for backward compatibility. To fully migrate, move your rule files and reference them in `kilo.json`. +{% /callout %} + +{% /tab %} +{% /tabs %} ## Creating Custom Rules +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ### Using the UI Interface {% image src="/docs/img/custom-rules/rules-ui.png" alt="Rules tab in Kilo Code" width="400" /%} @@ -132,6 +278,47 @@ To create rules manually: Rules will be automatically applied to all future Kilo Code interactions. Any new changes will be applied immediately. +{% /tab %} +{% tab label="VSCode (Legacy)" %} + +### Using the Settings UI or Config File + +1. Create a `kilo.json` file in your project root (if it doesn't exist) +2. Create a `.kilo/rules/` directory (or any directory you prefer) +3. Write your rule as a Markdown file in that directory +4. Add the file path or a glob pattern to the `instructions` array in `kilo.json` + +```jsonc +// kilo.json +{ + "instructions": [".kilo/rules/my-new-rule.md"], +} +``` + +Rules are applied on the next interaction. You can also edit `kilo.json` through the **Settings** webview in VS Code. + +{% /tab %} +{% tab label="CLI" %} + +### Using the Config File + +1. Create a `kilo.json` file in your project root (if it doesn't exist) +2. Create a `.kilo/rules/` directory (or any directory you prefer) +3. Write your rule as a Markdown file in that directory +4. Add the file path or a glob pattern to the `instructions` array in `kilo.json` + +```jsonc +// kilo.json +{ + "instructions": [".kilo/rules/my-new-rule.md"], +} +``` + +Rules are applied on the next interaction. + +{% /tab %} +{% /tabs %} + ## Example Rules ### Example 1: Table Formatting @@ -207,14 +394,30 @@ When working in team environments, placing `.kilocode/rules/codestyle.md` files If your custom rules aren't being properly followed: -1. **Check rule status in the UI**: Use the rules management interface to verify that your rules are active and properly loaded 1. **Verify rule formatting**: Ensure that your rules are properly formatted with clear Markdown structure -1. **Check rule locations**: Ensure that your rules are located in supported locations: - - Global rules: `~/.kilocode/rules/` directory - - Project rules: `.kilocode/rules/` directory - - Legacy files: `.kilocoderules`, `.roorules`, or `.clinerules` -1. **Rule specificity**: Verify that the rules are specific and unambiguous -1. **Restart VS Code**: Restart VS Code to ensure the rules are properly loaded +2. **Rule specificity**: Verify that the rules are specific and unambiguous +3. **Check rule locations**: + +{% tabs %} +{% tab label="VSCode (Legacy)" %} + +- **Check rule status in the UI**: Use the rules management interface to verify that your rules are active and properly loaded +- Ensure rules are in supported locations: + - Global rules: `~/.kilocode/rules/` directory + - Project rules: `.kilocode/rules/` directory + - Legacy files: `.kilocoderules`, `.roorules`, or `.clinerules` +- **Restart VS Code** to ensure the rules are properly loaded + +{% /tab %} +{% tab label="VSCode & CLI" %} + +- Verify that your `kilo.json` file is valid JSON (with comments) +- Ensure the `instructions` paths resolve to existing files +- Check that glob patterns match the intended files +- Run `kilo` to see if rules are loaded in the output + +{% /tab %} +{% /tabs %} ## Related Features diff --git a/packages/kilo-docs/pages/customize/custom-subagents.md b/packages/kilo-docs/pages/customize/custom-subagents.md index e97090c4a1e..7fa87c195af 100644 --- a/packages/kilo-docs/pages/customize/custom-subagents.md +++ b/packages/kilo-docs/pages/customize/custom-subagents.md @@ -1,6 +1,7 @@ --- title: "Custom Subagents" description: "Create and configure custom subagents in Kilo Code's CLI" +platform: new --- # Custom Subagents diff --git a/packages/kilo-docs/pages/customize/skills.md b/packages/kilo-docs/pages/customize/skills.md index 8f553d681ef..8d49fbb7e64 100644 --- a/packages/kilo-docs/pages/customize/skills.md +++ b/packages/kilo-docs/pages/customize/skills.md @@ -47,6 +47,9 @@ This means: Skills are loaded from multiple locations, allowing both personal skills and project-specific instructions. +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ### Global Skills (User-Level) Global skills are located in the `.kilocode` directory within your Home directory. @@ -84,9 +87,68 @@ your-project/ └── SKILL.md ``` +{% /tab %} +{% tab label="VSCode & CLI" %} + +### Global Skills (User-Level) + +Global skills are located in the `.kilo` directory within your Home directory: + +- Mac and Linux: `~/.kilo/skills/` +- Windows: `\Users\\.kilo\skills\` + +``` +~/.kilo/ +└── skills/ # Generic skills (all modes) + ├── my-skill/ + │ └── SKILL.md + └── another-skill/ + └── SKILL.md +``` + +### Project Skills (Workspace-Level) + +Located in `.kilo/skills/` within your project: + +``` +your-project/ +└── .kilo/ + └── skills/ # Generic skills for this project + └── project-conventions/ + └── SKILL.md +``` + +### Compatibility Directories + +For interoperability with other tools, the CLI also loads skills from: + +- `.claude/skills/` — Claude Code compatibility +- `.agents/skills/` — Open agent standard + +### Additional Skill Paths and Remote URLs + +You can configure extra skill locations and remote skill URLs in your `kilo.json` config (project or global): + +```jsonc +{ + "skills": { + "paths": ["/path/to/shared/skills"], + "urls": ["https://example.com/skills/my-skill/SKILL.md"], + }, +} +``` + +The `skills.paths` key accepts absolute paths to additional skill directories. The `skills.urls` key accepts URLs pointing to remote `SKILL.md` files that are fetched on demand. + +{% /tab %} +{% /tabs %} + ## Mode-Specific Skills -To create a skill that only appears in a specific mode: +{% tabs %} +{% tab label="VSCode (Legacy)" %} + +To create a skill that only appears in a specific mode, place it in a `skills-{mode-slug}` directory: ```bash # For Code mode only @@ -98,8 +160,21 @@ mkdir -p ~/.kilocode/skills-architect/microservices The directory naming pattern is `skills-{mode-slug}` where `{mode-slug}` matches the mode's identifier (e.g., `code`, `architect`, `ask`, `debug`). +{% /tab %} +{% tab label="VSCode & CLI" %} + +The new platform does not use mode-specific skill directories. All skills are loaded into a shared pool and the agent decides which skill to invoke based on the skill's `description` field and the current task context. + +If you need a skill to only apply in certain situations, write a clear and specific `description` in the SKILL.md frontmatter so the agent knows when to use it. + +{% /tab %} +{% /tabs %} + ## Priority and Overrides +{% tabs %} +{% tab label="VSCode (Legacy)" %} + When multiple skills share the same name, Kilo Code uses these priority rules: 1. **Project skills override global skills** - A project skill with the same name takes precedence @@ -111,8 +186,19 @@ This allows you to: - Override them per-project when needed - Customize behavior for specific modes +{% /tab %} +{% tab label="VSCode & CLI" %} + +When multiple skills share the same name, project-level skills (`.kilo/skills/`) take precedence over global skills (`~/.kilo/skills/`). Skills from compatibility directories (`.claude/skills/`, `.agents/skills/`) and additional configured paths are loaded alongside project and global skills. + +{% /tab %} +{% /tabs %} + ## When Skills Are Loaded +{% tabs %} +{% tab label="VSCode (Legacy)" %} + Skills are discovered when Kilo Code initializes: - When VSCode starts @@ -126,6 +212,19 @@ Skills directories are monitored for changes to `SKILL.md` files. However, the m You can symlink skills directories to share skills across machines or from a central repository. When using symlinks, the skill's `name` field must match the **symlink name**, not the target directory name. +{% /tab %} +{% tab label="VSCode & CLI" %} + +Skills are discovered when a session starts. The CLI scans all configured skill directories and reads metadata (name, description, file path) for each skill. + +- In the **CLI**: Skills are loaded when you start a new session or run `kilo run` +- In the **VS Code extension**: Skills are loaded when the extension connects to the CLI server + +Skills are re-scanned at the start of each new session. To pick up newly added or modified skills, start a new session. + +{% /tab %} +{% /tabs %} + ## SKILL.md Format The `SKILL.md` file uses YAML frontmatter followed by Markdown content containing the instructions: @@ -213,62 +312,101 @@ These additional files can be referenced from your skill's instructions, allowin ## Example: Creating a Skill +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. Create the skill directory: ```bash mkdir -p ~/.kilocode/skills/api-design ``` -2. Create `SKILL.md`: - - ```markdown - --- - name: api-design - description: REST API design best practices and conventions - --- - - # API Design Guidelines - - When designing REST APIs, follow these conventions: - - ## URL Structure - - - Use plural nouns for resources: `/users`, `/orders` - - Use kebab-case for multi-word resources: `/order-items` - - Nest related resources: `/users/{id}/orders` - - ## HTTP Methods - - - GET: Retrieve resources - - POST: Create new resources - - PUT: Replace entire resource - - PATCH: Partial update - - DELETE: Remove resource - - ## Response Codes - - - 200: Success - - 201: Created - - 400: Bad Request - - 404: Not Found - - 500: Server Error - ``` +2. Create `SKILL.md` (see content below) 3. Reload VSCode to load the skill 4. The skill will now be available in all modes +{% /tab %} +{% tab label="VSCode & CLI" %} + +1. Create the skill directory: + + ```bash + mkdir -p ~/.kilo/skills/api-design + ``` + +2. Create `SKILL.md` (see content below) + +3. Start a new session to pick up the skill + +{% /tab %} +{% /tabs %} + +Example `SKILL.md`: + +```markdown +--- +name: api-design +description: REST API design best practices and conventions +--- + +# API Design Guidelines + +When designing REST APIs, follow these conventions: + +## URL Structure + +- Use plural nouns for resources: `/users`, `/orders` +- Use kebab-case for multi-word resources: `/order-items` +- Nest related resources: `/users/{id}/orders` + +## HTTP Methods + +- GET: Retrieve resources +- POST: Create new resources +- PUT: Replace entire resource +- PATCH: Partial update +- DELETE: Remove resource + +## Response Codes + +- 200: Success +- 201: Created +- 400: Bad Request +- 404: Not Found +- 500: Server Error +``` + ## Finding Skills +{% tabs %} +{% tab label="VSCode (Legacy)" %} + You can discover and install community-created skills through: -- **Kilo Marketplace** - Browse skills directly in the Kilo Code extension via the Marketplace tab, or explore the [Kilo Marketplace repository](https://github.com/Kilo-Org/kilo-marketplace) on GitHub -- [Agent Skills Specification](https://agentskills.io/home) - The open specification that skills follow, enabling interoperability across different AI agents +- **Kilo Marketplace** — Browse skills directly in the Kilo Code extension via the Marketplace tab, or explore the [Kilo Marketplace repository](https://github.com/Kilo-Org/kilo-marketplace) on GitHub +- [Agent Skills Specification](https://agentskills.io/home) — The open specification that skills follow, enabling interoperability across different AI agents + +{% /tab %} +{% tab label="VSCode & CLI" %} + +The new platform does not have a marketplace UI yet. You can find and share skills through: + +- **[Kilo Marketplace repository](https://github.com/Kilo-Org/kilo-marketplace)** — Browse community skills on GitHub and manually download them into your skills directory +- **[Agent Skills Specification](https://agentskills.io/home)** — The open specification that skills follow, enabling interoperability across different AI agents +- **Remote URLs** — Use the `skills.urls` config key to load skills directly from URLs without manually downloading them + +{% /tab %} +{% /tabs %} ## Troubleshooting ### Skill Not Loading? +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Check the Output panel**: Open `View` → `Output` → Select "Kilo Code" from dropdown. Look for skill-related errors. 2. **Verify frontmatter**: Ensure `name` exactly matches the directory name and `description` is present. @@ -277,6 +415,20 @@ You can discover and install community-created skills through: 4. **Check file location**: Ensure `SKILL.md` is directly inside the skill directory, not nested further. +{% /tab %} +{% tab label="VSCode & CLI" %} + +1. **Verify frontmatter**: Ensure `name` exactly matches the directory name and `description` is present. + +2. **Start a new session**: Skills are scanned at session start. Begin a new session to pick up changes. + +3. **Check file location**: Ensure `SKILL.md` is directly inside the skill directory (e.g., `.kilo/skills/my-skill/SKILL.md`), not nested further. + +4. **Check config paths**: If using `skills.paths` or `skills.urls`, verify the paths and URLs are correct in your `kilo.json`. + +{% /tab %} +{% /tabs %} + ### Verifying a Skill is Available To confirm a skill is properly loaded and available to the agent, you can ask the agent directly. Simply send a message like: @@ -291,10 +443,21 @@ If the agent confirms the skill is available, you're ready to use it. If not, ch ### Checking if a Skill Was Used +{% tabs %} +{% tab label="VSCode (Legacy)" %} + To see if a skill was actually used during a conversation, look for a `read_file` tool call in the chat that targets a `SKILL.md` file. When the agent decides to use a skill, it reads the full skill file into context—this appears as a file read operation in the conversation. There's currently no dedicated UI indicator showing "Skill X was activated." The `read_file` call is the most reliable way to confirm a skill was used. +{% /tab %} +{% tab label="VSCode & CLI" %} + +When the agent uses a skill, it invokes the `skill` tool with the skill's name. Look for a `skill` tool call in the conversation to confirm a skill was loaded. The tool output includes the full skill content injected into context. + +{% /tab %} +{% /tabs %} + ### Common Errors | Error | Cause | Solution | @@ -307,6 +470,19 @@ There's currently no dedicated UI indicator showing "Skill X was activated." The Have you created a skill that others might find useful? Share it with the community by contributing to the [Kilo Marketplace](https://github.com/Kilo-Org/kilo-marketplace)! +{% tabs %} +{% tab label="VSCode (Legacy)" %} + +Skills submitted to the marketplace are browsable and installable directly from the Marketplace tab in the **VSCode** version. + +{% /tab %} +{% tab label="VSCode & CLI" %} + +While the new platform does not yet have a built-in marketplace UI, skills from the [Kilo Marketplace repository](https://github.com/Kilo-Org/kilo-marketplace) can be manually downloaded into your `.kilo/skills/` directory or loaded via `skills.urls` in config. + +{% /tab %} +{% /tabs %} + ### How to Submit Your Skill 1. **Prepare your skill**: Ensure your skill directory contains a valid `SKILL.md` file with proper frontmatter diff --git a/packages/kilo-docs/pages/customize/workflows.md b/packages/kilo-docs/pages/customize/workflows.md index c18a0030fb8..4b8fed926af 100644 --- a/packages/kilo-docs/pages/customize/workflows.md +++ b/packages/kilo-docs/pages/customize/workflows.md @@ -1,6 +1,7 @@ --- title: "Workflows" description: "Create automated workflows with Kilo Code" +platform: new --- # Workflows From 8304cf44dc082393f962ff30a5aa82fcb492584a Mon Sep 17 00:00:00 2001 From: Josh Lambert Date: Tue, 24 Mar 2026 05:29:32 -0400 Subject: [PATCH 019/308] docs(kilo-docs): add platform tabs to MCP and shell integration pages Add VSCode (Pre-release) and CLI tabs to 3 automate pages: - mcp/using-in-kilo-code.md: Tabbed config tables, CLI commands (including logout and debug), transport types, troubleshooting - extending/shell-integration.md: Platform-specific shell integration - automate/index.md: Fix stale link to deleted using-in-cli page MCP timeout correctly shown as 30000ms (verified against mcp/index.ts:29 DEFAULT_TIMEOUT = 30_000). Part of the docs platform tabs effort (PR 7 of 8). Depends on #7497 for infrastructure. --- packages/kilo-docs/lib/nav/automate.ts | 5 +- .../automate/extending/shell-integration.md | 77 +++++ packages/kilo-docs/pages/automate/index.md | 2 +- .../pages/automate/mcp/using-in-kilo-code.md | 319 +++++++++++++++--- 4 files changed, 362 insertions(+), 41 deletions(-) diff --git a/packages/kilo-docs/lib/nav/automate.ts b/packages/kilo-docs/lib/nav/automate.ts index e8ae1c02a8d..d4d9bb487e8 100644 --- a/packages/kilo-docs/lib/nav/automate.ts +++ b/packages/kilo-docs/lib/nav/automate.ts @@ -29,6 +29,7 @@ export const AutomateNav: NavSection[] = [ { href: "/automate/extending/auto-launch", children: "Auto-launch Configuration", + platform: "legacy", }, { href: "/automate/mcp/overview", @@ -53,8 +54,8 @@ export const AutomateNav: NavSection[] = [ { title: "Tools", links: [ - { href: "/automate/how-tools-work", children: "How Tools Work" }, - { href: "/automate/tools", children: "Tools Details" }, + { href: "/automate/how-tools-work", children: "How Tools Work", platform: "legacy" }, + { href: "/automate/tools", children: "Tools Details", platform: "legacy" }, ], }, ] diff --git a/packages/kilo-docs/pages/automate/extending/shell-integration.md b/packages/kilo-docs/pages/automate/extending/shell-integration.md index 5c7a88187ac..c88399a1f61 100644 --- a/packages/kilo-docs/pages/automate/extending/shell-integration.md +++ b/packages/kilo-docs/pages/automate/extending/shell-integration.md @@ -7,6 +7,9 @@ description: "Integrate Kilo Code with your shell environment" Terminal Shell Integration is a key feature that enables Kilo Code to execute commands in your terminal and intelligently process their output. This bidirectional communication between the AI and your development environment unlocks powerful automation capabilities. +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ## What is Shell Integration? Shell integration is automatically enabled in Kilo Code and connects directly to your terminal's command execution lifecycle without requiring any setup from you. This built-in feature allows Kilo Code to: @@ -340,6 +343,80 @@ The [VS Code Terminal Integration Test Extension](https://github.com/KJ7LNW/vsce - Note your environment (OS, VS Code version, shell, and any shell prompt customization) - Open an issue with these details to help improve shell integration +{% /tab %} +{% tab label="VSCode & CLI" %} + +## How Shell Execution Works + +The new CLI and extension take a fundamentally different approach to shell execution. Instead of relying on VS Code's terminal shell integration, the CLI spawns and manages shell processes directly using the `bash` tool. + +This means: + +- **No VS Code shell integration required** — the CLI handles shell execution independently +- **No shell integration setup or troubleshooting** — it works out of the box +- **Consistent behavior** across environments — the same shell execution logic runs whether you use the CLI directly or through the VS Code extension + +## The `bash` Tool + +The `bash` tool is the primary way the agent executes shell commands. It spawns a persistent shell session and runs commands within it. + +### Key Features + +- **Working directory control**: Use the `workdir` parameter to run commands in a specific directory, instead of `cd && ` patterns +- **Configurable timeout**: Set a per-command timeout in milliseconds (defaults to 2 minutes) +- **Real-time output streaming**: Command output is streamed back as it's produced +- **Process tree management**: The tool manages the full process tree, ensuring child processes are properly cleaned up + +### Security Analysis + +Commands are parsed using **Tree-sitter** before execution, enabling: + +- Path resolution to detect file access patterns +- External directory detection to flag commands that reach outside the project +- Structured analysis of command intent for safer auto-approval decisions + +### Shell Detection + +The CLI automatically detects the appropriate shell for your platform using `Shell.acceptable()`. This selects a compatible shell (bash, zsh, etc.) without requiring manual configuration. + +## Agent Manager Terminals (VS Code Extension) + +When using the Kilo Code VS Code extension with the Agent Manager, each agent session gets its own dedicated VS Code terminal. + +### Per-Session Terminals + +- Each session creates a terminal named **`Agent: {branch}`**, where `{branch}` is the git branch or worktree the session is working in +- The terminal's working directory is automatically set to the session's worktree directory +- Terminals are standard VS Code integrated terminals — you can interact with them directly + +### Keyboard Shortcuts + +| Shortcut | Action | +| --------------------------- | --------------------------------------- | +| Cmd+/ | Focus the session's terminal | +| Cmd+. | Return focus to the Agent Manager panel | + +### Terminal Context Menu Actions + +Right-click in an Agent Manager terminal to access these actions: + +- **Add Terminal Content to Context** — sends the terminal's visible output to the agent as context +- **Fix This Command** — asks the agent to diagnose and fix the last failed command +- **Explain This Command** — asks the agent to explain what a command does + +## Troubleshooting + +Shell execution in the new CLI is significantly simpler than the **VSCode** version's terminal integration. Most issues are resolved by ensuring: + +1. **A supported shell is installed**: bash or zsh on macOS/Linux, PowerShell on Windows +2. **The shell is on your PATH**: The CLI needs to find the shell binary +3. **File permissions are correct**: The CLI needs execute permission on the shell binary + +If commands fail to execute, check the CLI's log output for error details. The CLI logs the shell it detected and any errors during command execution. + +{% /tab %} +{% /tabs %} + ## Support If you've followed these steps and are still experiencing problems, please: diff --git a/packages/kilo-docs/pages/automate/index.md b/packages/kilo-docs/pages/automate/index.md index 453f0163c50..9616faf4a7e 100644 --- a/packages/kilo-docs/pages/automate/index.md +++ b/packages/kilo-docs/pages/automate/index.md @@ -36,7 +36,7 @@ Connect Kilo Code to external tools and services: - [**Using MCP in Kilo Code**](/docs/automate/mcp/using-in-kilo-code) — Configuration guide - [**STDIO & SSE Transports**](/docs/automate/mcp/server-transports) — Local and remote server options - [**MCP vs API**](/docs/automate/mcp/mcp-vs-api) — When to use MCP -- [**Using MCP in CLI**](/docs/automate/mcp/using-in-cli) — CLI-specific MCP setup +- [**Using MCP in Kilo Code**](/docs/automate/mcp/using-in-kilo-code) — Configure MCP servers ## Integrations diff --git a/packages/kilo-docs/pages/automate/mcp/using-in-kilo-code.md b/packages/kilo-docs/pages/automate/mcp/using-in-kilo-code.md index 43dd907c755..f0ef4d68a98 100644 --- a/packages/kilo-docs/pages/automate/mcp/using-in-kilo-code.md +++ b/packages/kilo-docs/pages/automate/mcp/using-in-kilo-code.md @@ -7,31 +7,46 @@ description: "How to use MCP servers in Kilo Code" Model Context Protocol (MCP) extends Kilo Code's capabilities by connecting to external tools and services. This guide covers everything you need to know about using MCP with Kilo Code. -{% youtube url="https://youtu.be/6O9RQoQRX8A" caption="Demostrating MCP installation in Kilo Code" /%} +{% youtube url="https://youtu.be/6O9RQoQRX8A" caption="Demonstrating MCP installation in Kilo Code" /%} ## Configuring MCP Servers -MCP server configurations can be managed at two levels: +MCP server configurations can be managed at two levels: **global** (applies across all workspaces) and **project-level** (specific to a single project). Project-level configuration takes precedence over global settings. -1. **Global Configuration**: Stored in the `mcp_settings.json` file, accessible via VS Code settings (see below). These settings apply across all your workspaces unless overridden by a project-level configuration. -2. **Project-level Configuration**: Defined in a `.kilocode/mcp.json` file within your project's root directory. This allows you to set up project-specific servers and share configurations with your team by committing the file to version control. Kilo Code automatically detects and loads this file if it exists. +{% tabs %} +{% tab label="VSCode (Legacy)" %} -**Precedence**: If a server name exists in both global and project configurations, the **project-level configuration takes precedence**. +| Scope | Path | Description | +| ----------- | -------------------- | --------------------------------------------------------------- | +| **Global** | `mcp_settings.json` | Accessible via VS Code settings. Applies across all workspaces. | +| **Project** | `.kilocode/mcp.json` | In your project root. Auto-detected by Kilo Code. | -### Editing MCP Settings Files +Project-level configs can be committed to version control to share with your team. -You can edit both global and project-level MCP configuration files directly from the Kilo Code settings. +{% /tab %} +{% tab label="VSCode" %} -1. Click the {% codicon name="gear" /%} icon in the top navigation of the Kilo Code pane to open `Settings`. -2. Click the `Agent Behaviour` tab on the left side -3. Select the `MCP Servers` sub-tab -4. Click the appropriate button: - - **`Edit Global MCP`**: Opens the global `mcp_settings.json` file. - - **`Edit Project MCP`**: Opens the project-specific `.kilocode/mcp.json` file. If this file doesn't exist, Kilo Code will create it for you. +In the VS Code extension, open **Settings → MCP** to add and manage MCP servers through the UI. Under the hood the extension reads the same config files as the CLI — see the **CLI** tab for file paths and format. -{% image src="/docs/img/using-mcp-in-kilo-code/mcp-installed-config.png" alt="Edit Global MCP and Edit Project MCP buttons" width="600" caption="Edit Global MCP and Edit Project MCP buttons" /%} +{% /tab %} +{% tab label="CLI" %} -Both files use a JSON format with a `mcpServers` object containing named server configurations: +The CLI accepts several config filenames. The recommended file is `kilo.json`: + +| Scope | Recommended Path | Also supported | +| ----------- | ------------------------------------ | -------------------------------------------------------------- | +| **Global** | `~/.config/kilo/kilo.json` | `kilo.jsonc`, `opencode.json`, `opencode.jsonc`, `config.json` | +| **Project** | `./kilo.json` or `./.kilo/kilo.json` | `kilo.jsonc`, `opencode.jsonc`, `opencode.json` | + +{% /tab %} +{% /tabs %} + +## Configuration Format + +{% tabs %} +{% tab label="VSCode (Legacy)" %} + +Both global and project-level files use a JSON format with a `mcpServers` object containing named server configurations: ```json { @@ -51,6 +66,33 @@ Both files use a JSON format with a `mcpServers` object containing named server _Example of MCP Server config in Kilo Code (STDIO Transport)_ +{% /tab %} +{% tab label="VSCode" %} + +In the VS Code extension, open **Settings → MCP** and click **Add Server** to configure a new server through the UI. You can also edit the config files directly — see the **CLI** tab for the JSON format. + +{% /tab %} +{% tab label="CLI" %} + +Add MCP servers under the `mcp` key in your config file. Each server has a unique name that you can reference in prompts. + +```json +{ + "mcp": { + "my-server": { + "type": "local", + "command": ["npx", "-y", "my-mcp-command"], + "enabled": true + } + } +} +``` + +You can disable a server by setting `enabled` to `false` without removing it from your config. + +{% /tab %} +{% /tabs %} + ### Understanding Transport Types MCP supports three transport types for server communication: @@ -69,6 +111,9 @@ For more in-depth information about how STDIO transport works, see [STDIO Transp STDIO configuration example: +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ```json { "mcpServers": { @@ -85,6 +130,42 @@ STDIO configuration example: } ``` +{% /tab %} +{% tab label="VSCode" %} + +In the VS Code extension, open **Settings → MCP**, click **Add Server**, and choose **Local (stdio)**. Fill in the command, arguments, and optional environment variables through the UI. You can also edit the config files directly — see the **CLI** tab for the JSON format. + +{% /tab %} +{% tab label="CLI" %} + +```json +{ + "mcp": { + "my-local-server": { + "type": "local", + "command": ["npx", "-y", "my-mcp-command"], + "enabled": true, + "environment": { + "API_KEY": "your_api_key" + } + } + } +} +``` + +#### Local Server Options + +| Option | Type | Required | Description | +| ------------- | ------- | -------- | --------------------------------------------------------------------- | +| `type` | String | Yes | Must be `"local"`. | +| `command` | Array | Yes | Command and arguments to run the MCP server. | +| `environment` | Object | No | Environment variables to set when running the server. | +| `enabled` | Boolean | No | Enable or disable the MCP server on startup. | +| `timeout` | Number | No | Timeout in ms for fetching tools from the MCP server. Default: 30000. | + +{% /tab %} +{% /tabs %} + #### Streamable HTTP Transport Used for remote servers accessed over HTTP/HTTPS: @@ -94,7 +175,8 @@ Used for remote servers accessed over HTTP/HTTPS: - Requires network access - Allows centralized deployment and management -Streamable HTTP transport configuration example: +{% tabs %} +{% tab label="VSCode (Legacy)" %} ```json { @@ -112,7 +194,43 @@ Streamable HTTP transport configuration example: } ``` -#### SSE Transport +{% /tab %} +{% tab label="VSCode" %} + +In the VS Code extension, open **Settings → MCP**, click **Add Server**, and choose **Remote (HTTP)**. Enter the server URL and optional headers through the UI. You can also edit the config files directly — see the **CLI** tab for the JSON format. + +{% /tab %} +{% tab label="CLI" %} + +```json +{ + "mcp": { + "my-remote-server": { + "type": "remote", + "url": "https://my-mcp-server.com/mcp", + "enabled": true, + "headers": { + "Authorization": "Bearer MY_API_KEY" + } + } + } +} +``` + +#### Remote Server Options + +| Option | Type | Required | Description | +| --------- | ------- | -------- | --------------------------------------------------------------------- | +| `type` | String | Yes | Must be `"remote"`. | +| `url` | String | Yes | URL of the remote MCP server. | +| `enabled` | Boolean | No | Enable or disable the MCP server on startup. | +| `headers` | Object | No | HTTP headers to send with requests. | +| `timeout` | Number | No | Timeout in ms for fetching tools from the MCP server. Default: 30000. | + +{% /tab %} +{% /tabs %} + +### SSE Transport ⚠️ DEPRECATED: The SSE Transport has been deprecated as of MCP specification version 2025-03-26. Please use the HTTP Stream Transport instead, which implements the new Streamable HTTP transport specification. @@ -143,6 +261,24 @@ SSE configuration example: } ``` +## Managing MCP Servers + +{% tabs %} +{% tab label="VSCode (Legacy)" %} + +### Editing MCP Settings Files + +You can edit both global and project-level MCP configuration files directly from the Kilo Code settings. + +1. Click the {% codicon name="gear" /%} icon in the top navigation of the Kilo Code pane to open `Settings`. +2. Click the `Agent Behaviour` tab on the left side +3. Select the `MCP Servers` sub-tab +4. Click the appropriate button: + - **`Edit Global MCP`**: Opens the global `mcp_settings.json` file. + - **`Edit Project MCP`**: Opens the project-specific `.kilocode/mcp.json` file. If this file doesn't exist, Kilo Code will create it for you. + +{% image src="/docs/img/using-mcp-in-kilo-code/mcp-installed-config.png" alt="Edit Global MCP and Edit Project MCP buttons" width="600" caption="Edit Global MCP and Edit Project MCP buttons" /%} + ### Deleting a Server 1. Press the {% codicon name="trash" /%} next to the MCP server you would like to delete @@ -178,41 +314,58 @@ MCP tool auto-approval works on a per-tool basis and is disabled by default. To When enabled, Kilo Code will automatically approve this specific tool without prompting. Note that the global "Use MCP servers" setting takes precedence - if it's disabled, no MCP tools will be auto-approved. -## Finding and Installing MCP Servers +{% /tab %} +{% tab label="VSCode" %} -Kilo Code does not come with any pre-installed MCP servers. You'll need to find and install them separately. +In the VS Code extension, manage MCP servers from **Settings → MCP**: -- **Community Repositories:** Check for community-maintained lists of MCP servers on GitHub -- **Ask Kilo Code:** You can ask Kilo Code to help you find or even create MCP servers -- **Build Your Own:** Create custom MCP servers using the SDK to extend Kilo Code with your own tools +- **Add a server**: Click **Add Server** and fill in the details +- **Enable/disable**: Toggle a server on or off without removing its configuration +- **Delete**: Remove a server from the list -For full SDK documentation, visit the [MCP GitHub repository](https://github.com/modelcontextprotocol/). +The extension also supports the `{env:VARIABLE_NAME}` syntax in config files to reference environment variables (see the **CLI** tab for details). -## Using MCP Tools in Your Workflow +{% /tab %} +{% tab label="CLI" %} -After configuring an MCP server, Kilo Code will automatically detect available tools and resources. To use them: +### CLI Commands -1. Type your request in the Kilo Code chat interface -2. Kilo Code will identify when an MCP tool can help with your task -3. Approve the tool use when prompted (or use auto-approval) +| Command | Description | +| ----------------- | ------------------------------- | +| `kilo mcp list` | List all configured MCP servers | +| `kilo mcp add` | Add an MCP server | +| `kilo mcp auth` | Authenticate with an MCP server | +| `kilo mcp logout` | Log out from an MCP server | +| `kilo mcp debug` | Debug an MCP server connection | -Example: "Analyze the performance of my API" might use an MCP tool that tests API endpoints. +Inside the interactive TUI, use the `/mcps` slash command to toggle MCP servers on or off. -## Troubleshooting MCP Servers +### Environment Variables -Common issues and solutions: +Use `{env:VARIABLE_NAME}` syntax in config files to reference environment variables: -- **Server Not Responding:** Check if the server process is running and verify network connectivity -- **Permission Errors:** Ensure proper API keys and credentials are configured in your `mcp_settings.json` (for global settings) or `.kilocode/mcp.json` (for project settings). -- **Tool Not Available:** Confirm the server is properly implementing the tool and it's not disabled in settings -- **Slow Performance:** Try adjusting the network timeout value for the specific MCP server +```json +{ + "mcp": { + "my-server": { + "type": "remote", + "url": "https://mcp.example.com/mcp", + "headers": { + "Authorization": "Bearer {env:MY_API_KEY}" + } + } + } +} +``` -{% callout type="tip" %} -**Reduce system prompt size:** If you're not using MCP, turn it off in Settings > Agent Behaviour > MCP Servers to significantly cut down the size of the system prompt and improve performance. -{% /callout %} +{% /tab %} +{% /tabs %} ## Platform-Specific MCP Configuration Examples +{% tabs %} +{% tab label="VSCode (Legacy)" %} + ### Windows Configuration Example When setting up MCP servers on Windows, you'll need to use the Windows Command Prompt (`cmd`) to execute commands. Here's an example of configuring a Puppeteer MCP server on Windows: @@ -253,3 +406,93 @@ For macOS or Linux, you would use a different configuration: {% /callout %} The same approach can be used for other MCP servers on Windows, adjusting the package name as needed for different server types. + +{% /tab %} +{% tab label="VSCode" %} + +In the VS Code extension, use **Settings → MCP → Add Server** to add any of the examples below through the UI. You can also edit the config files directly — see the **CLI** tab for the JSON format. + +{% /tab %} +{% tab label="CLI" %} + +### Figma Desktop + +Connect to the Figma Desktop app's MCP server: + +```json +{ + "mcp": { + "Figma Desktop": { + "type": "remote", + "url": "http://127.0.0.1:3845/mcp" + } + } +} +``` + +### Context7 + +Add the [Context7](https://github.com/upstash/context7) MCP server for documentation search: + +```json +{ + "mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp" + } + } +} +``` + +### Everything Test Server + +Add the test MCP server for development: + +```json +{ + "mcp": { + "mcp_everything": { + "type": "local", + "command": ["npx", "-y", "@modelcontextprotocol/server-everything"] + } + } +} +``` + +{% /tab %} +{% /tabs %} + +## Finding and Installing MCP Servers + +Kilo Code does not come with any pre-installed MCP servers. You'll need to find and install them separately. + +- **Kilo Marketplace:** Browse community-contributed MCP server configurations and agent skills in the [Kilo Marketplace](https://github.com/Kilo-Org/kilo-marketplace). The marketplace includes ready-to-use configs for popular tools like Figma, Sentry, and more. +- **Community Repositories:** Check for community-maintained lists of MCP servers on GitHub +- **Ask Kilo Code:** You can ask Kilo Code to help you find or even create MCP servers +- **Build Your Own:** Create custom MCP servers using the SDK to extend Kilo Code with your own tools + +For full SDK documentation, visit the [MCP GitHub repository](https://github.com/modelcontextprotocol/). + +## Using MCP Tools in Your Workflow + +After configuring an MCP server, Kilo Code will automatically detect available tools and resources. To use them: + +1. Type your request in the Kilo Code chat interface +2. Kilo Code will identify when an MCP tool can help with your task +3. Approve the tool use when prompted (or use auto-approval) + +Example: "Analyze the performance of my API" might use an MCP tool that tests API endpoints. + +## Troubleshooting MCP Servers + +Common issues and solutions: + +- **Server Not Responding:** Check if the server process is running and verify network connectivity +- **Permission Errors:** Ensure proper API keys and credentials are configured in your `mcp_settings.json` (for global settings) or `.kilocode/mcp.json` (for project settings). +- **Tool Not Available:** Confirm the server is properly implementing the tool and it's not disabled in settings +- **Slow Performance:** Try adjusting the network timeout value for the specific MCP server + +{% callout type="tip" %} +**Reduce system prompt size:** If you're not using MCP, turn it off in Settings > Agent Behaviour > MCP Servers to significantly cut down the size of the system prompt and improve performance. +{% /callout %} From 6e602f4ad37f89e80ee8c08aa9e3ec7e0c846e1e Mon Sep 17 00:00:00 2001 From: Josh Lambert Date: Tue, 24 Mar 2026 05:35:14 -0400 Subject: [PATCH 020/308] docs(kilo-docs): add platform tabs to AI provider pages Add VSCode (Pre-release) and CLI tabs to all 30 AI provider pages: - index.md: Overview with platform-specific provider configuration - 29 individual provider pages: Each gets VSCode, Pre-release, and CLI configuration tabs with correct provider IDs and env vars Provider IDs verified against packages/opencode/src/provider/: - amazon-bedrock (not bedrock) - fireworks-ai (not fireworks) - chutes (not chutes-ai) - moonshotai (not moonshot) - vercel (not vercel-ai-gateway) Env vars verified: - AI_GATEWAY_API_KEY (not VERCEL_AI_GATEWAY_API_KEY) - OVHCLOUD_API_KEY (not OVH_AI_ENDPOINTS_ACCESS_TOKEN) - GOOGLE_CLOUD_LOCATION (not GOOGLE_CLOUD_REGION) - AICORE_SERVICE_KEY (not SAP_AI_CORE_*) Providers not available in CLI (glama, unbound) show warning callouts. Part of the docs platform tabs effort (PR 8 of 8). Depends on #7497 for infrastructure. --- .../kilo-docs/pages/ai-providers/anthropic.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/bedrock.md | 50 +++++++++++++++++ .../kilo-docs/pages/ai-providers/cerebras.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/chutes-ai.md | 44 +++++++++++++++ .../pages/ai-providers/claude-code.md | 49 +++++++++++++++++ .../kilo-docs/pages/ai-providers/deepseek.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/fireworks.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/gemini.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/glama.md | 20 +++++++ packages/kilo-docs/pages/ai-providers/groq.md | 54 ++++++++++++++----- .../kilo-docs/pages/ai-providers/inception.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/index.md | 6 +-- .../kilo-docs/pages/ai-providers/lmstudio.md | 38 +++++++++++++ .../kilo-docs/pages/ai-providers/minimax.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/mistral.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/moonshot.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/ollama.md | 38 +++++++++++++ .../ai-providers/openai-chatgpt-plus-pro.md | 40 ++++++++++++++ .../pages/ai-providers/openai-compatible.md | 45 ++++++++++++++++ .../kilo-docs/pages/ai-providers/openai.md | 44 +++++++++++++++ .../pages/ai-providers/openrouter.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/ovhcloud.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/requesty.md | 44 +++++++++++++++ .../pages/ai-providers/sap-ai-core.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/unbound.md | 20 +++++++ packages/kilo-docs/pages/ai-providers/v0.md | 45 ++++++++++++++++ .../pages/ai-providers/vercel-ai-gateway.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/vertex.md | 47 ++++++++++++++++ packages/kilo-docs/pages/ai-providers/xai.md | 44 +++++++++++++++ .../kilo-docs/pages/ai-providers/zenmux.md | 44 +++++++++++++++ 30 files changed, 1227 insertions(+), 17 deletions(-) diff --git a/packages/kilo-docs/pages/ai-providers/anthropic.md b/packages/kilo-docs/pages/ai-providers/anthropic.md index 80897edd3cc..767aed584cb 100644 --- a/packages/kilo-docs/pages/ai-providers/anthropic.md +++ b/packages/kilo-docs/pages/ai-providers/anthropic.md @@ -17,12 +17,56 @@ Anthropic is an AI safety and research company that builds reliable, interpretab ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Anthropic" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your Anthropic API key into the "Anthropic API Key" field. 4. **Select Model:** Choose your desired Claude model from the "Model" dropdown. 5. **(Optional) Custom Base URL:** If you need to use a custom base URL for the Anthropic API, check "Use custom base URL" and enter the URL. Most people won't need to adjust this. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add Anthropic and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export ANTHROPIC_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "anthropic": { + "env": ["ANTHROPIC_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "anthropic/claude-sonnet-4-20250514", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Prompt Caching:** Claude 3 models support [prompt caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching), which can significantly reduce costs and latency for repeated prompts. diff --git a/packages/kilo-docs/pages/ai-providers/bedrock.md b/packages/kilo-docs/pages/ai-providers/bedrock.md index ecdb8a6c86d..457955576e5 100644 --- a/packages/kilo-docs/pages/ai-providers/bedrock.md +++ b/packages/kilo-docs/pages/ai-providers/bedrock.md @@ -34,6 +34,9 @@ You have three options for configuring AWS credentials: ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Bedrock" from the "API Provider" dropdown. 3. **Select Authentication Method:** @@ -48,6 +51,53 @@ You have three options for configuring AWS credentials: 5. **(Optional) Cross-Region Inference:** Check "Use cross-region inference" if you want to access models in a region different from your configured AWS region. 6. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add AWS Bedrock. The extension uses the AWS credentials chain for authentication — configure your AWS credentials using the AWS CLI or environment variables before adding the provider. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Bedrock uses the AWS credentials chain for authentication. Configure your AWS credentials using the AWS CLI or environment variables: + +**Environment variables:** + +```bash +export AWS_ACCESS_KEY_ID="your-access-key" +export AWS_SECRET_ACCESS_KEY="your-secret-key" +export AWS_REGION="us-east-1" +``` + +Or use an AWS profile: + +```bash +aws configure --profile bedrock +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "amazon-bedrock": {}, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "bedrock/anthropic.claude-sonnet-4-20250514-v1:0", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Permissions:** Ensure your IAM user or role has the necessary permissions to invoke Bedrock models. The `bedrock:InvokeModel` permission is required. diff --git a/packages/kilo-docs/pages/ai-providers/cerebras.md b/packages/kilo-docs/pages/ai-providers/cerebras.md index 7f965ece593..24c19bdc421 100644 --- a/packages/kilo-docs/pages/ai-providers/cerebras.md +++ b/packages/kilo-docs/pages/ai-providers/cerebras.md @@ -17,11 +17,55 @@ Cerebras is known for their ultra-fast AI inference powered by the Cerebras CS-3 ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Cerebras" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your Cerebras API key into the "Cerebras API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add Cerebras and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export CEREBRAS_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "cerebras": { + "env": ["CEREBRAS_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "cerebras/llama-4-scout-17b-16e-instruct", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Inference Speed:** Cerebras models deliver some of the fastest inference speeds available, reducing wait times during development. diff --git a/packages/kilo-docs/pages/ai-providers/chutes-ai.md b/packages/kilo-docs/pages/ai-providers/chutes-ai.md index d0a4a14f62f..b72af388f2a 100644 --- a/packages/kilo-docs/pages/ai-providers/chutes-ai.md +++ b/packages/kilo-docs/pages/ai-providers/chutes-ai.md @@ -20,11 +20,55 @@ Always refer to the official Chutes AI documentation or your dashboard for the m ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Chutes AI" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your Chutes AI API key into the "Chutes AI API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add Chutes AI and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export CHUTES_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "chutes": { + "env": ["CHUTES_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "chutes-ai/model-name", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Free Access:** Chutes AI provides free API access, making it an excellent option for experimentation and development without immediate costs. diff --git a/packages/kilo-docs/pages/ai-providers/claude-code.md b/packages/kilo-docs/pages/ai-providers/claude-code.md index 7cd5136a435..699a4af7f95 100644 --- a/packages/kilo-docs/pages/ai-providers/claude-code.md +++ b/packages/kilo-docs/pages/ai-providers/claude-code.md @@ -34,11 +34,60 @@ The specific models available depend on your Claude subscription and plan. See [ ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Claude Code" from the "API Provider" dropdown. 3. **Select Model:** Choose your desired Claude model from the "Model" dropdown. 4. **(Optional) Custom CLI Path:** If you installed Claude Code to a location other than the default `claude` command, enter the full path to your Claude executable in the "Claude Code Path" field. Most users won't need to change this. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab. Claude Code uses your existing Anthropic credentials from the `claude` CLI — make sure it is installed and authenticated before adding the provider. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Claude Code uses your existing Anthropic credentials (from the `claude` CLI). Make sure the Claude Code CLI is installed and authenticated: + +```bash +claude --version +claude auth login +``` + +If you have an `ANTHROPIC_API_KEY` environment variable set, the Claude CLI will use it automatically: + +```bash +export ANTHROPIC_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "anthropic": { + "env": ["ANTHROPIC_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "anthropic/claude-sonnet-4-20250514", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **No API Keys Required:** Claude Code uses your existing CLI authentication, so you don't need to manage separate API keys. diff --git a/packages/kilo-docs/pages/ai-providers/deepseek.md b/packages/kilo-docs/pages/ai-providers/deepseek.md index dea4ad27bf8..d70c070f3e8 100644 --- a/packages/kilo-docs/pages/ai-providers/deepseek.md +++ b/packages/kilo-docs/pages/ai-providers/deepseek.md @@ -17,11 +17,55 @@ Kilo Code supports accessing models through the DeepSeek API, including `deepsee ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "DeepSeek" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your DeepSeek API key into the "DeepSeek API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add DeepSeek and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export DEEPSEEK_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "deepseek": { + "env": ["DEEPSEEK_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "deepseek/deepseek-chat", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Pricing:** Refer to the [DeepSeek Pricing](https://api-docs.deepseek.com/quick_start/pricing/) page for details on model costs. diff --git a/packages/kilo-docs/pages/ai-providers/fireworks.md b/packages/kilo-docs/pages/ai-providers/fireworks.md index d89a0796df6..18f08ad7911 100644 --- a/packages/kilo-docs/pages/ai-providers/fireworks.md +++ b/packages/kilo-docs/pages/ai-providers/fireworks.md @@ -17,11 +17,55 @@ Fireworks AI is a high-performance platform for running AI models that offers fa ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Fireworks AI" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your Fireworks AI API key into the "Fireworks AI API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add Fireworks AI and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export FIREWORKS_AI_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "fireworks-ai": { + "env": ["FIREWORKS_AI_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "fireworks/accounts/fireworks/models/llama4-scout-instruct-basic", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Performance:** Fireworks AI is optimized for speed and offers excellent performance for both chat and completion tasks. diff --git a/packages/kilo-docs/pages/ai-providers/gemini.md b/packages/kilo-docs/pages/ai-providers/gemini.md index 4914f9ea7b6..3a0ffe09eec 100644 --- a/packages/kilo-docs/pages/ai-providers/gemini.md +++ b/packages/kilo-docs/pages/ai-providers/gemini.md @@ -17,11 +17,55 @@ Kilo Code supports Google's Gemini family of models through the Google AI Gemini ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Google Gemini" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your Gemini API key into the "Gemini API Key" field. 4. **Select Model:** Choose your desired Gemini model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add Google Gemini and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export GOOGLE_GENERATIVE_AI_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "google": { + "env": ["GOOGLE_GENERATIVE_AI_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "google/gemini-2.5-pro", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Pricing:** Gemini API usage is priced based on input and output tokens. Refer to the [Gemini pricing page](https://ai.google.dev/pricing) for detailed information. diff --git a/packages/kilo-docs/pages/ai-providers/glama.md b/packages/kilo-docs/pages/ai-providers/glama.md index bc50910b431..fb000fc64bb 100644 --- a/packages/kilo-docs/pages/ai-providers/glama.md +++ b/packages/kilo-docs/pages/ai-providers/glama.md @@ -26,11 +26,31 @@ Refer to the [Glama documentation](https://glama.ai/models) for the most up-to-d ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Glama" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your Glama API key into the "Glama API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add Glama and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +{% callout type="warning" %} +Glama is not yet available as a CLI provider. Check the [Kilo Code releases](https://github.com/Kilo-Org/kilocode/releases) for updates on provider support. +{% /callout %} + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Pricing:** Glama operates on a pay-per-use basis. Pricing varies depending on the model you choose. diff --git a/packages/kilo-docs/pages/ai-providers/groq.md b/packages/kilo-docs/pages/ai-providers/groq.md index 77bb3efadbc..58fcf4f1657 100644 --- a/packages/kilo-docs/pages/ai-providers/groq.md +++ b/packages/kilo-docs/pages/ai-providers/groq.md @@ -20,17 +20,54 @@ Kilo Code will attempt to fetch the list of available models from the Groq API. ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Groq" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your Groq API key into the "Groq API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. -## Tips and Notes +{% /tab %} +{% tab label="VSCode" %} -- **High-Speed Inference:** Groq's LPUs provide exceptionally fast response times, making it ideal for interactive development workflows. -- **Token Limits:** Some models have specific `max_tokens` limits that are automatically handled by Kilo Code (e.g., the `moonshotai/kimi-k2-instruct` model). -- **Cost Efficiency:** Groq often provides competitive pricing for high-speed inference compared to other providers. -- **Model Selection:** Choose models based on your specific needs - larger models like `llama3-70b-8192` for complex reasoning tasks, or smaller models like `llama3-8b-8192` for faster, simpler operations. +Open **Settings** (gear icon) and go to the **Providers** tab to add Groq and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export GROQ_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "groq": { + "env": ["GROQ_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "groq/llama-3.3-70b-versatile", +} +``` + +{% /tab %} +{% /tabs %} ## Supported Models @@ -46,13 +83,6 @@ Kilo Code supports the following models through Groq: **Note:** Model availability may change. Refer to the [Groq documentation](https://console.groq.com/docs/models) for the latest model list and specifications. -## Configuration in Kilo Code - -1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. -2. **Select Provider:** Choose "Groq" from the "API Provider" dropdown. -3. **Enter API Key:** Paste your Groq API key into the "Groq API Key" field. -4. **Select Model:** Choose your desired model from the "Model" dropdown. - ## Model-Specific Features ### Kimi K2 Model diff --git a/packages/kilo-docs/pages/ai-providers/inception.md b/packages/kilo-docs/pages/ai-providers/inception.md index 6a8f302e391..8431a37fc6f 100644 --- a/packages/kilo-docs/pages/ai-providers/inception.md +++ b/packages/kilo-docs/pages/ai-providers/inception.md @@ -23,11 +23,55 @@ Refer to Inception's current website and developer documentation for the most up ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Inception" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your Inception API key into the "Inception API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add Inception and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export INCEPTION_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "inception": { + "env": ["INCEPTION_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "inception/mercury-coder-small-beta", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Enterprise Focus:** Inception is designed for production-grade AI applications with emphasis on reliability and consistency. diff --git a/packages/kilo-docs/pages/ai-providers/index.md b/packages/kilo-docs/pages/ai-providers/index.md index 4f75c4e985a..6981043e579 100644 --- a/packages/kilo-docs/pages/ai-providers/index.md +++ b/packages/kilo-docs/pages/ai-providers/index.md @@ -58,11 +58,7 @@ Route requests through unified APIs with additional features: - **Regional** - Better latency in certain locations {% callout type="note" %} -All API keys use VS Code's Secret Storage—never stored in plain text. -{% /callout %} - -{% callout type="warning" title="Time-to-first-byte timeout" %} -For all providers, there is a **five-minute timeout** on time to first token. This means if a provider does not begin streaming a response within five minutes of the request being sent, the request will be cancelled. This is a constraint of the Bun runtime and cannot be easily configured. +In the **VSCode (Legacy)** version, API keys use VS Code's Secret Storage. In the current **VSCode & CLI** version, keys are set via environment variables or referenced in `kilo.json` config files. See individual provider pages for setup instructions for each platform. {% /callout %} ## Next Steps diff --git a/packages/kilo-docs/pages/ai-providers/lmstudio.md b/packages/kilo-docs/pages/ai-providers/lmstudio.md index 13efa7b8361..e22058308b2 100644 --- a/packages/kilo-docs/pages/ai-providers/lmstudio.md +++ b/packages/kilo-docs/pages/ai-providers/lmstudio.md @@ -27,12 +27,50 @@ Kilo Code supports running models locally using LM Studio. LM Studio provides a ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "LM Studio" from the "API Provider" dropdown. 3. **Enter Model ID:** Enter the _file name_ of the model you loaded in LM Studio (e.g., `codellama-7b.Q4_0.gguf`). You can find this in the LM Studio "Local Server" tab. 4. **(Optional) Base URL:** By default, Kilo Code will connect to LM Studio at `http://localhost:1234`. If you've configured LM Studio to use a different address or port, enter the full URL here. 5. **(Optional) Timeout:** By default, API requests time out after 10 minutes. Local models can be slow, if you hit this timeout you can consider increasing it here: VS Code Extensions panel > Kilo Code gear menu > Settings > API Request Timeout. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add LM Studio. No API key is needed since LM Studio runs locally. You can configure the base URL if LM Studio is running on a different host or port. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +LM Studio runs locally, so no API key is needed. Configure the base URL if LM Studio is running on a different host or port: + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "lmstudio": { + "baseURL": "http://localhost:1234/v1", + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "lmstudio/codellama-7b", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Resource Requirements:** Running large language models locally can be resource-intensive. Make sure your computer meets the minimum requirements for the model you choose. diff --git a/packages/kilo-docs/pages/ai-providers/minimax.md b/packages/kilo-docs/pages/ai-providers/minimax.md index 4c6fd6adc5b..4f36072519f 100644 --- a/packages/kilo-docs/pages/ai-providers/minimax.md +++ b/packages/kilo-docs/pages/ai-providers/minimax.md @@ -17,11 +17,55 @@ MiniMax is a global AI foundation model company focused on fast, cost-efficient ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Navigate to **Providers**. Choose **MiniMax** from the API Provider dropdown. 3. **Enter API Key:** Paste your MiniMax API key into the MiniMax API Key field. 4. **Select Model:** Choose your desired MiniMax model from the Model dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add MiniMax and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export MINIMAX_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "minimax": { + "env": ["MINIMAX_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "minimax/MiniMax-M1", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Performance:** MiniMax M2.1 emphasizes fast inference, strong coding ability, and exceptional tool-calling performance. diff --git a/packages/kilo-docs/pages/ai-providers/mistral.md b/packages/kilo-docs/pages/ai-providers/mistral.md index 8a902adb401..e1ce39948b2 100644 --- a/packages/kilo-docs/pages/ai-providers/mistral.md +++ b/packages/kilo-docs/pages/ai-providers/mistral.md @@ -17,11 +17,55 @@ Kilo Code supports accessing models through the Mistral AI API, including both s ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Mistral" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your Mistral API key into the "Mistral API Key" field if you're using a `mistral` model. If you intend to use `codestral-latest`, see the "Codestral" section below. 4. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add Mistral and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export MISTRAL_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "mistral": { + "env": ["MISTRAL_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "mistral/mistral-large-latest", +} +``` + +{% /tab %} +{% /tabs %} + ## Using Codestral [Codestral](https://docs.mistral.ai/capabilities/code_generation/) is a model specifically designed for code generation and interaction. diff --git a/packages/kilo-docs/pages/ai-providers/moonshot.md b/packages/kilo-docs/pages/ai-providers/moonshot.md index 44ee85619a1..c1b97cfe8d6 100644 --- a/packages/kilo-docs/pages/ai-providers/moonshot.md +++ b/packages/kilo-docs/pages/ai-providers/moonshot.md @@ -17,11 +17,55 @@ Moonshot.ai is a Chinese AI company known for their **Kimi** models featuring ul ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Moonshot.ai" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your Moonshot.ai API key into the "Moonshot.ai API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add Moonshot.ai and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export MOONSHOT_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "moonshotai": { + "env": ["MOONSHOT_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "moonshot/moonshot-v1-auto", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Ultra-Long Context:** Kimi models excel at handling large codebases and complex projects with their extended context windows. diff --git a/packages/kilo-docs/pages/ai-providers/ollama.md b/packages/kilo-docs/pages/ai-providers/ollama.md index d50417072ca..33f8199e24e 100644 --- a/packages/kilo-docs/pages/ai-providers/ollama.md +++ b/packages/kilo-docs/pages/ai-providers/ollama.md @@ -72,12 +72,50 @@ By default, API requests time out after 10 minutes. Local models can be slow, if ### Configure Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + - Open the Kilo Code panel ({% kiloCodeIcon size="1em" /%}). - Click the Settings gear icon ({% codicon name="gear" /%}). - Select "Ollama" as the API Provider. - Select the model configured in the previous step. - (Optional) You can configure the base URL if you're running Ollama on a different machine. The default is `http://localhost:11434`. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add Ollama. No API key is needed since Ollama runs locally. You can configure the base URL if Ollama is running on a different host. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Ollama runs locally, so no API key is needed. Configure the base URL if Ollama is running on a different host: + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "ollama": { + "baseURL": "http://localhost:11434/v1", + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "ollama/qwen3-coder:30b", +} +``` + +{% /tab %} +{% /tabs %} + ## Further Reading Refer to the [Ollama documentation](https://ollama.com/docs) for more information on installing, configuring and using Ollama. diff --git a/packages/kilo-docs/pages/ai-providers/openai-chatgpt-plus-pro.md b/packages/kilo-docs/pages/ai-providers/openai-chatgpt-plus-pro.md index 2e2105f8367..4f24ddc2908 100644 --- a/packages/kilo-docs/pages/ai-providers/openai-chatgpt-plus-pro.md +++ b/packages/kilo-docs/pages/ai-providers/openai-chatgpt-plus-pro.md @@ -4,6 +4,9 @@ sidebar_label: ChatGPT Plus/Pro # Using ChatGPT Subscriptions With Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. Open Kilo Code settings (click the gear icon {% codicon name="gear" /%} in the Kilo Code panel). 2. In **API Provider**, select **OpenAI – ChatGPT Plus/Pro**. 3. Click **Sign in to OpenAI Codex**. @@ -11,6 +14,43 @@ sidebar_label: ChatGPT Plus/Pro 5. Back in Kilo Code settings, pick a model from the dropdown. 6. Save. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab. ChatGPT Plus/Pro uses OAuth authentication — follow the sign-in flow to connect your ChatGPT subscription. + +{% /tab %} +{% tab label="CLI" %} + +ChatGPT Plus/Pro uses OAuth authentication, which is only available in the VS Code extension. For the CLI, use the [OpenAI API provider](/docs/ai-providers/openai) with an API key instead: + +```bash +export OPENAI_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "openai": { + "env": ["OPENAI_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "openai/gpt-4.1", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Subscription Required:** You need an active ChatGPT Plus or Pro subscription. This provider won't work with free ChatGPT accounts. See [OpenAI's ChatGPT plans](https://openai.com/chatgpt/pricing) for more information. diff --git a/packages/kilo-docs/pages/ai-providers/openai-compatible.md b/packages/kilo-docs/pages/ai-providers/openai-compatible.md index f550cbab7cb..5e373573752 100644 --- a/packages/kilo-docs/pages/ai-providers/openai-compatible.md +++ b/packages/kilo-docs/pages/ai-providers/openai-compatible.md @@ -14,6 +14,9 @@ This document focuses on setting up providers _other than_ the official OpenAI A ## General Configuration +{% tabs %} +{% tab label="VSCode (Legacy)" %} + The key to using an OpenAI-compatible provider is to configure two main settings: 1. **Base URL:** This is the API endpoint for the provider. It will _not_ be `https://api.openai.com/v1` (that's for the official OpenAI API). @@ -34,6 +37,48 @@ You'll find these settings in the Kilo Code settings panel (click the {% codicon - Input Price - Output Price +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add an OpenAI Compatible provider. Enter your API key and the provider's base URL. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key and base URL as environment variables or configure them in your `kilo.json` config file: + +**Environment variable:** + +```bash +export OPENAI_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "openai-compatible": { + "env": ["OPENAI_API_KEY"], + "baseURL": "https://api.your-provider.com/v1", + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "openai-compatible/model-name", +} +``` + +{% /tab %} +{% /tabs %} + ### Full Endpoint URL Support Kilo Code supports full endpoint URLs in the Base URL field, providing greater flexibility for provider configuration: diff --git a/packages/kilo-docs/pages/ai-providers/openai.md b/packages/kilo-docs/pages/ai-providers/openai.md index 73dbb8904c7..4c5a379b539 100644 --- a/packages/kilo-docs/pages/ai-providers/openai.md +++ b/packages/kilo-docs/pages/ai-providers/openai.md @@ -17,11 +17,55 @@ Kilo Code supports accessing models directly through the official OpenAI API. ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "OpenAI" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your OpenAI API key into the "OpenAI API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add OpenAI and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export OPENAI_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "openai": { + "env": ["OPENAI_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "openai/gpt-4.1", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Pricing:** Refer to the [OpenAI Pricing](https://openai.com/pricing) page for details on model costs. diff --git a/packages/kilo-docs/pages/ai-providers/openrouter.md b/packages/kilo-docs/pages/ai-providers/openrouter.md index 84019fa69e9..bdcbbf1a528 100644 --- a/packages/kilo-docs/pages/ai-providers/openrouter.md +++ b/packages/kilo-docs/pages/ai-providers/openrouter.md @@ -16,12 +16,56 @@ OpenRouter is an AI platform that provides access to a wide variety of language ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "OpenRouter" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your OpenRouter API key into the "OpenRouter API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. 5. **(Optional) Custom Base URL:** If you need to use a custom base URL for the OpenRouter API, check "Use custom base URL" and enter the URL. Leave this blank for most users. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add OpenRouter and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export OPENROUTER_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "openrouter": { + "env": ["OPENROUTER_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "openrouter/anthropic/claude-sonnet-4-20250514", +} +``` + +{% /tab %} +{% /tabs %} + ## Supported Transforms OpenRouter provides an [optional "middle-out" message transform](https://openrouter.ai/docs/features/message-transforms) to help with prompts that exceed the maximum context size of a model. You can enable it by checking the "Compress prompts and message chains to the context size" box. diff --git a/packages/kilo-docs/pages/ai-providers/ovhcloud.md b/packages/kilo-docs/pages/ai-providers/ovhcloud.md index 344cb130e9b..7b9890a2598 100644 --- a/packages/kilo-docs/pages/ai-providers/ovhcloud.md +++ b/packages/kilo-docs/pages/ai-providers/ovhcloud.md @@ -24,7 +24,51 @@ You can report any bugs or feedbacks by chatting with us in our [Discord server] ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "OVHcloud AI Endpoints" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your AI Endpoints API key into the "OVHcloud AI Endpoints API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. + +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add OVHcloud AI Endpoints and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export OVHCLOUD_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "ovhcloud": { + "env": ["OVHCLOUD_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "ovhcloud/model-name", +} +``` + +{% /tab %} +{% /tabs %} diff --git a/packages/kilo-docs/pages/ai-providers/requesty.md b/packages/kilo-docs/pages/ai-providers/requesty.md index 6fc4a656d9a..fda3c5796e3 100644 --- a/packages/kilo-docs/pages/ai-providers/requesty.md +++ b/packages/kilo-docs/pages/ai-providers/requesty.md @@ -15,11 +15,55 @@ Kilo Code supports accessing models through the [Requesty](https://www.requesty. ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Requesty" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your Requesty API key into the "Requesty API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add Requesty and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export REQUESTY_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "requesty": { + "env": ["REQUESTY_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "requesty/anthropic/claude-sonnet-4-20250514", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Optimizations**: Requesty offers range of in-flight cost optimizations to lower your costs. diff --git a/packages/kilo-docs/pages/ai-providers/sap-ai-core.md b/packages/kilo-docs/pages/ai-providers/sap-ai-core.md index 6c110a58cc8..16dfec8bbdf 100644 --- a/packages/kilo-docs/pages/ai-providers/sap-ai-core.md +++ b/packages/kilo-docs/pages/ai-providers/sap-ai-core.md @@ -77,6 +77,9 @@ The exact list of available models depends on your SAP AI Core configuration and ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "SAP AI Core" from the "API Provider" dropdown. 3. **Enter Credentials:** @@ -91,6 +94,47 @@ The exact list of available models depends on your SAP AI Core configuration and 5. **Select Model:** Choose your desired model from the dropdown 6. **Select Deployment:** (Foundation Models Mode only) Choose an active deployment for your selected model +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add SAP AI Core. Enter your OAuth2 client credentials (Client ID, Client Secret, Base URL, and Auth URL) in the provider settings. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +SAP AI Core uses OAuth2 client credentials for authentication. Set the credentials as environment variables or in your config file: + +**Environment variables:** + +```bash +export AICORE_SERVICE_KEY='{"your": "service-key-json"}' +export AICORE_DEPLOYMENT_ID="your-deployment-id" +export AICORE_RESOURCE_GROUP="your-resource-group" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "sap-ai-core": {}, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "sap-ai-core/model-name", +} +``` + +{% /tab %} +{% /tabs %} + ## Deployments (Foundation Models Mode) When using Foundation Models mode: diff --git a/packages/kilo-docs/pages/ai-providers/unbound.md b/packages/kilo-docs/pages/ai-providers/unbound.md index 11e061a91ab..fd7f6fb6e27 100644 --- a/packages/kilo-docs/pages/ai-providers/unbound.md +++ b/packages/kilo-docs/pages/ai-providers/unbound.md @@ -20,11 +20,31 @@ Unbound allows you configure a list of supported models in your application, and ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Unbound" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your Unbound API key into the "Unbound API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add Unbound and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +{% callout type="warning" %} +Unbound is not yet available as a CLI provider. Check the [Kilo Code releases](https://github.com/Kilo-Org/kilocode/releases) for updates on provider support. +{% /callout %} + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Security Focus:** Unbound emphasizes security features for enterprise use. If your organization has strict security requirements for AI usage, Unbound might be a good option. diff --git a/packages/kilo-docs/pages/ai-providers/v0.md b/packages/kilo-docs/pages/ai-providers/v0.md index 5d8d0280bc3..2ba2ba4ac67 100644 --- a/packages/kilo-docs/pages/ai-providers/v0.md +++ b/packages/kilo-docs/pages/ai-providers/v0.md @@ -15,6 +15,9 @@ To use v0 with Kilo Code, you'll need: ## Configuration +{% tabs %} +{% tab label="VSCode (Legacy)" %} + Setting up v0 in Kilo Code is straightforward: 1. In Kilo Code settings (click the {% codicon name="gear" /%} icon): @@ -26,6 +29,48 @@ Setting up v0 in Kilo Code is straightforward: +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add an OpenAI Compatible provider. Set the base URL to `https://api.v0.dev/v1` and enter your v0 API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +v0 uses the OpenAI-compatible provider. Set the API key and base URL in your config: + +**Environment variable:** + +```bash +export OPENAI_API_KEY="your-v0-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "openai-compatible": { + "env": ["OPENAI_API_KEY"], + "baseURL": "https://api.v0.dev/v1", + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "openai-compatible/v0-1.0-md", +} +``` + +{% /tab %} +{% /tabs %} + ## Troubleshooting - **"Invalid API Key":** Double-check that you've entered the API key correctly. diff --git a/packages/kilo-docs/pages/ai-providers/vercel-ai-gateway.md b/packages/kilo-docs/pages/ai-providers/vercel-ai-gateway.md index 3147a1ac9a2..aba308e59e3 100644 --- a/packages/kilo-docs/pages/ai-providers/vercel-ai-gateway.md +++ b/packages/kilo-docs/pages/ai-providers/vercel-ai-gateway.md @@ -54,11 +54,55 @@ Check the model description in the dropdown for specific capabilities. ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "Vercel AI Gateway" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your Vercel AI Gateway API key into the "Vercel AI Gateway API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add Vercel AI Gateway and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export AI_GATEWAY_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "vercel": { + "env": ["AI_GATEWAY_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "vercel-ai-gateway/anthropic/claude-sonnet-4", +} +``` + +{% /tab %} +{% /tabs %} + --- ## Prompt Caching diff --git a/packages/kilo-docs/pages/ai-providers/vertex.md b/packages/kilo-docs/pages/ai-providers/vertex.md index 994a84b7b31..abbb56da3b8 100644 --- a/packages/kilo-docs/pages/ai-providers/vertex.md +++ b/packages/kilo-docs/pages/ai-providers/vertex.md @@ -20,6 +20,9 @@ Kilo Code supports accessing models through Google Cloud Platform's Vertex AI, a ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "GCP Vertex AI" from the "API Provider" dropdown. 3. **Configure Authentication:** @@ -31,6 +34,50 @@ Kilo Code supports accessing models through Google Cloud Platform's Vertex AI, a 5. **Select Region:** Choose the region where your Vertex AI resources are located (e.g., `us-east5`). 6. **Select Model:** Choose your desired model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add GCP Vertex AI. The extension uses Google Application Default Credentials (ADC) for authentication — run `gcloud auth application-default login` before adding the provider. Set your project ID and region in the provider settings. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Vertex AI uses Google Application Default Credentials (ADC) for authentication. Set up ADC using the Google Cloud CLI: + +```bash +gcloud auth application-default login +``` + +Set your project and region as environment variables: + +```bash +export GOOGLE_CLOUD_PROJECT="your-project-id" +export GOOGLE_CLOUD_LOCATION="us-east5" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "google-vertex": {}, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "google-vertex/claude-sonnet-4@20250514", +} +``` + +{% /tab %} +{% /tabs %} + ## Tips and Notes - **Permissions:** Ensure your Google Cloud account has the necessary permissions to access Vertex AI and the specific models you want to use. diff --git a/packages/kilo-docs/pages/ai-providers/xai.md b/packages/kilo-docs/pages/ai-providers/xai.md index 309bd4f0c35..5435c6c7ecd 100644 --- a/packages/kilo-docs/pages/ai-providers/xai.md +++ b/packages/kilo-docs/pages/ai-providers/xai.md @@ -17,11 +17,55 @@ xAI is the company behind Grok, a large language model known for its conversatio ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon ({% codicon name="gear" /%}) in the Kilo Code panel. 2. **Select Provider:** Choose "xAI" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your xAI API key into the "xAI API Key" field. 4. **Select Model:** Choose your desired Grok model from the "Model" dropdown. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add xAI and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export XAI_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "xai": { + "env": ["XAI_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "xai/grok-3", +} +``` + +{% /tab %} +{% /tabs %} + ## Reasoning Capabilities Some models feature specialized reasoning capabilities, allowing them to "think before responding" - particularly useful for complex problem-solving tasks. diff --git a/packages/kilo-docs/pages/ai-providers/zenmux.md b/packages/kilo-docs/pages/ai-providers/zenmux.md index 1e646d1b258..de7985830eb 100644 --- a/packages/kilo-docs/pages/ai-providers/zenmux.md +++ b/packages/kilo-docs/pages/ai-providers/zenmux.md @@ -16,12 +16,56 @@ import Codicon from "@site/src/components/Codicon"; ## Configuration in Kilo Code +{% tabs %} +{% tab label="VSCode (Legacy)" %} + 1. **Open Kilo Code Settings:** Click the gear icon () in the Kilo Code panel. 2. **Select Provider:** Choose "ZenMux" from the "API Provider" dropdown. 3. **Enter API Key:** Paste your ZenMux API key into the "ZenMux API Key" field. 4. **Select Model:** Choose your desired model from the "Model" dropdown. 5. **(Optional) Custom Base URL:** If you need to use a custom base URL for the ZenMux API, check "Use custom base URL" and enter the URL. Leave this blank for most users. +{% /tab %} +{% tab label="VSCode" %} + +Open **Settings** (gear icon) and go to the **Providers** tab to add ZenMux and enter your API key. + +The extension stores this in your `kilo.json` config file. You can also edit the config file directly — see the **CLI** tab for the file format. + +{% /tab %} +{% tab label="CLI" %} + +Set the API key as an environment variable or configure it in your `kilo.json` config file: + +**Environment variable:** + +```bash +export ZENMUX_API_KEY="your-api-key" +``` + +**Config file** (`~/.config/kilo/kilo.json` or `./kilo.json`): + +```jsonc +{ + "provider": { + "zenmux": { + "env": ["ZENMUX_API_KEY"], + }, + }, +} +``` + +Then set your default model: + +```jsonc +{ + "model": "zenmux/openai/gpt-5", +} +``` + +{% /tab %} +{% /tabs %} + ## Supported Models ZenMux supports a wide range of models from various providers: From 373bbf84f29c347863a38675cecb8a2c47c9507c Mon Sep 17 00:00:00 2001 From: Josh Lambert Date: Wed, 25 Mar 2026 00:55:59 -0400 Subject: [PATCH 021/308] docs(kilo-docs): add platform tabs infrastructure and getting-started pages Combines infrastructure (PR 1) and getting-started content (PR 2) into a single reviewable PR. Infrastructure: - Platform type (legacy/new/all) in NavLink interface - PageVersionSwitcher banner for legacy-only and new-only pages - PlatformBadge component in SideNav with Legacy/New labels - Tabs hydration fix (SSR-safe useState + useEffect) - _app.tsx reads frontmatter.platform and renders banner Getting Started pages with tab content: - quickstart.md: Auth flow, kilo run --auto, config overview - setup-authentication.md: Tabbed auth flows per platform - settings/index.md: Config locations, precedence, export/import - auto-approving-actions.md: Per-tool permission system Platform markers: - settings/auto-cleanup.md: platform: legacy (frontmatter + nav) - settings/system-notifications.md: platform: legacy (frontmatter + nav) Fixes from code validation and PR review: - Remove false Variable Substitution section (does not exist) - Replace misleading provider env config format - Fix 'most tools prompt for approval' (default is mostly allow) - Add warning about secrets in kilo.json for version control - Fix experimental features tab referencing VSCode instead of Legacy --- .../components/PageVersionSwitcher.tsx | 5 +- packages/kilo-docs/components/TopNav.tsx | 5 +- packages/kilo-docs/lib/nav/getting-started.ts | 8 +- .../pages/getting-started/installing.md | 45 +--- .../pages/getting-started/quickstart.md | 107 +++++++- .../settings/auto-approving-actions.md | 240 +++++++++++++++++- .../getting-started/settings/auto-cleanup.md | 4 + .../pages/getting-started/settings/index.md | 120 ++++++++- .../settings/system-notifications.md | 1 + .../getting-started/setup-authentication.md | 66 ++++- 10 files changed, 556 insertions(+), 45 deletions(-) diff --git a/packages/kilo-docs/components/PageVersionSwitcher.tsx b/packages/kilo-docs/components/PageVersionSwitcher.tsx index 1ff9ec3a91a..2c793355602 100644 --- a/packages/kilo-docs/components/PageVersionSwitcher.tsx +++ b/packages/kilo-docs/components/PageVersionSwitcher.tsx @@ -14,8 +14,8 @@ export function PageVersionSwitcher({ platform }: Props) { {legacy ? "\u24D8" : "\u2728"} {legacy - ? "This page documents the legacy VSCode extension. The current VSCode extension & CLI does not have an equivalent page yet." - : "This page documents the current VSCode extension & CLI. There is no equivalent page for the legacy VSCode extension."} + ? "This page applies to the legacy VSCode extension." + : "This page applies to the current VSCode extension & CLI."}