Skip to content

Provider guides ​

Korus can run different coding engines in the same workspace. Each engine has its own account, conversation location, and customization. Connecting one does not authenticate the others.

EngineInstallation and sign-in
CodexUses an installed CLI, or ChatGPT's runtime on macOS; browser sign-in from Korus
Claude CodeUses an installed CLI or Korus's bundled runtime; sign-in through a command copied from Korus
CursorUses the installed Cursor CLI and its existing setup; sign in from Korus
AntigravityUses the installed Antigravity CLI; native Google sign-in

Choose where each engine keeps its setup ​

Korus checks for an available runtime first. Installed Codex and Claude Code CLIs take precedence over their fallback runtimes. If an engine is missing, Install opens the engine's own installation instructions. The refresh icon rechecks detection. Codex and Claude Code reuse their existing setup by default. Select Continue when an engine is already connected. For Codex, Claude Code, and Antigravity, use Customize to choose a separate setup, either beneath the engine during connection or beside Location in Settings. Cursor uses its existing setup.

There are two choices under Conversations:

ChoiceConversations and sign-inSkills and configuration
Separate Korus chatsKorus uses its own provider home. Sign in for that setup, even if the engine already works in your terminal.Reuse my existing skills can share skills with that home. Other provider configuration remains separate.
Use existing setupKorus uses the provider home you already use outside Korus, including its sign-in and conversation storage.Skills and configuration belong to that existing setup; changes can affect sessions outside Korus too.

New Codex and Claude Code setups default to Use existing setup. Separate Korus chats uses its own sign-in; Reuse my existing skills controls skill sharing for that separate setup. Choose independently for each engine. Existing installations keep their saved choices; check Location to see the selected setup.

A provider home is the folder where that engine keeps its account state, conversations, and user configuration. With the standard Korus installation, separate homes are:

  • Codex: ~/.korus/codex-home
  • Claude Code: ~/.korus/claude-home
  • Antigravity: ~/.korus/antigravity-home

Existing setups normally use ~/.codex, ~/.claude, or ~/.gemini for Antigravity. Custom launch environments can use different paths, so the path displayed under Location is the one to check when troubleshooting.

Separate chats can still share skills

Reuse my existing skills links to your existing provider skills rather than taking a one-time copy. Updates are shared in both directions. For Codex, this choice also shares the provider's plugins; other engines share skills only. It does not copy your sign-in or move your old conversations.

Uncheck Reuse my existing skills if you want to manage those resources separately too. Repository instructions and project configuration still apply to the working folder you open.

Connect and verify ​

  1. Install the engine if needed, choose its conversation setup, then Save.
  2. Follow the Codex, Claude Code, Cursor, or Antigravity sign-in steps. Detected means the runtime is available; Connected means Korus recognizes the selected setup's authentication.
  3. Connect at least one engine, then select Continue on the first connection screen.
  4. In the engine's Settings page, check that Account shows Connected and Enable engine is on.
  5. Start a small conversation and check that the engine can respond before assigning a larger task.

Accounts and usage ​

Authentication, model availability, and usage limits belong to the selected provider. Connecting an account to Korus does not create a new model subscription or transfer one provider's access to another. Claude subscription sign-in and Anthropic Console API billing are separate choices in its connection dialog.

For usage recorded by Korus, open Settings → Analytics. These local statistics are separate from your provider's remaining quota, credits, and billing.

Cursor ​

Run Cursor agents in the same workspace as your other engines. Use them for conversations, delegation, Missions, code reviews, and automations.

Connect Cursor ​

  1. Install the Cursor CLI if needed. Korus detects agent or cursor-agent; the Cursor editor alone does not provide the CLI. Use the refresh icon to recheck detection.
  2. Open Settings → Cursor → Connect, or connect Cursor on the first-run screen, and complete its sign-in flow. Korus uses your existing ~/.cursor setup and account; it does not offer a separate Cursor home.
  3. Check that the account is connected and Enable engine is on. Select Cursor when creating an agent, then choose a model from its live catalog. Reasoning choices depend on the model.

Cursor supports native Plan mode and Korus's interactive plan review. Add comments or choices, request a revision, then approve implementation. Text and image attachments are supported. Saved conversations can be reopened and continued in the same workspace.

Permissions and configuration ​

Use the composer's Permissions menu to choose Ask for approval or Full access. Ask for approval shows permission requests reported by Cursor; Full access approves those requests automatically. Plan approval remains a separate explicit decision in either mode. Cursor can perform native file edits without reporting a permission request, so Ask for approval does not guarantee approval before every edit. Use an isolated worktree and review the resulting changes.

