Quickstart

This guide walks you through your first session in Kilo Desktop. If you haven't installed the app yet, see Installation.

Complete onboarding

On first launch, a short setup wizard walks you through the setup steps.

1. Review the terms of service

Review and accept Kilo's terms of service.

2. Connect to Kilo

Sign in to your Kilo account to use frontier models, credits, and organization settings through the Kilo Gateway. You can skip this step and connect later from Settings.

3. Choose an autonomy level

Choose whether you want Kilo to operate with high autonomy or review its work first, pausing to show its plan and ask for your approval before it edits files or runs commands. High autonomy is the default behavior of the Kilo Code agent.

4. Create a workspace

A workspace scopes a chat to one or more folders on your machine. Add the folder(s) you want the agent to work in; the agent's file access, terminal, and git operations all run inside the workspace. You can add more workspaces anytime.

Navigate the home screen

When Kilo Desktop opens, you land on a new chat in the workspace you created during setup.

Sidebar

The sidebar on the left manages your chats and workspaces.

• New chat starts a fresh conversation.
• Search finds your past chats.
• Workspaces lists the folders you've added. Select the dropdown to switch to a different workspace or create a new one. Use the filter to organize the list — group by Status, Workspace, or Updated, order by Updated or Title, choose what each row shows, and filter by status (Needs attention, Working, Idle, or Archived).

Settings

Access the app settings by clicking the settings icon at the bottom of the sidebar. See General settings and AI settings for details.

Chat with the agent

The rest of the window is where you chat with the agent. Type a message, use @ to mention workspace files, or / to run a command.

Input controls

The controls around the input let you:

• Add an attachment with the + button.
• Choose an agent to set how it approaches your request. Pick one of the default agents: Code, Plan, Ask, Debug, or Architect. See Using agents for what each one does.
• Select autonomy level for the agent. With Manually approve, Kilo asks before each file edit or command; with Automatically approve, it proceeds on its own without requesting permission.
• Pick a model for the chat. The available models depend on how you're signed in and which providers you've connected. The list can include Kilo Gateway models, provider models you've added, or a local model you've added.
• Select a workspace to scope the chat to a workspace, add a New workspace, or choose No workspace to chat without one.
• Set where changes go with the git controls beside the workspace — work in your Local repository (switching or creating branches as needed), or run the session in a new worktree, an isolated copy created from a base branch. See Git integration.

Send your first message

Enter your message and send it to start the conversation. See What you can ask for prompts to get you started.

Work in tab groups

Tab groups let you work in the same workspace alongside the chat. Each tab group holds one or more tabs. Send a message to access the tab groups view.

Open a tab group

Open a new tab group with the + Add tab group button at the top of a chat:

Then, pick a tab to open in it:

• Files — browse and edit files in the workspace.
• Changes — review uncommitted git changes.
• Notebook — analyze data in an interactive Python notebook.
• Browser — open web pages without leaving the app.
• Terminal — run commands in an interactive shell.

Arrange tabs and tab groups

Use Add tab beside a tab group's tabs to add another tab to that group. Drag a tab to move it to another tab group. To move a whole tab group, drag it from the empty space to the right of its tabs.

Each tab has its own controls: Expand grows the tab to fill the workspace (select it again to collapse), Pop out moves the tab into its own window, and the close button removes it.

By default, each tab group you open is added next to the others, and the tab groups get narrower to fit your screen as you open more. Turn on Carousel layout to keep the tab groups wider, then hold Shift and scroll with your mouse to pan across them.

Show chat jumps you back to your conversation tab.

Save and reuse layouts

When you find an arrangement of tab groups and tabs you like, save it as a layout and reuse it in other chats. A layout stores how your tab groups and tabs are arranged, not their contents — your chat history and the files, notebooks, or pages you had open aren't included.

Use the Layouts button at the top right of a chat to:

• Save current layout — name the arrangement and, optionally, Use as default for new chats. The dialog lists any open tabs it can't recreate in a new chat (such as a specific file, notebook, or browser page).
• Apply a layout — select a saved layout from the menu to rearrange the current chat to match.
• Manage layouts — set or clear the default, update a layout from the current arrangement, rename it, or delete it.

The default layout applies to new chats only; existing chats stay as they are.