Last updated: November 2026
Use Settings → Agents to install the coding agents you already use, sign in to them, and choose how they run in Kepler. You sign in with your own agent account, and Kepler adds no markup on the agents you bring.
Kepler supports 9 agents. You can also add any other agent that speaks the Agent Client Protocol (ACP), or whose command-line interface you want to run inside a task.

Supported agents
Each agent gets its own section in Settings → Agents, in this order:
| Agent | Name in Settings | How Kepler runs it | Run modes | Multiple accounts |
|---|---|---|---|---|
| Claude Code | Claude Code | Your installed claude CLI |
Chat or Terminal | Yes |
| Codex | Codex | Your installed codex CLI |
Chat or Terminal | Yes |
| GitHub Copilot | GitHub Copilot | Your installed copilot CLI |
Chat or Terminal | Yes |
| OpenCode | OpenCode | Your installed opencode CLI, v2 |
Chat or Terminal | No |
| Pi | Pi | Your installed pi CLI, in its own terminal interface |
Terminal only | No |
| Auggie | Auggie | Your installed auggie CLI |
Chat or Terminal | Yes |
| Google Antigravity | Antigravity | Your installed agy CLI |
Terminal (default) or Chat | No |
| Cursor | Cursor | Your installed cursor-agent CLI |
Chat or Terminal | No |
| Grok Build | Grok Build | Your installed grok CLI |
Chat or Terminal | Yes |
Auggie is Augment’s coding agent. Like Claude Code and Codex, it reports plan usage back to Kepler, but only as a credit balance rather than usage windows. Google Antigravity reports a percentage used for each limit on the selected model, including its 5-hour and weekly windows. To learn about the plan usage meter, see Agent Sessions.
Kepler asks each agent’s provider for plan usage while Check plan usage with each agent’s provider is on. This setting is in Settings → Agents → Usage and recovery, and it is on by default.
Grok Build is xAI’s coding agent. It signs in through your browser, or you can supply an xAI API key.
Google Antigravity runs the agy CLI in both modes. Its sessions start in Terminal unless you pick Chat. Chat needs Antigravity CLI 1.5.0 or newer. With an older CLI, Kepler asks you to update it in Settings → Agents.
Pi is terminal-only. Kepler runs Pi’s own interface in a terminal inside the task. Kepler does not check Pi’s sign-in. Pi uses its own sign-in (/login, or the provider API-key environment variables it reads directly).
With Pi 1.x, a session gets the task’s context and Kepler’s workspace tools, and your own Pi configuration stays as it was. With other Pi versions, Kepler pastes the task’s context into the session instead. A Pi session resumes where it left off.
OpenCode needs version 2. Kepler does not start a session on an OpenCode 1 binary. A conversation you started under OpenCode 1 resumes in OpenCode 2.
Kepler’s tools in Terminal mode. If a Terminal session shows No Kepler tools on its status bar, choose Continue in Chat from the session menu to give the agent Kepler’s workspace tools. These agents get them in Terminal mode too, without any change to your own config:
| Agent | In Terminal mode |
|---|---|
| Claude Code, Pi, OpenCode 2.1.1 or newer | Kepler’s workspace tools, and Kepler wakes an idle session to read its inbox |
| Google Antigravity 1.5.3 or newer | Kepler’s workspace tools only |
Folder trust. A Claude Code or Pi session does not stop at the CLI’s own trust question in a repository, worktree, or folder you marked Trusted in Kepler. A worktree also inherits the trust you already gave its repository. See Trust a repository.
To choose between Chat and Terminal for an agent, see Run modes.
These 2 agents need a recent build to run in Chat:
| Agent | Minimum |
|---|---|
| GitHub Copilot | CLI v1.0 or newer |
| Cursor CLI | A build from early 2026 or newer |
Kepler checks the build before it starts a session, and tells you to update if it is too old.
Install an agent
When an agent is not installed, its section reads Not installed and offers Install, which opens Set up agent. Pick an install method, and Kepler runs the install command for you and shows its output. Cancel stops an install in progress. Once the install finishes, Kepler opens Sign in to agent if the agent needs a sign-in. Installs and updates run one at a time.
The install methods depend on the operating system of the machine you are on:
| Agent | macOS | Linux | Windows |
|---|---|---|---|
| Claude Code | Native installer, Homebrew, npm (global) | Native installer, Homebrew, npm (global) | Native installer, winget, npm (global) |
| Codex | Standalone installer, Homebrew, npm (global) | Standalone installer, npm (global) | Standalone installer, npm (global) |
| GitHub Copilot | Native installer, Homebrew, npm (global) | Native installer, Homebrew, npm (global) | winget, npm (global) |
| Cursor CLI | Native installer, Homebrew | Native installer | Native installer |
| Auggie | npm (global) | npm (global) | npm (global) |
| OpenCode | Native installer, Homebrew, npm (global) | Native installer, Homebrew, npm (global), pacman | npm (global) |
| Grok Build | Native installer | Native installer | Native installer |
| Pi | Native installer, npm (global) | Native installer, npm (global) | Native installer, npm (global) |
| Google Antigravity | Native installer | Native installer | Native installer |
Every OpenCode method installs OpenCode 2.
The dialog marks Claude Code’s npm (global) method Deprecated by Anthropic.
Kepler offers a method only when the tool it runs, such as Homebrew or npm, is installed. A method that needs Node.js says so when Node.js is missing. If none of an agent’s methods can run, Kepler says so and points you to the custom binary path instead. If the vendor’s desktop app is installed, such as Claude or ChatGPT, you still need the command-line tool, and the dialog says so.
If you already installed the agent somewhere Kepler did not find it, tell Kepler where it is from the same dialog:
- Under Already installed?, type the program’s full path in the Full path to agent field, or click Browse… to pick it.
- Click Use this, or press Enter.
Kepler saves the path as the agent’s Binary if the agent runs from it. If it does not, Kepler keeps the path you had before.

