Agent Manager

The Agent Manager is a full-panel editor tab built directly into the extension. All sessions share the single kilo serve backend process. It supports:

• Multiple parallel sessions, each in its own git worktree
• A diff/review panel showing changes vs. the parent branch
• Dedicated VS Code integrated terminals per session
• Setup scripts and .env auto-copy on worktree creation
• Session import from existing branches, external worktrees, or GitHub PR URLs
• "Continue in Worktree" to promote a sidebar session to the Agent Manager

Opening the Agent Manager

• Keyboard shortcut: Cmd+Shift+M (macOS) / Ctrl+Shift+M (Windows/Linux)
• Command Palette: "Kilo Code: Open Agent Manager"
• Click the Agent Manager icon in the sidebar toolbar

The panel opens as an editor tab and stays active across focus changes.

Working with Worktrees

Each Agent Manager session runs in an isolated git worktree on a separate branch, keeping your main branch clean.

PR Status Badges

Worktree items in the sidebar display a PR status badge when the branch has an associated pull request:

• Open — badge indicating the PR is open (its color can also reflect review and check status)
• Merged — purple badge indicating the PR has been merged
• Closed — red badge indicating the PR was closed without merging
• Draft — gray badge indicating the PR is in draft state

The badge appears on the right side of each worktree item and updates automatically via polling. If the worktree's branch doesn't have a PR yet, no badge is shown.

Creating a New Worktree Session

1. Click New Worktree or press Cmd+N (macOS) / Ctrl+N (Windows/Linux) to create a new worktree
2. Enter a branch name (or let Kilo generate one)
3. Type your first message to start the agent

A new git worktree is created from your current branch. The agent works in isolation — your main branch is unaffected.

Multi-Version Mode

You can run up to 4 parallel implementations of the same prompt across separate worktrees:

1. Click the multi-version button and enter a prompt
2. Optionally assign different models to each version
3. Kilo creates one worktree + session per version and runs them in parallel

Importing Existing Work

• From a branch: Import an existing git branch as a worktree
• From a GitHub PR URL: Paste a PR URL to import it as a worktree
• From an external worktree: Import a worktree that already exists on disk
• Continue in Worktree: From the sidebar chat, promote the current session to a new Agent Manager worktree

Sections

Sections let you group worktrees into collapsible, color-coded folders in the sidebar. Use them to organize your workflow however you like — by status ("Review Pending", "In Progress"), by project area ("Frontend", "Backend"), priority, or any other scheme that fits.

Creating a Section

• Right-click any worktree and select New Section from the context menu
• A new section is created with a random color and enters rename mode immediately — type a name and press Enter

Assigning Worktrees to Sections

Via context menu: Right-click a worktree, hover Move to Section, and pick a section from the list. Select Ungrouped to remove it from its current section.

Via drag and drop: Drag a worktree and drop it onto a section header to move it there.

Multi-version worktrees (created via Multi-Version Mode) are moved together — assigning one version to a section moves all versions in the group.

Renaming

Right-click the section header and select Rename Section. An inline text field appears — type the new name and press Enter to confirm or Escape to cancel.

Colors

Right-click the section header and select Set Color to open the color picker. Eight colors are available (Red, Orange, Yellow, Green, Cyan, Blue, Purple, Magenta) plus a Default option that uses the standard panel border color. The selected color appears as a left border stripe on the section.

Reordering

Right-click the section header and use Move Up / Move Down to reposition it in the sidebar. Sections and ungrouped worktrees share the same ordering space.

Collapsing

Click the section header to toggle it open or closed. Collapsed sections hide their worktrees and show only the section name and a member count badge. Collapse state is persisted across reloads.

Deleting a Section

Right-click the section header and select Delete Section. The section is removed but its worktrees are preserved — they become ungrouped.

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
• Cancel: Sends a cooperative stop signal to the agent
• Stop: Force-terminates the session and marks it as stopped

Diff / Review Panel

Press Cmd+D (macOS) / Ctrl+D (Windows/Linux) to toggle the diff panel. It shows a live-updating diff between the worktree and its parent branch.

• Select files and click Apply to Main Branch to merge changes
• Conflicts are surfaced with a resolution dialog
• Supports unified and split diff views

Terminals

Each session has a dedicated integrated terminal rooted in the session's worktree directory. Press Cmd+/ (macOS) / Ctrl+/ (Windows/Linux) to focus the terminal for the active session.

Switching Between Terminal and Agent Manager

A common workflow is letting the agent work, then switching to the terminal to run tests or inspect the worktree, then switching back to control the agent:

1. Agent Manager → Terminal: Press Cmd+/ (macOS) / Ctrl+/ (Windows/Linux) to open and focus the terminal for the current session. The terminal runs inside the session's worktree, so commands like npm test or git status operate on the agent's isolated branch.
2. Terminal → Agent Manager: Press Cmd+Shift+M (macOS) / Ctrl+Shift+M (Windows/Linux) to bring focus back to the Agent Manager panel and its prompt input. This works from anywhere in VS Code — the terminal, another editor tab, or the sidebar.

Setup Scripts

Place an executable script at .kilo/setup-script in your project root. It runs automatically whenever a new worktree is created (useful for npm install, env setup, etc.). Root-level .env and .env.* files are also auto-copied from the main repo before the setup script runs.

Session State and Persistence

Agent Manager state is persisted in .kilo/agent-manager.json. Sessions, worktrees, and their order are restored on reload.

Keyboard Shortcuts (Agent Manager Panel)

Troubleshooting

• "Please open a folder…" error — the Agent Manager requires a VS Code workspace folder
• Worktree creation fails — ensure Git is installed and the workspace is a valid git repository. Open the main repository (where .git is a directory), not an existing worktree checkout.