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

Each worktree item displays a PR status badge when its branch has an associated pull request. The badge shows the PR number (e.g. #142) and is color-coded to reflect the current state at a glance. Click the badge to open the PR in your browser.

How PRs are detected

The extension uses gh to automatically discover PRs for each worktree branch. Three strategies are tried in order:

1. Branch tracking ref — gh pr view resolves via the branch's tracking ref (works for fork PRs checked out with gh pr checkout)
2. Branch name — gh pr view <branch> matches same-repo branches pushed to origin
3. HEAD commit SHA — gh pr list --search "<sha>" as a last resort, matching PRs whose head ref points to the exact same commit

You can also import a PR directly from the advanced new worktree dialog: open the New Worktree dropdown and select Advanced, or press Cmd+Shift+N (macOS) / Ctrl+Shift+N (Windows/Linux), switch to the Import tab, then paste the GitHub PR URL. The branch is checked out and the badge appears automatically.

Badge colors

The badge color reflects the most important signal, evaluated in priority order:

When checks are pending on an open PR, the badge pulses to indicate activity.

Badge icon

The badge shows a checkmark icon when the PR review status is "Approved", and a branch icon in all other cases.

Hover card details

Hovering over a worktree item shows a card with additional PR details:

• PR number with a link icon to open it in the browser
• State — Open, Draft, Merged, or Closed
• Review — Approved, Changes Requested, or Pending (when a review exists)
• Checks — how many checks passed out of the total (e.g. 8/10 passed)

Automatic updates

PR badges update automatically in the background. The active worktree refreshes frequently, while other worktrees sync periodically to keep badges current. Polling pauses when the Agent Manager panel is hidden.

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 local to copy the worktree's changes onto your local checkout of the base branch
• Conflicts are surfaced with a resolution dialog
• Supports unified and split diff views
• Drag file headers into chat — drag a file header from the diff panel into the chat input to insert an @file mention, giving the agent context about specific changed files

See Agent Manager Workflows for the full integration story, including when to apply locally vs. merge directly vs. open a pull request.

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.

Run Script

The run button lets you start your project (dev server, build, tests, etc.) directly from the Agent Manager toolbar without switching to a terminal. It executes a shell script you define once, and runs it in the context of whichever worktree is currently selected.

Setting up a run script

Create a script file in .kilo/ using the appropriate filename for your platform:

For example, on macOS / Linux create .kilo/run-script:

#!/bin/sh
npm run dev

The next time you click the run button (or press Cmd+E / Ctrl+E), the script runs in the selected worktree's directory.

Environment variables

Two extra variables are injected into the script's environment:

Using the run button

• Run: Click the play button in the toolbar or press Cmd+E (macOS) / Ctrl+E (Windows/Linux). Output appears in a dedicated VS Code task panel.
• Stop: Click the stop button (same position) or press Cmd+E again while running.
• Configure: Click the dropdown arrow next to the run button and select "Configure run script" to open the script in your editor.

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.