Appearance
Troubleshooting
Start with the action that failed and the error it produced. Preserve unfinished work before changing the setup or restarting a process.
The app will not launch
Confirm you installed the build matching your platform and architecture. On macOS, move Korus to Applications; Windows builds are unsigned. Record the app version and any error shown during launch. See Installation for platform-specific steps.
Development builds have additional runtime and SDK requirements described in the repository README.
A provider will not connect
- Open the failing engine's Settings page.
- Check the selected setup location. A successful login in your normal command-line environment does not authenticate a separate Korus setup.
- Complete the authentication flow for that selected location. A detected engine and a connected account are separate states.
- Confirm the engine is enabled. The initial Continue button needs at least one installed, connected, enabled engine.
See the provider guides for the engine's setup and sign-in steps. If Antigravity is not detected, check that agy --version reports 1.5.1 or later, then select the refresh icon. Include the selected provider and any custom runtime or provider home when reporting the error.
My previous conversations are missing after changing setup
Check whether you changed Location between Separate Korus chats and Use existing setup. Those environments have different provider history and authentication. The location-switch flow can remove the affected local Korus agents and Quick Chats after you acknowledge it; it does not migrate their history into the new location.
Read the provider setup overview before making another change. Preserve any repository edits independently of the conversation history.
GitHub or GitLab works in another app but not in Korus
Coding-provider authentication is separate from GitHub or GitLab access. Korus can use GitHub CLI (gh) authenticated to github.com, GitLab CLI (glab) authenticated to gitlab.com, or a direct connection. Check access on the computer hosting the workspace. In Settings → Integrations, verify the selected account and reconnect the affected service if its CLI account changed. If CLI access is unavailable, complete direct authorization there. Repository browsing and Git clone/push authentication are separate; also check your SSH or HTTPS Git credentials if those operations fail.
If you skipped GitHub or GitLab during onboarding, local folder tasks still work. Connect the service when you need repository browsing, issues, or pull-request and merge-request workflows. Automations only need these integrations if their prompt calls for them.
A task is waiting
Inspect the active conversation for a question, approval, queued instruction, or provider error. A waiting task may need a response before work can continue.
If it is actively running, steer or interrupt through the conversation controls as appropriate.
If a Mission is waiting for review, open the selected stage artifact and either provide feedback or accept the proposal. If standalone Code Review has findings, use its review/remediation flow rather than expecting a conversation message to finish the review automatically.
A worktree or merge fails
Check the repository's status, branch, and existing worktrees. Keep dirty or unfinished work intact. Inspect the reported Git error and resolve the specific conflict before trying integration again.
A browser preview is blank
Confirm the development server is running and the URL uses the correct port. Inspect the browser console and ask the agent to verify the route that failed. A successful build alone does not prove a page rendered.
The in-app Browser is separate from your Chrome browser and its existing tabs. Follow Browser when the task specifically needs Chrome or an existing browser login.
A password manager will not fill a login
Check Settings → Browser to confirm the extension is installed and enabled. Open its toolbar popup, finish sign-in, and unlock the vault. Check that the saved login matches the page's address and grant any site access the extension needs. If Bitwarden reports missing desktop integration, enable browser integration in the Bitwarden desktop app.
Use the extension's Update or Reinstall action when needed, then reload the page. Clear browsing data… signs agents out of websites but preserves extension data; Remove uninstalls the extension and clears its Korus storage. See Browser.
A skill is missing from an agent
Open Settings → Skills → Installed and inspect the provider icons for the skill. Use Sync this skill or Sync to make it available to your configured local agents. An existing conflicting copy is preserved; decide which copy to keep and remove or rename the conflict before syncing again. Remote workspaces use the skills installed on their own computer. See Manage agent skills.
Computer Use cannot act
Enable the capability in Settings → Plugins, then check Settings → General → System permissions for the required macOS access. Record whether discovery, a window observation, an interaction, or capture failed.
Work stops when the app closes
Check Settings → General → Keep Korus ready in the background and its reported daemon status. Distinguish closing the desktop window from intentionally stopping the background service.
When you return, inspect the conversation for an approval, question, or provider error before submitting the same instruction again. Preventing sleep while agents run is a separate General setting.
Report a problem
Include the app version, platform, provider, steps to reproduce, expected result, actual result, and exact error. Use a small reproduction and remove private account details, credentials, and repository content from shared logs or screenshots.