Korus saves the permission choice on the agent and as the default for new Cursor conversations. Existing conversations keep their own choice. Switching to Full access also resolves pending tool-permission requests; switching back restores prompts for subsequent requests. These choices are Korus settings and do not rewrite your shared Cursor configuration.

Queue a follow-up or interrupt before changing direction. The optional Settings → Cursor → Steering fallback setting lets Korus interrupt the current turn and send your update as a new turn in the same conversation; it starts off.

Cursor conversations are available on desktop. Use Codex, Claude Code, or Antigravity for companion-app access or conversation sharing. Forking, goal mode, and editing or retrying old turns depend on the selected engine and are not offered for Cursor.

Usage ​

Cursor's Settings page shows account billing and quota information when available. Analytics records turns and measured timing; token counts, output speed, and per-turn cost are unavailable for Cursor. Account balances are separate from those execution statistics.

Antigravity ​

Antigravity runs on the Antigravity CLI (agy), version 1.5.1 or later, with every model on your account. If it is missing, Welcome and Settings → Antigravity show the install command and a link to Google's instructions:

sh
curl -fsSL https://antigravity.google/cli/install.sh | bash

Select the refresh icon once it is installed. Keep it current with agy update.

Once detected:

  1. Select Customize to choose separate Korus chats or your existing setup. Antigravity's existing setup is ~/.gemini. The Google sign-in is shared by both.
  2. Select Connect Antigravity in Welcome, or Connect in its Settings page, and complete the native Google sign-in flow. Credentials stay with Antigravity; do not paste them into chat.
  3. Wait for Connected, enable the engine, and select it when creating an agent. Verify with a small read-only repository task.

Antigravity supports streaming conversations, history, approvals, interruption, native Plan mode, and Korus workflows including reviews, Missions, delegation, and automations. Review its proposed plan before accepting implementation. Each model appears once, and models that offer thinking levels let you pick one beside the model.

Use the composer's Permissions menu to choose Ask for approval, Allow file edits, or Auto. These govern file edits and commands. Antigravity runs the tools of connected MCP servers without asking in every mode, so connect only servers you trust.

Desktop conversations accept images, WAV audio, PDFs, and UTF-8 text attachments. Antigravity attachments are unavailable for SSH-hosted agents and browser-hosted sessions. Steering a running turn, goals, conversation forks, and edit/retry/delete turn actions are not available; queue a follow-up or interrupt instead. See Conversations for shared controls.

Connect GitHub, GitLab, or Linear ​

Korus detects GitHub CLI (gh) authenticated to github.com on the workspace host. During onboarding, connect Korus directly for faster access or choose Use GitHub CLI. Settings shows Using GitHub CLI with a Connect button for direct authorization. Canceling or disconnecting a direct GitHub connection returns to authenticated CLI access when available. Existing direct connections keep their account. CLI access supports repository, issue, and pull-request workflows; hosted GitHub MCP tools require a direct connection.

GitLab.com works alongside GitHub. Korus detects authenticated GitLab CLI (glab) access on the workspace host, or you can connect directly using GitLab's device sign-in flow. Canceling or disconnecting a direct connection preserves available CLI access. Direct GitLab connections can also authorize the official GitLab MCP tools; CLI access alone does not enable them.

Coding engines and backlog integrations are separate choices. The selected engine runs the agent; GitHub, GitLab, or Linear supplies the work items.

Open Settings → Integrations and connect the service you want to use:

IntegrationConnectBacklog source
GitHubSelect Connect, copy the displayed device code, open GitHub, and authorize Korus. Return when authorization finishes.A GitHub repository, with issues and pull requests.
GitLabSelect Connect, follow the device sign-in instructions on GitLab.com, and return to Korus when authorization finishes.A GitLab project, with issues and merge requests.
LinearSelect Connect, complete sign-in and authorization in the browser, and return to Korus. Check for Connected and the expected account.A Linear team or project, with issues.

Linear does not require pasting an API key or registering your own OAuth application in Settings. Cancel stops an in-progress authorization; use Connect to retry. If the build reports that Linear sign-in is not configured, use a build with Linear configuration rather than entering credentials in chat. Disconnect removes Korus's connection to that service without disconnecting the other integration or your coding engines.

In backlog pickers, choose the provider first, then its Repository or Team / project. Browsing only offers connected providers; with one connected provider, the provider selector is hidden.

A Linear team or project identifies where the issue lives, not where code runs. Work started from a repository uses that repository. Without a repository context, choose a Code repository before starting. Automations schedule prompts independently of work sources; include the repository in the prompt when asking a Quick Chat to create an agent or worktree.

Git branches, commits, pushes, and delivery requests still belong to the code repository. GitHub repositories use pull requests; GitLab projects use merge requests. Linear supplies backlog work alongside those delivery workflows. See Browse and start backlog work and Missions for the entry points.