The install output pane stays open after the install finishes. Read it before you dismiss it: errors such as a permissions failure appear only there.
Binary detection
Kepler finds each agent’s binary the way your shell does: the first match on your PATH, the same one which reports. It also finds an agent installed by nvm or Homebrew, even when you did not launch Kepler from a terminal. After you change your shell’s startup files, click Restart agent or Rescan, and the agent picks up the change without a Kepler restart.
Each agent’s card in Settings → Agents shows what Kepler resolved. The version and Install are in the card’s title line. Binary and Data folder are under Program and data folder:
| Control | What it does |
|---|---|
| Version | The installed version, or Not installed |
| Install | Runs one of the install methods above. Shown when the agent is not installed |
| Binary | The resolved absolute path, or Not found, with where it came from (PATH, Shell, or Common) and its version |
| Rescan | Re-detects this agent’s binary. Use it after installing or removing one outside Kepler |
| Custom path… | Pins an absolute path of your own, which must be a file |
| Clear custom | Drops the pinned path and goes back to automatic resolution. Shown only while a custom path is set |
| Installed versions | A picker listing every install Kepler found, with an Auto row. Appears only when Kepler finds more than one |
| Data folder | Overrides the agent’s own data and config directory. Leave it empty for the agent default |
| Enabled | Whether Kepler offers this agent when you start a session |
If Kepler cannot read an installed agent’s version, its section shows a Version unknown badge, and features that depend on the version stay off, such as sending a new session’s first message automatically. To fix it, reinstall or update the agent.
When an installed version has a known problem, the agent’s card shows a warning under its title line that names the version and what to do. For example:
| Agent | What the warning tells you |
|---|---|
| OpenCode | OpenCode 1 is not supported, and its sessions do not start. Install OpenCode 2, or pick an OpenCode 2 binary |
| Auggie | Chat sessions with this version may not load your MCP servers |
| Codex | This version can show approval prompts that need no answer. Update Codex to 0.163.0 or newer |

If a custom path later disappears, such as after an auto-update removes an old version, Kepler finds the agent itself again instead of reporting it missing.
Above the agent cards in Settings → Agents, Rescan re-detects every agent at once, and Update all runs each installed agent’s own updater.

