Troubleshooting

If something isn't working in Kilo Desktop, start here.

The app can't reach the agent

Kilo Desktop runs the agent through a local server (a kilo serve process) that starts when the app opens. If chats fail to respond:

Wait a moment after launch — the server needs to report healthy before it accepts requests. If the server stops, Kilo Desktop tries to restart it automatically.
Make sure you're signed in to your Kilo account so hosted models are available.
If you see Kilo isn't running, select Restart. Restarting the app also relaunches the server.

The Changes tab or branch picker isn't available

Git integration needs your system git. If the tools are missing or not working:

Confirm git is installed and on your PATH.
If you see Kilo Desktop needs Git 2.17 or newer, but found Git …, your git is too old. Update Git (run git --version to check), then restart Kilo Desktop.
If the folder isn't a git repository, use Initialize Git in the Changes tab to create one. See Git integration.
For bare or unsafe repositories, the Use and Branch fields on the New Session page are intentionally hidden.
macOS: if git reports that you haven't agreed to the Xcode license, run sudo xcodebuild -license in Terminal, accept it, then try again.
macOS: if you see Git was not found. Install Git, then restart Kilo Desktop., the Xcode Command Line Tools may be missing. Run xcode-select --install in Terminal, then restart Kilo Desktop.

A workspace shows a warning icon

One or more of the workspace's folders can't be found — it was moved, renamed, deleted, or is on a drive that isn't connected. Select the warning icon to open Edit workspace. Use Add folder to choose the folder's new location and remove the old entry with ×. If the folder you removed was Primary, the first remaining folder becomes primary, so select Make primary on the right folder if needed. Then select Save.

Conda environments and notebooks require a Kilo account. When the agent needs one of these while you're signed out, it shows a sign-in card in the chat. If you select Not now, the agent stops using that feature's tools until you sign in or restart the app. Declining one feature doesn't affect the others.

A local model isn't listed in a chat

Local models appear in the model picker only after you're signed in to your Kilo account, the Local Model Server is enabled, and you've imported a model. Check the Local Model Server settings.

The agent can't find a file in a gitignored folder

When the agent searches your workspace for files, it skips anything excluded by your .gitignore. If a notebook or other file lives in an ignored folder, the agent won't find it by searching — but it can still open and edit the file once you point it there:

Open it from the Files tab. The Files tab shows gitignored files and folders, so you can browse to the file and open it directly.
Mention it with @ in the chat and select the file from the list.
Give the agent the path, for example: "Open data/scratch/analysis.ipynb."