diff --git a/packages/kilo-docs/pages/automate/agent-manager.md b/packages/kilo-docs/pages/automate/agent-manager.md index 07d13b6bc730..d620a371d1d8 100644 --- a/packages/kilo-docs/pages/automate/agent-manager.md +++ b/packages/kilo-docs/pages/automate/agent-manager.md @@ -87,6 +87,14 @@ Every stored post includes the receipt text "Stored only. This does not confirm The panel opens as an editor tab and stays active across focus changes. +## Introduction for new sessions + +New and empty sessions show an inline introduction to parallel worktrees instead of the standard welcome. It uses two example worktree cards to preview branches, changes, and PR status, with guidance on bringing changes back and resolving conflicts. The preview is illustrative — it does not create worktrees, query GitHub, or start a model request. + +- Select **Create a worktree** to start your first isolated session, or **Read the guide** to open the [Agent Manager Workflows](/docs/automate/agent-manager-workflows) guide. +- Select **Skip introduction** to restore the normal welcome with recent-session history and Feedback & Support. The **How Agent Manager works** control on the welcome screen shows the introduction again inline without losing your draft. +- Kilo remembers your choice across sessions and reloads. + ## Requirements - Open a VS Code workspace folder @@ -103,6 +111,15 @@ Agent Manager worktree defaults belong to a repository. Open a project's setting The **Worktree Setup Script** control opens or creates the setup script for the selected repository. See [Setup Scripts](#setup-scripts) for supported filenames and execution behavior. +### Branch naming + +The **Agent Manager** settings tab also has controls that apply to every project: + +- **Automatic branch naming** (on by default) — Kilo names a session's branch automatically once the conversation describes a clear task. Explicitly named branches, and branches that are already published, are never renamed. +- **Branch prefix** — prefix for automatically named branches, for example `feature/`. It does not apply to explicit branch names. Leave it empty for no prefix. + +These controls use the settings page's normal Save/Discard flow. + ## Providers and Authentication Agent Manager uses the same sign-in, provider settings, models, BYOK keys, custom providers, MCP servers, and permission rules as the extension sidebar. Configure them from extension Settings and they apply to Agent Manager as well. @@ -119,7 +136,9 @@ In a managed worktree's chat, type `/update-from-base` and select the action to The saved base stays the same if you switch branches in Local or change the project's default base. For example, a worktree created from `main` still updates from `main` when Local has `release` checked out. If you switch branches inside the managed worktree, the agent updates that worktree's current branch, not its original branch. Select the intended worktree before running the command; it does not update Local. -The agent uses the recorded remote, or the saved base branch's upstream if no remote was recorded. It asks for a source if the base is local-only or unavailable. The request prohibits stashing, discarding uncommitted work, and pushing. Existing merge or rebase operations and blocking dirty changes require your input. Normal tool approvals still apply. +The agent uses the recorded remote, or the saved base branch's upstream if no remote was recorded. It asks for a source if the base is local-only or unavailable. + +The update preserves local work without asking how to save it. The agent keeps every staged, unstaged, and untracked change in a verified recovery copy unique to that worktree, temporarily clears those edits to merge the base, then restores them and their staging state. Unfinished work stays uncommitted and out of the merge commit, and the recovery copy is kept until restoration is verified. Kilo never uses the shared Git stash stack and never touches another worktree's recovery data. A preservation step it cannot verify, an existing merge or rebase, and conflicts that need a decision about intended behavior all stop and ask. Normal tool approvals still apply. ### Worktree Location @@ -249,7 +268,7 @@ Sending a thread gives it to Kilo as review context, and it does not post anythi #### Checks -Each failing check offers **Fix with Kilo**, which sends the failure summary and log commands to the current agent. With an active Agent Manager terminal, the label becomes **Send failures to terminal**. +When any check fails or is cancelled, the Checks section offers **Fix with Kilo**, which sends a bounded failure summary and log commands for the failed jobs to the current agent. With an active Agent Manager terminal, the label becomes **Send failures to terminal**. #### Conversation @@ -261,7 +280,7 @@ The conversation lists the pull request description and history in one timeline: - **Lifecycle events:** merged, closed, reopened, and force-push, with the actor - **Show earlier activity** when GitHub has timeline items before the loaded window. It opens the pull request on GitHub. -Use a comment card's **Fix with Kilo** action to hand it to the agent. **Dismiss** hides a comment from the next send, and **Restore** brings it back. **Fix N with Kilo** or **Send N to terminal** sends the actionable comments together. +Use a comment card's **Fix with Kilo** action to hand it to the agent. **Dismiss** hides a comment from the next send, and **Restore** brings it back. **Fix N with Kilo** or **Send N to terminal** sends the actionable comments together. **Copy comment** copies a card as markdown. Bot comments are collapsed by default and marked with a bot badge, and batch sends skip bot comments, dismissed comments, and comments you already sent. #### Reviewers @@ -280,11 +299,13 @@ The Reviewers section shows each requested or completed reviewer with an avatar ### Creating a New Worktree Session 1. Click **New Worktree** or press `Cmd+N` (macOS) / `Ctrl+N` (Windows/Linux) to open the new worktree dialog -2. Enter a branch name (or let Kilo generate one) +2. Optionally expand **Advanced options** to set a branch name; otherwise Kilo generates one 3. Type your first message, then create the worktree Kilo creates the worktree from the selected project's configured default base branch. In a multi-project workspace, the selected project determines this setting. An explicit base branch selected in the dialog takes precedence. If no default is configured, Kilo falls back to automatic detection of the repository's remote default branch. The agent works in isolation, so your main branch is unaffected. +An explicit branch name is preserved exactly, including slashes, case, and punctuation. An invalid Git branch name is rejected, and your prompt and attachments are kept. + To create a worktree immediately from the default base branch, press `Cmd+Shift+N` (macOS) / `Ctrl+Shift+N` (Windows/Linux). This uses the selected project's configured default, or the automatic remote-default fallback when no configured default exists. ### Slash Commands in the Worktree Prompt @@ -398,6 +419,8 @@ Use `Cmd+T` / `Ctrl+T` in the panel, or `mode: "local"` with a selected `worktre - **Sessions in one worktree:** Use targeted `agent_manager` prompts for conversation. They also see the same files, commits, and branch, so coordinate before making overlapping edits. - **Sessions in different worktrees:** Use targeted prompts plus commits, diffs, or pull requests to pass changes between isolated checkouts. Files are not shared automatically. - **Task descendants:** A `task` child belongs to the session that launched it. Its Kilo Swarm board is scoped to that session tree, not to every Agent Manager session in the project. +- **Peer requests and replies:** An agent can send a prompt to another session, and the receiving agent can reply to the exact originating session. Replies enter the source session through its normal prompt queue, so a busy session queues the reply behind its active work instead of rejecting it. Peer requests and replies are coordination data, not user instructions or approval. +- **Message attribution:** When Kilo delivers a prompt on behalf of another session, the message shows a **Sent by Kilo from another session** label. Select the arrow next to it to switch to the originating session and its worktree. If the originating session is closed, the label shows **Session not open** instead, and the marker is hidden from the displayed and copied message text. ## Sections @@ -439,7 +462,7 @@ Right-click the section header and select **Delete Section**. The section is rem ## Sending Messages, Approvals, and Control - **Continue the conversation:** Send a follow-up message to the running agent -- **Approvals:** The Permission Dock shows tool approval prompts — approve once, approve always, or deny +- **Approvals:** The Permission Dock shows tool approval prompts — approve once, approve always, or deny. Denying opens an optional feedback field so the agent can revise its proposal before retrying - **Cancel:** Sends a cooperative stop signal to the agent - **Stop:** Force-terminates the session and marks it as stopped @@ -465,13 +488,20 @@ The worktree creation base and the diff comparison base are separate. The Branch ### Sending review comments -Add comments in the diff panel or in the rendered view of a Markdown document. Click **Send all to chat** to send the collected comments to chat. If an Agent Manager terminal is active, the comments are sent to that terminal instead. Press `Cmd+Enter` (macOS) or `Ctrl+Enter` (Windows/Linux) to use the same action from the review panel. +Add comments in the diff panel or in the rendered view of a Markdown document. In the composer, **Save** keeps the comment in the review collection, and the primary action sends it to the active session. If an Agent Manager terminal is active, it goes to that terminal instead. When the diff belongs to a checked-out pull request, the primary action becomes a split button that can also post the comment to the pull request: + +- **Send to Kilo** sends the comment to the session or Agent Manager terminal. +- **Send to GitHub #PR** posts the comment to the pull request. Open the chevron next to the split button to switch destinations. If the line is not part of the current pull request snapshot, the composer reports that it cannot be posted. + +`Enter` sends to Kilo and `Cmd+Enter` (macOS) / `Ctrl+Enter` (Windows/Linux) saves locally. Publishing to GitHub always requires a click. + +The review toolbar sends the whole collection at once. **Send all to chat (N)** sends every collected comment to Kilo, and **Send N to GitHub #PR** posts the comments that map to the pull request. Only the chat action carries the keyboard shortcut. If a GitHub post fails partway through, the posted comments are removed and the rest stay in the collection for a retry. After sending, the local comment collection is cleared. To discard collected comments without sending them, click **Clear all** in the chat input. ### PR review comments in the diff -When the selected worktree has an associated pull request, its review threads also appear inline at their file and line in the Agent Manager diff panel and the full-screen review. The inline cards support the same reply, resolve, unresolve, reaction, and send actions as the PR panel. Threads with no matching line in the current diff appear under **Comments outside the current diff**. +When the selected worktree has an associated pull request, its review threads also appear inline at their file and line in the Agent Manager diff panel, the full-screen review, and the Changes diff view. The inline cards support the same reply, resolve, unresolve, reaction, and send actions as the PR panel. Threads with no matching line in the current diff appear under **Comments outside the current diff**. ### Diff Scope @@ -501,6 +531,24 @@ In a rendered Markdown preview, use the comment control in the line gutter to ad The project and worktree context owns document tabs, loaded content, and comments. The session ID attached to an opened file selects the session's worktree for reading and native-editor navigation. Sessions that share one worktree also share its document inspector state; switching project or worktree changes the visible context without mixing tabs or comments across worktrees. +## Browser previews + +{% callout type="info" %} +Browser previews are experimental and off by default. Enable **Browser Automation** in the VS Code **Experimental** settings, or set `kilo-code.new.experimental.browserAutomation` to `true`. The Browser panel stays hidden until it is enabled. +{% /callout %} + +The Browser panel previews a local application beside the agent and embeds a matching Chromium developer-tools frontend for the page. It is session-scoped: each Agent Manager session gets its own browser, and the panel follows the selected session. + +Open the panel with the **Browser** button in the Agent Manager toolbar, enter a local application URL (for example `http://localhost:3000`), and select **Open**. Use **Refresh** to reload the visible page and **Close** to stop the browser. The panel lists recent automation events and page console errors in its diagnostics area; security blocks from the automation browser appear there as diagnostics, not as page errors. + +The agent can also open the page itself with the `browser_open` tool when it needs to inspect a local application. The tool is limited to HTTP URLs on `localhost` or `127.0.0.1`, and it returns the page status, console diagnostics, and a screenshot. + +### Element feedback + +Select **Select element**, then select an element in the preview to add a reference to the chat input. A reference captures a unique selector, a short DOM breadcrumb, sanitized HTML, the element's text, and its computed text and background colors, plus a source file and line when the page provides a verifiable source location. Add your instruction and send the message; the agent receives a compact context block and the transcript renders the reference as a collapsible card. + +Capture stays bounded. It does not copy the whole subtree, hidden or editable content, input values, event handlers, arbitrary attributes, unrelated console logs, or element geometry. + ## Terminals Each session has a dedicated terminal rooted in the session's worktree directory. Press `Cmd+/` (macOS) / `Ctrl+/` (Windows/Linux) to focus the terminal for the active session. If the embedded terminal is already visible but the prompt has focus, the same shortcut focuses the terminal without hiding it. Press it again while the terminal has focus to hide the panel. @@ -511,10 +559,10 @@ When you use `@terminal` in an Agent Manager prompt, Kilo captures the focused t The toolbar's terminal button is a split button: click it to open a terminal, or use its dropdown to choose where terminals open: -- **VS Code terminal** (default) — opens or focuses the VS Code integrated terminal at the bottom of the window -- **Agent Manager panel** — opens an embedded terminal in the side panel that also hosts the diff view, so the shell stays inside the Agent Manager layout +- **Agent Manager panel** (default) — opens an embedded terminal in the side panel that also hosts the diff view, so the shell stays inside the Agent Manager layout +- **VS Code terminal** — opens or focuses the VS Code integrated terminal at the bottom of the window -The dropdown choice is remembered per panel and becomes the default for new panels. You can also set the default directly with the `kilo-code.new.agentManager.terminalButtonDestination` setting (`vscode` or `agentManager`). The `Cmd+/` (macOS) / `Ctrl+/` (Windows/Linux) shortcut follows the same destination. +The dropdown choice is remembered per panel and becomes the default for new panels. You can also set the default directly with the `kilo-code.new.agentManager.terminalButtonDestination` setting (`vscode` or `agentManager`). An unrecognized setting falls back to the VS Code terminal. The `Cmd+/` (macOS) / `Ctrl+/` (Windows/Linux) shortcut follows the same destination. With the **Agent Manager panel** destination, the terminal works like the diff panel: press `Cmd+/` to reveal and focus it, press it while the panel is visible but another control has focus to move focus into the terminal, and press it again from the terminal to hide it. Hiding never stops the terminal — scrollback and running processes continue in the background, and focus returns to the chat input. A terminal stops only when you click its close button or type `exit` in the shell. diff --git a/packages/kilo-docs/pages/automate/integrations.md b/packages/kilo-docs/pages/automate/integrations.md index fb2146f314ef..a15c87656770 100644 --- a/packages/kilo-docs/pages/automate/integrations.md +++ b/packages/kilo-docs/pages/automate/integrations.md @@ -63,6 +63,10 @@ Once approved: - GitHub will show a **Connected** status. - Your Kilo workspace can now access GitHub repositories securely. +### 5. Choose the GitHub AI model + +The GitHub integration panel includes an **AI Model** selector that sets which model Kilo uses when it responds to `@kilocode-bot` mentions on GitHub issues and pull requests. A personal integration has one selector. An organization integration shows a selector for each connected GitHub installation, so you can give each installation its own model. Changing an organization's model requires permission to manage organization billing. + --- ## Connecting GitLab diff --git a/packages/kilo-docs/pages/automate/tools/index.md b/packages/kilo-docs/pages/automate/tools/index.md index 97e5211fc2d9..6bcb8a2d835e 100644 --- a/packages/kilo-docs/pages/automate/tools/index.md +++ b/packages/kilo-docs/pages/automate/tools/index.md @@ -118,6 +118,8 @@ These tools help manage the conversation and task flow: - `todoread` - Reads the current session TODO list - `plan` - Enters structured planning mode - `skill` - Invokes a reusable skill (Markdown instruction module) +- `schedule_wakeup` - Schedules a future turn for the current session +- `cancel_wakeup` - Lists or cancels the current session's scheduled wakeups - `agent_manager` - Starts Agent Manager local or worktree sessions in VS Code - `board_post` / `board_read` - Exchange messages on the experimental Kilo Swarm board @@ -147,6 +149,21 @@ For example, a primary agent can start independent background research with a ca Background subagents are available when the server exposes the background capability. Do not poll for progress or duplicate work in the same files. If Kilo returns a `task_id` after a failed or interrupted child, use it to resume that child when the current session and permissions allow it. A child can create more task children only when its configured depth and `task` permission allow it. +### Scheduled wakeups + +In the CLI and VS Code extension, the agent can defer its own continuation with `schedule_wakeup` instead of holding a turn open: + +- The agent gives a prompt to resume with and exactly one of `delay` (for example `30s`, `5m`, `2h`, `1d`; a bare number is seconds) or `when` (an absolute ISO-8601 date-time). +- A delay under 10 seconds is raised to 10 seconds, a time more than 7 days away is pulled back to 7 days, and a time at or before now is rejected. +- One session holds at most 10 pending wakeups. +- When the wakeup fires, the session resumes with the scheduled prompt marked `[scheduled wakeup]`, and a note that no user is present. +- Wakeups are stored and re-armed when the project is opened again, so they survive a restart. An overdue wakeup fires when the project opens. +- A wakeup that fires while the session is paused is logged as unresumable instead of resuming. + +`cancel_wakeup` lists the session's pending wakeups with their id, due time, and reason (or the scheduled prompt when no reason was given) and cancels one by id. Cancelling an id that already fired or was cancelled reports it without failing. + +This is for waiting on something outside a blocking command, such as a build, deploy, or CI window, or a later check-in on a slowly changing task. For short waits, use a blocking shell command with a raised `timeout` instead. + ### Kilo Swarm board tools Kilo Swarm is an optional shared board for one main session and its `task` descendants, including nested descendants. Enable it in **Settings > Experimental** or set `experimental.shared_agent_board` to `true` in `kilo.jsonc`. The board is not shared by unrelated sessions, even when they use the same repository or worktree. 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 18d4bc48255c..6b76df18f5b8 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 @@ -109,7 +109,7 @@ Type `@` in the TUI to get file autocomplete suggestions, or mention file paths - URLs → Opens in browser - Messages → Expand/collapse details - Code blocks → Copy button appears -- Mermaid code blocks → Fenced `mermaid` blocks render as diagrams after the message finishes streaming. The source remains copyable, and invalid Mermaid syntax stays visible in a contained error state. +- Mermaid code blocks → In VS Code and JetBrains, fenced `mermaid` blocks render as diagrams after the message finishes streaming. The source remains copyable, and invalid Mermaid syntax stays visible in a contained error state. The terminal cannot render Mermaid, so Ask mode in the CLI uses plain-text or ASCII diagrams instead; explicitly requesting Mermaid source still returns it. - Charts → In VS Code, asking for a chart, graph, or plot renders an inline chart in the conversation. Supported types include bar, line, scatter, pie, doughnut, radar, bubble, and polar area. Diagrams and flowcharts still render as Mermaid. **Status signals:** @@ -140,6 +140,8 @@ When Kilo Code needs more information to complete a task, it asks a follow-up qu 2. **Options Displayed** - Selectable options are presented that you can choose from 3. **Selection** - Pick an option or type a custom response +For single-select questions, the agent can mark one option as the default answer. That option starts selected and focused, so pressing `Enter` confirms it. You can still choose another option, and a default never submits on its own or takes focus from the message composer. + **Benefits:** - **Speed** - Quickly respond without typing full answers 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 2a88ed2de4cf..ab91ea2214d8 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 @@ -26,9 +26,12 @@ Type `@` in the chat input to get autocomplete suggestions. You can mention: | **Terminal** | In the sidebar, include the active VS Code terminal output. In Agent Manager, include the focused terminal for the selected session or worktree, including embedded **Run** and **Setup** tabs. | `@terminal` | | **Git Changes** | Attach uncommitted working-tree diffs and new files | `@git-changes` | | **Past chats** | Add a previous session's chat history as context | `@` → **Past chats** → pick a session | +| **Model** | Reference a model for a subagent or Agent Manager session | `@anthropic/claude-sonnet-4.6` | Selecting a suggestion inserts the mention and highlights it in the input. File contents, terminal output, and git changes are attached as context when you send the message. +The query can contain spaces, so files and folders whose names include spaces stay reachable — type `@my report.txt`. Files, past chats, and entries such as **Terminal**, **Git changes**, and **Browse files...** are ranked together by how well they match the query, so the best match appears first whatever kind of item it is. Past chats are also matched by title directly in the list. + Terminal context is limited to 500 lines or 50,000 characters. Longer output is truncated. If no terminal content is available, Kilo reports that terminal content is unavailable instead of attaching an empty file. ### Referencing Past Chats @@ -37,6 +40,12 @@ Choosing **Past chats** from the `@` menu opens a searchable picker of sessions Very long chat histories are truncated, keeping the beginning and end, so a single mention cannot fill the context window. +### Referencing a Model + +Choosing **Model** from the `@` menu opens the model picker. Picking a model inserts an `@provider/model` token into the prompt, for example `@anthropic/claude-sonnet-4.6`. + +Selecting a model this way does not change the model used by the current session. The token is plain inline text so the agent can read the exact model key — useful for telling a `task` subagent or an Agent Manager session which model to use. The token moves and deletes as a single unit, and it is never sent as a file or rendered as a clickable file link. + ### Drag and Drop You can also add file mentions by dragging and dropping: @@ -46,8 +55,14 @@ You can also add file mentions by dragging and dropping: | **Explorer / Editor tabs** | Drag a file or folder from VS Code's Explorer or an editor tab into the chat input | Inserts an `@/relative/path` mention | | **Multiple files** | Drag several files at once | Inserts space-separated `@` mentions | | **Agent Manager diff headers** | Drag a file header from the Agent Manager's diff panel into chat | Inserts an `@file` mention | +| **Session tabs** | Drag a session tab from the chat tab strip into the chat input | Inserts a mention for that session | +| **Worktree cards** | Drag a worktree card from the Agent Manager sidebar into the chat input | Inserts an `@` worktree mention that carries the worktree's directory, branch, and session IDs | +| **Terminal tabs** | Drag a terminal tab into the chat input | Inserts an `@terminal` mention for that terminal | +| **Document tabs** | Drag an open tab from the Agent Manager Documents inspector into the chat input | Inserts an `@file` mention for that document | | **Images** | Hold **Shift** while dragging an image file from your OS file manager into the chat input | Attaches the image | +While a mention drag is over the prompt, the prompt highlights to show it is the drop target. The inserted mention ends with a trailing space so you can keep typing. + {% callout type="info" %} VS Code requires holding **Shift** when dragging files from outside the editor (e.g. Finder or Windows Explorer) into a webview. This applies to image drops — file drops from within VS Code (Explorer, editor tabs) work without Shift. {% /callout %} diff --git a/packages/kilo-docs/pages/code-with-ai/agents/goals.md b/packages/kilo-docs/pages/code-with-ai/agents/goals.md index 0a256d5fa1d9..ad3c1bbc6c76 100644 --- a/packages/kilo-docs/pages/code-with-ai/agents/goals.md +++ b/packages/kilo-docs/pages/code-with-ai/agents/goals.md @@ -33,6 +33,13 @@ To treat a control word as the objective, separate it with `--`: The `--` delimiter sets the literal objective `pause` instead of pausing the current goal. The VS Code goal composer adds this delimiter for you. +{% /tab %} +{% tab label="Mobile" %} + +Select `/goal` in the composer with no objective to start goal-compose mode, then enter the objective. The next message you send forwards `/goal `. To set a goal without compose mode, type `/goal ` and send it directly. + +Goals require a connected CLI that advertises the `goal` command. A session whose CLI does not support it shows an upgrade message instead of sending. + {% /tab %} {% /tabs %} @@ -50,6 +57,8 @@ An objective can be up to 10,000 characters. The CLI and VS Code also show a goal control next to the composer. Select it to pause, resume, or clear the goal. When a goal is complete, the control label is **Restart goal** instead of **Resume**. +In the mobile app, a session with a goal shows a fixed goal section under the session header. The section shows the status and objective, plus the CLI's reason when it provides one; tap it to **Edit** the objective, **Pause** or **Resume**, or **Remove** the goal. Editing sends `/goal `, and the other actions send `/goal pause`, `/goal resume`, and `/goal clear`. + ## Goal statuses | Status | Meaning | 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 d511415d6948..c950f929206d 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 @@ -58,6 +58,7 @@ While the specifics change constantly, some principles stay consistent: - Set per-agent defaults and a global default in the **Settings** panel (Models tab), or directly in the `kilo.jsonc` config file. - **Model precedence:** Session override → Last picked per agent → Per-agent config → Global config → [Auto Free](/docs/code-with-ai/agents/auto-model#tiers) (note: Auto Free may route to providers that log prompts — see the Auto Model page for details). - The model selector remembers the last model you picked for each agent, so switching agents restores your previous choice. A manual pick always beats config settings. +- When you're signed in to an organization, Kilo checks the selected model against the models your organization makes available. If that model is unavailable, it uses the organization's default model for the session instead of falling back to an unrelated public model. Automatic fallbacks don't overwrite your saved preference, so switching back to your personal account restores your choice. {% /tab %} {% tab label="CLI" %} diff --git a/packages/kilo-docs/pages/code-with-ai/agents/using-agents.md b/packages/kilo-docs/pages/code-with-ai/agents/using-agents.md index 7f6ddf8cfc77..ffc098bcfc52 100644 --- a/packages/kilo-docs/pages/code-with-ai/agents/using-agents.md +++ b/packages/kilo-docs/pages/code-with-ai/agents/using-agents.md @@ -68,7 +68,7 @@ There are several ways to switch agents: | **Description** | An experienced technical leader and planner who helps design systems and create implementation plans | | **Tool Access** | Read-only tools plus restricted file editing (plan files in `.kilo/plans/` only) | | **Ideal For** | System design, high-level planning, and architecture discussions | -| **Special Features** | Similar to the legacy extension's "Architect" mode, with a planning-focused approach | +| **Special Features** | Similar to the legacy extension's "Architect" mode, with a planning-focused approach. In VS Code, the saved plan opens in the editor when it is ready for review. | ### debug 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 a12731d20881..0b636ae008f6 100644 --- a/packages/kilo-docs/pages/code-with-ai/platforms/cli.md +++ b/packages/kilo-docs/pages/code-with-ai/platforms/cli.md @@ -131,6 +131,7 @@ The `kilo console` command and its browser interface are deprecated and will be | Command | Aliases | Description | |---|---|---| | `/status` | - | View status | +| `/about` | - | Show version, channel, runtime, config path, project root, connected providers, and default model; press `c` to copy a diagnostic block | | `/themes` | - | Switch theme | | `/help` | - | Show help | | `/reload` | - | Reload every instance of the project from disk (config, skills, agents, and commands) | @@ -246,7 +247,9 @@ There is no slash command or command-palette toggle for notifications or sounds. The CLI's interactive mode supports slash commands for common operations. The main commands are documented above in the [Interactive Slash Commands](#interactive-slash-commands) section. -Use `/diff` to review working-tree changes. From the diff viewer, switch the source to the current branch compared with the main branch or to changes from the last assistant turn. Use `/move` to move the current session to another project directory. +Use `/about` to open the About dialog, either from the command palette (under **Kilo**) or as a slash command. It shows the CLI version and channel, runtime and platform, configuration and project paths, connected providers, and the default model, with links to the docs, GitHub, issues, and Discord. Press `c` to copy a diagnostic block for bug reports. + +Use `/diff` to review working-tree changes. From the diff viewer, switch the source to the current branch compared with the main branch, to changes from the last assistant turn, or to changes from the last commit (`HEAD` vs `HEAD~1`). Use `/move` to move the current session to another project directory. The `diff_open` and `session_move` TUI keybindings run the same actions and are unbound by default. Set them under `keybinds` in `tui.jsonc`: @@ -565,10 +568,26 @@ Selecting an "Always run" option will: Kilo only saves the pattern you select. Approving a specific command does not approve redirected variants or broader command patterns unless that broader option is shown and selected. +### Rejecting with Feedback + +Select **Reject**, or press `Esc`, to open a rejection message field instead of rejecting immediately. Type what the agent should do differently, then press `Enter` to reject with that feedback. Press `Esc` to cancel and return to the approval prompt. + +The feedback is optional. Leave the field empty and press `Enter` to reject without feedback. With feedback, the agent can revise its proposal and ask for approval again; an empty rejection is a plain denial. + ### Pasting Large Text Pasting a large block of text (five or more lines, or over 800 characters) into the prompt collapses it into a placeholder such as `[Pasted ~6 lines]` to keep the prompt readable. To view or edit the pasted text, paste the same text again — the matching placeholder expands in place. +### Answering Questions + +When `kilo run` asks a question with selectable options, the footer shows the available keys. For multiple-choice questions: + +- `Space` toggles the focused option. +- `Enter` advances to the next question, or to the review and confirm step on the last question. +- `1`–`9` toggle an option directly, and `↑`/`↓` move the focus. `Tab` and `Shift+Tab` switch between questions. + +For single-select questions, `Enter` submits the answer. When the agent defines a default answer, that option starts selected and `Enter` confirms it. `Esc` dismisses the question. + ## Autonomous Mode (Non-Interactive) Autonomous mode allows Kilo Code to run in automated environments like CI/CD pipelines without requiring user interaction. @@ -603,7 +622,9 @@ This instructs the AI to proceed without user input. - `0`: Success (task completed) - `124`: Timeout (task exceeded time limit) -- `1`: Error (initialization or execution failure) +- `1`: Error (initialization, execution, or request failure) + +A run that completes without producing any assistant output also exits `1`, so an empty run is not mistaken for a successful one. Kilo prints `run ended without an assistant message; the model returned no output` to stderr, or emits it as a final `error` record when you use `--format json`. A run that produces assistant output still exits `0`. If the prompt request itself fails, that error is reported instead and the empty-output diagnostic is not added. Without `--auto`, a non-interactive run cannot prompt for approval and auto-rejects any permission request it receives. If a run auto-rejected at least one request, it exits `1` with a stderr diagnostic naming the cause, since the task likely did not complete. Pass `--auto` for autonomous use. diff --git a/packages/kilo-docs/pages/customize/context/context-condensing.md b/packages/kilo-docs/pages/customize/context/context-condensing.md index 9339ed5509f7..4eb3b772b7a2 100644 --- a/packages/kilo-docs/pages/customize/context/context-condensing.md +++ b/packages/kilo-docs/pages/customize/context/context-condensing.md @@ -95,7 +95,7 @@ Compaction is configured in your `kilo.jsonc` file: ### Use a different model for compaction -Summarization can use a cheaper or larger-context model than your main agent. Configure a dedicated compaction agent: +Summarization can use a cheaper or larger-context model than your main agent. In the VS Code extension, select the **Compaction model** under **Settings → Models**, next to the other per-purpose model selectors. To configure it in `kilo.jsonc`, set a dedicated compaction agent: ```jsonc { diff --git a/packages/kilo-docs/pages/customize/custom-instructions.md b/packages/kilo-docs/pages/customize/custom-instructions.md index 064f9be342e3..734b7843a6f1 100644 --- a/packages/kilo-docs/pages/customize/custom-instructions.md +++ b/packages/kilo-docs/pages/customize/custom-instructions.md @@ -46,6 +46,10 @@ For instructions that apply across all your projects, place an `AGENTS.md` file Project-level instructions are loaded before global instructions and apply to every session. +{% callout type="note" %} +After the experimental [Claude Code Migration](/docs/getting-started/settings#claude-code-migration) runs, Kilo stops loading global `~/.claude/CLAUDE.md` instructions. Project-level `CLAUDE.md` files keep working. +{% /callout %} + ### 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. @@ -123,6 +127,10 @@ For instructions that apply across all your projects, place an `AGENTS.md` file Project-level instructions are loaded before global instructions and apply to every session. +{% callout type="note" %} +After the experimental [Claude Code Migration](/docs/getting-started/settings#claude-code-migration) runs, Kilo stops loading global `~/.claude/CLAUDE.md` instructions. Project-level `CLAUDE.md` files keep working. +{% /callout %} + ### 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. diff --git a/packages/kilo-docs/pages/customize/custom-subagents.md b/packages/kilo-docs/pages/customize/custom-subagents.md index 978e094c1aa9..8bd1c19656c8 100644 --- a/packages/kilo-docs/pages/customize/custom-subagents.md +++ b/packages/kilo-docs/pages/customize/custom-subagents.md @@ -236,6 +236,10 @@ Once configured, subagents can be used in two ways: Primary agents with full tool access can automatically invoke subagents via the Task tool when the subagent's `description` matches the task at hand. Write clear, descriptive `description` values to help primary agents select the right subagent. The deprecated Orchestrator agent is not required. +### Per-task model selection + +By default, a `task` subagent uses the model configured on the subagent or inherited from the parent agent. When [Task Subagent Model Selection](/docs/getting-started/settings#task-subagent-model-selection) is enabled, the orchestrating agent can choose a model, provider, and reasoning `variant` for an individual task instead. The agent can search the available models and supported variants with the `agent_manager_models` tool, and invalid selections fail before the child session starts. This experimental setting is off by default. + ### Manual Invocation via @ Mentions You can manually invoke any subagent by typing `@agent-name` in your message: diff --git a/packages/kilo-docs/pages/getting-started/byok.md b/packages/kilo-docs/pages/getting-started/byok.md index d3915372cba9..80d8bdb2eae1 100644 --- a/packages/kilo-docs/pages/getting-started/byok.md +++ b/packages/kilo-docs/pages/getting-started/byok.md @@ -24,6 +24,7 @@ Use your provider API key to route matching models through your account: - Anthropic - AWS Bedrock +- Azure OpenAI - DeepSeek - Fireworks - Google AI Studio @@ -67,7 +68,18 @@ These providers offer coding-focused subscriptions or dedicated endpoints. Bring ### AWS Bedrock configuration -AWS Bedrock requires credentials in a different format than other providers. Instead of a single API key, you must provide your AWS credentials as a JSON object: +AWS Bedrock requires credentials as a JSON object rather than a single API key. Use exactly one of these two formats. + +**Bedrock API key** — generate a key in the AWS Bedrock console, use a region where the key and model are available, and replace the key before it expires: + +```json +{ + "apiKey": "...", + "region": "us-east-1" +} +``` + +**IAM credentials** — use an IAM user or role: ```json { @@ -79,15 +91,36 @@ AWS Bedrock requires credentials in a different format than other providers. Ins | Field | Description | |---|---| -| `accessKeyId` | Your AWS access key ID | -| `secretAccessKey` | Your AWS secret access key | +| `apiKey` | Your Bedrock API key (API-key format only) | +| `accessKeyId` | Your AWS access key ID (IAM format only) | +| `secretAccessKey` | Your AWS secret access key (IAM format only) | | `region` | The AWS region where Bedrock is enabled (e.g., `us-east-1`, `eu-west-1`) | -Your IAM user or role must have the following permissions: +Don't mix fields from both formats in the same object. + +An IAM user or role must have the following permissions: - `bedrock:InvokeModel` - `bedrock:InvokeModelWithResponseStream` +### Azure OpenAI configuration + +Azure OpenAI requires your API key and resource name rather than a single key. Provide both as a JSON object: + +```json +{ + "apiKey": "...", + "resourceName": "my-azure-resource" +} +``` + +| Field | Description | +|---|---| +| `apiKey` | Your Azure OpenAI API key. | +| `resourceName` | The name of your Azure OpenAI resource, which is the subdomain of your endpoint URL. | + +If your Azure deployment names differ from the model IDs you select in Kilo, add optional deployment mappings so each model resolves to its deployment. + ## How Bring Your Own Key works - When you use the **Kilo Gateway** provider, Kilo checks if there's a BYOK key for the selected model's provider. diff --git a/packages/kilo-docs/pages/getting-started/cost-controls-and-usage-safeguards.md b/packages/kilo-docs/pages/getting-started/cost-controls-and-usage-safeguards.md index ec281b1cae66..836893ea2ce0 100644 --- a/packages/kilo-docs/pages/getting-started/cost-controls-and-usage-safeguards.md +++ b/packages/kilo-docs/pages/getting-started/cost-controls-and-usage-safeguards.md @@ -108,7 +108,7 @@ Auto-compaction is **enabled by default** — Kilo automatically compacts when a **Where to configure:** Toggle auto-compaction in **Settings → Context** (VS Code) or set `compaction.auto` in `kilo.jsonc`. Configure the trigger threshold with `compaction.threshold_percent` (e.g. `80` to compact at 80% of the model's context window). -You can also configure a cheaper model specifically for compaction, so summarization does not consume frontier model tokens: +You can also configure a cheaper model specifically for compaction, so summarization does not consume frontier model tokens. In the VS Code extension, pick the **Compaction model** under **Settings → Models**. In `kilo.jsonc`: ```jsonc { diff --git a/packages/kilo-docs/pages/getting-started/settings/auto-approving-actions.md b/packages/kilo-docs/pages/getting-started/settings/auto-approving-actions.md index 070fc59df500..478f3f51551d 100644 --- a/packages/kilo-docs/pages/getting-started/settings/auto-approving-actions.md +++ b/packages/kilo-docs/pages/getting-started/settings/auto-approving-actions.md @@ -63,8 +63,10 @@ When a tool is set to `"ask"`, Kilo pauses and displays a permission prompt with | Option | Behavior | |---|---| -| **Run** | Allow this specific invocation | -| **Deny** | Block this specific invocation | +| **Allow once** | Allow this specific invocation | +| **Deny** | Reject the invocation. Kilo opens an optional feedback field, then **Reject** confirms. | + +Selecting **Deny** opens an optional feedback field. Enter what the agent should do differently, then press `Enter` to reject with that feedback, or `Esc` to cancel and return to the prompt. Leave the field empty and press `Enter` to reject without feedback. With feedback, the agent can revise its proposal and request approval again before anything is applied; an empty rejection is a plain denial. Rejecting never grants a permanent approval. Use the shield button in the prompt controls to toggle runtime auto-approve for permission prompts without opening Settings. When enabled, the shield is highlighted and pending permission prompts are approved automatically. The runtime state stays synced across the sidebar, open Kilo tabs, and Agent Manager session views. diff --git a/packages/kilo-docs/pages/getting-started/settings/index.md b/packages/kilo-docs/pages/getting-started/settings/index.md index daecf52102fe..244ab2780819 100644 --- a/packages/kilo-docs/pages/getting-started/settings/index.md +++ b/packages/kilo-docs/pages/getting-started/settings/index.md @@ -187,6 +187,9 @@ Available experimental settings include: - **Paste summary** - summarize large clipboard pastes before including them - **Batch tool** - allow the agent to batch multiple tool calls in one step - **Kilo Swarm** - let a main session and its task subagents share a board (off by default) +- **Enable Browser Automation** - enable the Agent Manager browser panel and the `browser_open` tool (off by default) +- **Task Subagent Model Selection** - let the agent choose a model, provider, and reasoning variant for each `task` subagent (off by default) +- **Claude Code Migration** - one-time import of supported global Claude Code instructions, skills, and MCP definitions (off by default) - **OpenTelemetry** - enable Kilo telemetry and optional OTLP export when configured Advanced options not exposed in the UI can be configured via the `experimental` key in `kilo.jsonc`: @@ -218,7 +221,7 @@ Telemetry is enabled by default. Set `experimental.openTelemetry` to `false` in Kilo Swarm lets a main session and its task descendants, including nested subagents, exchange messages on a shared board. It is experimental and uses the existing Task tool, not a separate agent runtime. The board is not shared with unrelated sessions, even in the same repository or worktree. -Enable **Kilo Swarm** in the VS Code **Experimental** settings, or set `experimental.shared_agent_board` to `true` in `kilo.jsonc`. It is off by default. This display name does not change the configuration key, tool names, stored board or session IDs, database migrations, history, or permissions. +Enable **Kilo Swarm** in the VS Code **Experimental** settings, or set `experimental.shared_agent_board` to `true` in `kilo.jsonc`. You can also enable it with the `KILO_EXPERIMENTAL_SHARED_AGENT_BOARD` environment variable, or with the umbrella `KILO_EXPERIMENTAL=true`, without editing config. The environment flag is an additional enable path, so an explicit config `false` does not disable the board when the flag is set. It is off by default. This display name does not change the configuration key, tool names, stored board or session IDs, database migrations, history, or permissions. Use it when agents can benefit from discoveries during work: @@ -232,3 +235,25 @@ Straightforward tasks can stay solo. Enabling the board does not mean agents are All participants can read the board history, including messages addressed to others. Recipient selection is not a privacy boundary. Peer messages do not grant user approval or change permissions; `HOLD` and `VETO` are advisory, not controls that pause or cancel work. When a main session has board messages, open the **Board** icon in its task header to read them, refresh them, or reset the board. Only the owning top-level session can view or reset its board; child sessions and cloud sessions cannot. Reset clears visible messages only and does not stop agents or clear conversations. See [Kilo Swarm communication](/docs/automate/agent-manager#kilo-swarm-communication) for the board dialog, ownership rules, and recipient-state warnings. + +### Task Subagent Model Selection + +Task subagents normally use the model and reasoning variant configured for the subagent or inherited from the parent. With **Task Subagent Model Selection** enabled, the orchestrating agent can choose a model, provider, and reasoning variant for an individual `task` subagent instead. + +Enable it in the VS Code **Experimental** settings, or set `experimental.task_model_selection` to `true` in `kilo.jsonc`. It is off by default. When the setting is on, the agent can search available models with the `agent_manager_models` tool and pass `model`, `provider`, and `variant` when it starts a subagent. Explicit selections are validated before the child session starts, so an invalid model, provider, or variant fails instead of silently falling back. A resumed subagent keeps its last model and reasoning variant unless it is overridden. See [Custom Subagents](/docs/customize/custom-subagents#per-task-model-selection). + +### Claude Code Migration + +**Claude Code Migration** is a one-time, opt-in import of supported global Claude Code configuration into Kilo. It runs on the next backend start after you enable it. A receipt and a global config lock ensure the import is attempted only once, with no automatic retry. + +Enable it in the VS Code **Experimental** settings, or set the `KILO_EXPERIMENTAL_CLAUDE_MIGRATION` environment variable. It is off by default. + +The migration imports only: + +- Global instructions from `~/.claude/CLAUDE.md`, written to Kilo's global `AGENTS.md` +- Standalone skills from `~/.claude/skills/`, imported one directory per skill with a `SKILL.md` +- Top-level MCP server definitions from `~/.claude.json`, imported disabled + +Your original Claude files are never changed or deleted. Existing Kilo instructions, skills, commands, and MCP names take precedence: anything that would conflict with existing content is skipped, along with unsupported syntax, symlinks, skill bundles with extra files, unsafe destination paths, and custom config routing. Imported MCP servers stay disabled until you enable them. + +After the attempt, Kilo stops using global `~/.claude` instructions and skills as a fallback, while project-level Claude compatibility (such as a `CLAUDE.md` in a repository) still works. A notification reports what was imported, skipped, or failed and points to the migration receipt for the full list. diff --git a/packages/kilo-docs/pages/getting-started/settings/notifications.md b/packages/kilo-docs/pages/getting-started/settings/notifications.md index 51ee463464bc..cd3d50d6a211 100644 --- a/packages/kilo-docs/pages/getting-started/settings/notifications.md +++ b/packages/kilo-docs/pages/getting-started/settings/notifications.md @@ -55,7 +55,7 @@ Each enabled channel decides independently. The OS notification follows window f | Not focused | Visible | Yes | No | | Not focused | Not visible | Yes | Yes | -Both channels can fire for the same event. The VS Code notification includes the workspace and session names and a **Show** button. **Show** focuses the Kilo sidebar and opens the session at its latest message. +Both channels can fire for the same event. The VS Code notification includes the workspace and session names and a **Show** button. **Show** opens the session at its latest message. When Agent Manager owns the session, it opens in Agent Manager and selects the right project, worktree or Local tab, and session. Otherwise, **Show** focuses the Kilo sidebar. ### Native notification support