Sign in to an agent
An installed agent shows Sign in until it has a credential, and Sign out once it does. Sign in opens a modal listing the methods that agent supports on this machine, plus any methods Kepler provides itself. If the agent refuses a credential, the account shows Sign in again, and the modal shows the agent’s reason:
| Agent | How you sign in |
|---|---|
| Claude Code | Browser sign-in. Kepler runs the sign-in for you and your browser opens; you paste a code back only if the browser callback cannot reach Kepler. More sign-in options adds Amazon Bedrock, Google Vertex AI, Microsoft Foundry, and LLM gateway |
| Codex | Sign in with a ChatGPT account through your browser, or enter an API key. On a remote, ChatGPT (device code) |
| GitHub Copilot | Sign in with GitHub: open github.com/login/device and enter the one-time code Kepler shows |
| Cursor CLI | Cursor’s own browser sign-in, driven from the modal, or Paste an API key from the Cursor dashboard. On a remote, only the API key works |
| Auggie | Sign in with browser, or Paste session token |
| OpenCode | OpenCode account (Go or Console): sign in through your browser with a one-time code. OpenCode also resolves providers from its own config file and provider environment variables |
| Grok Build | Browser sign-in, or Paste an API key for a deployment with no local browser |
| Google Antigravity | Sign in in Terminal: sign in, type /exit in the terminal, then confirm in the modal. The modal also lists the Google sign-in methods the CLI offers |
| Pi | Nothing to do in Kepler. Sign in inside the CLI itself, or set the provider environment variables it reads |
Claude Code through a cloud provider or gateway
To run Claude Code through your cloud provider rather than a Claude account, click More sign-in options in the Sign in to Claude Code modal and pick a method:
| Method | What you enter |
|---|---|
| Amazon Bedrock | A Bedrock API key (AWS_BEARER_TOKEN_BEDROCK) and the AWS region (AWS_REGION) |
| Google Vertex AI | The project (ANTHROPIC_VERTEX_PROJECT_ID) and region (CLOUD_ML_REGION), and optionally a credentials file (GOOGLE_APPLICATION_CREDENTIALS). Leave the file empty to use application default credentials |
| Microsoft Foundry | The resource name only (ANTHROPIC_FOUNDRY_RESOURCE), and optionally an API key and your Opus, Sonnet, and Haiku deployment names. Without a key, it signs in with Microsoft Entra ID credentials on this machine |
| LLM gateway | The gateway’s URL (ANTHROPIC_BASE_URL) and the token it issues (ANTHROPIC_AUTH_TOKEN), plus any other NAME=value variables your gateway needs |

The account then reads as the provider and its region, project, or resource, or as the gateway’s host. Kepler shows no plan usage for it, because the plan belongs to your cloud provider. Saving one method clears the values stored for the others, and Sign out clears the provider. You can set a gateway’s extra variables only on the computer running Kepler, not from a paired device.
OpenCode account
OpenCode account (Go or Console) signs OpenCode in to your OpenCode account:
- Click Sign in on OpenCode’s card and pick OpenCode account (Go or Console).
- Click Open sign-in in browser and enter the One-time code the modal shows.
- Choose the workspace with your Go subscription.
- Select a Go model to use your plan.
The agent’s card then shows OpenCode as signed in.