Remote hosts ​

Run agents on another computer while keeping their conversations alongside local work in the same workspace.

  1. Configure SSH key access to the host and add it to your SSH configuration.
  2. Open Settings → Connections → Add remote, choose the host, and connect. Verify the host identity when asked.
  3. Initialize the environment and select the coding engines to install. Korus prepares its remote runtime and reports setup progress.
  4. Expand the host's row to connect the selected coding-provider accounts and manage engine updates. A working local sign-in does not establish remote access; check each remote engine's connection state.
  5. When opening a repository or creating work, choose Host. Korus can use an existing clone there or clone the repository from its origin. Check the destination path, coding engine, and model before starting.

Local and remote agents can share a workspace, but each agent's files, Git operations, tools, and running processes belong to its host. A repository credential or service available locally may need separate setup there. Agents stay on their chosen host; create another agent to work elsewhere.

The host indicator shows connection health separately from whether the coding engine is signed in. If it is unavailable, reconnect from Connections rather than creating a duplicate agent. Update Korus upgrades the remote runtime; finish active turns and pending requests first. Removing the connection removes those remote agents from this app while leaving them running on the host. Missions and conversation sharing use local agents.

Manage agent skills ​

Open Settings → Skills to give your coding agents reusable instructions for design, security, testing, and other work.

Discover and install ​

The Discover tab offers individual skills and packs, including Security audit, Web design guidelines, Impeccable, Matt Pocock's skills, Superpowers, and pstack. Choose Install or Install pack to add one.

To bring another source, choose Install skill and paste a GitHub repository or skill-folder URL, a skills.sh skill URL, or a skills add command. When several coding agents are configured, select which should receive the installation. Packs install the skills they contain; check the source and instructions before using code or workflows from an unfamiliar author.

Inspect and sync ​

The Installed tab includes skills installed through Korus and skills already present in your local coding-agent setups. Search by name or description, switch between Personal and Built-in, and check the provider icons to see where a skill is available.

Open a skill's … → View skill action to read its instructions. When installed copies differ, the viewer lets you inspect each version. Installing a skill does not by itself run its workflow; select or request the skill in a conversation when you want the agent to use it.

Choose Sync to make personal skills available across your configured local coding agents, or Sync this skill for one entry. Existing conflicting installations are preserved. If a provider still shows a conflict, decide which copy to keep, remove or rename the conflicting installation, and sync again. Remote computers manage their own skills.

Refresh or remove ​

Use Refresh on a managed skill or pack in Discover to download its source again. In Installed, Delete skill asks for confirmation before removing that skill's installed folders across configured coding agents. Uninstall on a pack removes the skills Korus installed from that pack. Original sources of linked skills are kept, and built-in skills are protected from deletion.

Skills add instructions and workflows; your provider account still supplies model access. They are separate from browser extensions and coding-provider plugins.

Choosing an engine ​

When multiple engines are available, choose an engine when starting new work. With only one available engine, Korus can use it without showing a picker. Models, reasoning controls, and permission choices depend on that engine.

An existing conversation stays with its provider. Connecting another engine does not convert it. To continue work with another engine, use Hand off…, which creates a replacement agent in the same workspace using a written handoff.

Enable engine controls whether Korus uses an engine without signing out. Disconnect signs out of the account in the selected provider home; saved conversations remain. With Use existing setup, that sign-out also affects the shared terminal setup. Korus prevents turning off the last active engine with the enable toggle; connect or enable another one first.

Change the conversation location later ​

Choose the location before creating agents when possible. Switching between Separate Korus chats and Use existing setup after starting work has consequences:

  1. Wait until the affected engine's local agents are idle. Finish or discard affected code reviews and finish affected Mission runs.
  2. Open the engine's Settings page, choose Customize, select the new location, and select Save.
  3. Review Change conversation setup? Korus reports how many local agents, including Quick Chats, will be removed.
  4. Acknowledge the removal, then choose Remove agents and switch only if you intend to proceed.
  5. Connect the new setup if needed and create new agents there.

Conversation files remain in the previous provider home. This action does not migrate them, and switching back does not restore the removed agents in Korus. Your repository folders and worktrees are not deleted by the location switch. Remote-workspace agents use their remote host's setup and are outside this local reset.

If the connection behaves differently from your terminal ​

Compare the path under Location first. A working terminal sign-in, skill, or MCP server may belong to an existing home while Korus is using a separate one. Resolve installation and authentication errors in the engine's Settings page, then verify with a small conversation.

For additional help, record the engine, app version, displayed location, and exact error. Continue with Troubleshooting.