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 intended macOS Apple silicon release and moved it to Applications. Record the app version and any macOS error shown during launch.
Development builds have additional runtime and SDK requirements described in the repository README.
A provider will not connect
- Open Settings → Codex or Settings → Claude Code for the failing engine.
- 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 Codex or Claude Code guide. 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 works in another app but not in Korus
Provider authentication and Korus's GitHub integration are separate connections. Open Settings → Integrations and complete Korus's GitHub authorization. Check that the authorized account can access the intended repository.
If you skipped GitHub during onboarding, local folder tasks still work. Connect GitHub when you need repository browsing, issue and pull-request intake, or Automations.
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.
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.