Browser sign-in, including on a remote
Claude Code and Codex both sign in through your browser, and neither needs a terminal to do it.
This also works on a remote environment:
- Claude Code on a remote offers Sign in with Claude.ai, which opens Claude’s sign-in in your local browser and takes the code you paste back. Kepler saves the credential on the remote machine. Sign in with token (advanced) is for an account that cannot finish a browser sign-in.
- Codex on a remote offers ChatGPT (device code). Kepler shows the sign-in link and a One-time code, and the credential is saved on the remote machine. Some ChatGPT workspaces turn device sign-in off, and Kepler then points you to the alternatives.
- Cursor CLI on a remote offers only Paste an API key, because its browser sign-in cannot complete there.
Wherever Kepler opens a browser sign-in for Claude Code, Codex, or Antigravity, Open sign-in in browser appears beside a read-only Sign-in link field with Copy link. To open the link in another browser or profile, copy it.
When a sign-in runs in a terminal on a remote and the browser page does not load after you sign in, paste that page’s address into the box under the terminal and click Send. Kepler opens the address on the remote machine, if the sign-in printed it. You then finish in the terminal.
Import local Codex login is the other remote route, in the desktop app: it copies this machine’s ~/.codex/auth.json to the remote target, and asks you to confirm on this machine before it reads the file. The import copies a credential: anyone with access to that remote machine can send Codex requests on your account until you sign out.
A Codex API key, entered in the modal, works locally and on a remote. Sign out on Codex signs the CLI itself out, and Kepler follows a sign-in you do in the Codex CLI outside Kepler.
Auggie’s sign-in methods
Auggie supports 2 sign-in methods:
| Method | What it does | Where it works |
|---|---|---|
| Sign in with browser | Runs Auggie’s sign-in and finishes it in your browser | Local, and over SSH: the remote variant opens the page in your local browser and takes a pasted JSON response |
| Paste session token | You paste the JSON from auggie token print into Kepler. Kepler stores it and supplies it on every session |
Anywhere, including CI-style setups with no browser |
If you run Auggie’s browser sign-in on this machine yourself, Kepler detects it and you can skip the token paste.
Multiple accounts of one agent
Claude Code, Codex, GitHub Copilot, Auggie, and Grok Build support more than one signed-in account. To add one, open Settings → Agents → your agent → Accounts and click Add account. Each account keeps its own credentials. Claude Code, Codex, and GitHub Copilot accounts can share their conversation history with the CLI, and a Copilot account shares it by default.
To give each added account its own color, pick one from the swatch at the left of its row. Kepler tints the agent icon with that color on session tabs, the task’s context panel, and the terminal status bar, so you can tell sessions on different accounts apart. The default account stays uncolored.
For Auggie, you can only add a second account with Paste session token. Its browser sign-in would sign the second account in as the first.
Run modes
Every agent except Pi runs in 2 modes, and each agent keeps its own default. To pick the default for an agent, open Settings → Agents, expand the agent, and set New sessions start in:
| Mode | What you get |
|---|---|
| Chat | Kepler shows the conversation itself, with replies, diffs, and plans you can read, review, and search. This is the default |
| Terminal | The agent’s own command-line app, with its commands, shortcuts, and settings, in a terminal inside the task |
To start one session in the other mode without changing the default, set Start in in the composer’s Agent settings before you send the first message. An agent that offers only one mode shows no switch at all. See Agent Sessions.
Chat sessions show up as Kepler in places such as your Anthropic dashboard.
Detecting sessions started outside Kepler
Settings → Integrations → Your terminal → Show sessions started outside Kepler is a separate setting that applies to all agents, and it is off by default. It installs GitKraken hooks so sessions you start in your own terminal show up in Kepler. It covers every agent Kepler can track that way: Claude Code, Codex, Cursor, GitHub Copilot, OpenCode, Auggie, Grok Build, Pi, and Google Antigravity. See Agent Sessions.
Kepler also follows its own Terminal sessions this way. If a running Terminal session stops reporting to Kepler, Kepler warns that Agent sessions aren’t reporting to Kepler. Click Repair, then restart any session that still does not report. To repair sessions running on another computer, use Kepler on that computer.
Programs that report their own status
Some terminal programs report their own status to Kepler. When an agent’s terminal program does this, Kepler shows the session as working, blocked, or done from what the program reports. See Agent Sessions.
Your default agent
New sessions start with, in Settings → Tasks → New tasks, sets the agent, account, model, mode, and options a new session starts with. You pick them in the same Agent settings pill as the composer, and you can start from an agent preset. Start each session on the agent you used last is on by default: your first session uses the pill’s agent, and each later one starts on your last pick. To always start on the pill’s agent, clear it. See Default agent.
Kepler saves agent options per account. Picking a different account of the same agent brings up that account’s own saved model and options, so a larger model you chose on your work account does not carry over to your personal one.
Only agents that are installed and Enabled appear in the picker. If your saved default is no longer installed, Kepler says so and asks you to pick another.
An Action can override all of this. See Actions for how an Action pins a provider, account, model, mode, and options together, and which choice wins when they disagree.
Custom agents
If your agent is not one of the 9 supported agents, you can add it by its command. To add one, open Settings → Agents → Custom agents, click New custom agent, and fill in these fields:
| Field | What it holds |
|---|---|
| Name | What the agent is called in Kepler’s pickers |
| Runs in | Chat (Kepler’s chat, for a program that speaks ACP) or Terminal (the command’s own app, in a terminal) |
| Command | The binary to run: an absolute path, or a name Kepler resolves on your PATH |
| Args (one per line) | Arguments for the command. For a Chat agent, the arguments that put it into ACP mode, for example --acp |
| Environment variables (KEY=value, one per line) | Variables merged into the agent’s environment on every session |
Kepler treats environment values as secrets: it encrypts them at rest and hides them after you save. When you edit a custom agent, leaving a value empty (KEY=) keeps the stored secret, and typing a new value replaces it.
Custom agents appear alongside the built-in agents everywhere you can choose an agent. A custom agent that runs in Terminal works the same way as a built-in one.
MCP servers
Kepler lists the MCP servers each agent loads. You can add, remove, sign in to, and turn off servers or single tools, per repository from the composer’s Agent settings pill, or as defaults in Settings → Agents → MCP servers. See MCP Servers.
Sessions
After you connect an agent, you run it in a session inside a task. To learn how to start and resume sessions, queue prompts, and review what the agent produced, see Agent Sessions.
A task holds resources and does not require a worktree, or even a repository. See Tasks and Resources.
To follow conversations you started outside Kepler, see Sessions started outside Kepler.