Styx doesn't come with an AI of its own. It runs the coding agent CLIs on your computer, signed in to plans you already have, so there are no API keys to paste and your prompts go straight from the agent to its provider. This page covers getting an agent from "not on this computer" to "ready".
Supported agents
| Agent | The CLI Styx runs | Sign in with |
|---|---|---|
| Claude Code | claude | A Claude Pro or Max plan |
| Codex | codex | A ChatGPT Plus, Pro or Team plan |
| Gemini CLI | gemini | A Google account |
| Cursor agent | cursor-agent (or agent) | A Cursor plan |
| OpenCode | opencode | Any provider OpenCode supports, or none for its free models |
| Goose | goose | Any provider configured with goose configure |
| Amp | amp | Your Amp account (amp login) |
| Shell | Your shell (zsh, bash or PowerShell) | Nothing to sign in to |
You can use any mix. Each task picks its agent, so one project can have Claude Code on one branch and Codex on another.
Set up an agent from Styx
The quickest way is to let Styx do it. During first-run setup, the Your AI step shows one card per plan. Later, open Settings › Agents and select Connect on the agent's row; the same card opens there.
On the card, Set up runs four steps out of sight and ticks each one off:
- Getting ready. Anything the agent needs first. Gemini CLI needs Node.js, so Styx downloads a private copy if you don't have one. On Windows, Claude Code uses git for its commands, so Styx installs git; if that fails, Claude uses PowerShell instead and everything else works.
- Installing. The vendor's own installer, the same command their docs give you. For example
curl -fsSL https://claude.ai/install.sh | bashfor Claude Code on a Mac, orbrew install gemini-cli(ornpm install -g @google/gemini-cliwithout Homebrew) for Gemini CLI. - Signing in. The agent's own sign-in opens in your browser. Sign in, approve, and come back: the card moves on by itself. If the browser didn't open, Didn't open? Copy the link; if your browser shows a code, paste it into the card.
- Testing. Styx sends one tiny message and waits for the answer, so Ready means the plan really works.
One ready agent is enough to start. Show details shows what the installer or sign-in printed, if you want to see it.
OpenCode has no card: it isn't one plan, and its sign-in asks which provider you want. In Settings › Agents, Connect on its row opens the tools straight away: Install opencode… runs OpenCode's own installer (curl -fsSL https://opencode.ai/install | bash on a Mac or Linux, npm install -g opencode-ai on Windows) in a terminal you can watch, and Sign in with opencode… runs opencode auth login there, where you pick a provider and sign in or paste its key.
Goose also uses the tools dialog in Settings › Agents. Install the Goose CLI and run Sign in (goose configure) to choose a provider and model. Styx uses goose acp for native chat and approvals when available; older versions run in a terminal. Goose owns its provider credentials. Verify leaves it not verified because Goose has no offline identity probe: its provider check spends a model turn. You can still start a task.
Goose starts in approval mode for Default, Accept edits and Auto: tool calls ask you here. Plan and Don’t ask use Goose’s chat-only mode, which disables all tools, including reads. Only Bypass permissions selects Goose’s automatic tool approval. These settings apply to the session process and do not change your Goose configuration.
Amp uses the manual tools in Settings › Agents. Install the CLI, then Sign in with amp login. Styx keeps credentials with Amp. Verify remains not verified; use Amp’s own account tools to check your login. A task can still start.
Amp runs its interactive terminal inside the task’s worktree, with Styx MCP tools and target-command shims. Open the task’s Terminal tab to read replies and answer Amp’s prompts. Its stream-json format has no documented interactive approval response, so Styx keeps tool prompts in Amp’s terminal. Native chat cards, live mode switches and background tasks are unavailable. Default, Accept edits and Auto ask before every tool; Plan and Don’t ask reject every tool, including reads. Only Bypass permissions requests automatic tool approval through a process flag; that setting is never saved in the worktree. These rules apply at launch. The model field takes Amp mode names, such as low, medium or high.
Styx temporarily pins those rules in an untracked .amp/settings.json and restores that file verbatim on cleanup; a pre-existing .amp/settings.jsonc is left untouched and shadowed for the session. A tracked or invalid settings.json, symbolic link or junction stops launch rather than changing versioned settings or following a linked path. Provider keys and the Styx broker token are not written there.
If a step stops, the card says why in one sentence and offers the fix:
- Needs a plan: you're signed in, but that account doesn't include the agent (for example Claude on the free plan). See plans opens the vendor's plans.
- Out of usage: the plan answered that it's out of usage for now. It works again when your limit resets.
- Out of date: the installed CLI is too old to use from Styx. Update takes a few seconds.
- Stopped or Not signed in: Try again. Show details has what the CLI said.
Signing in
Sign-in always happens in the agent's own flow: claude auth login, codex login, cursor-agent login or opencode auth login, and Gemini CLI signs in on its first run. Styx never sees your password and never stores a token. It keeps two things: where the CLI lives on disk, and which account it reports being signed in as.
To check an agent, select Verify on its row in Settings › Agents: Styx asks the CLI who it's signed in as and shows the account. For OpenCode that's the providers it has a login or a key for (for example Anthropic, OpenRouter). With none, OpenCode can still use its free models, but the row says signed out.
Settings › Agents
Settings › Agents has one row per agent: its version and where it was found, the account it's signed in as, and its state (connected, signed out, not installed, not verified or check failed). An agent that isn't ready has a highlighted Connect button; one that is has Reconnect. Rescan re-detects every agent now.
Under the table, Preferences has the Default agent, Shell (Windows) (PowerShell or WSL), the Detected CLIs line, and, when an agent is installed in more than one place, a row to pick which copy Styx runs.
Models and effort
Each task can use its own model, effort and permission mode. Set them in the fields under the New task box, or change them during a task from the controls under the chat's composer. Per project, the defaults live in the project's Agent defaults (in the project's nav): Default agent, Model, Permission mode and Effort.
What you can pick depends on the agent:
- Claude Code: Default, Fable, Opus, Sonnet or Haiku, and an effort from Low to Max.
- Codex: the models your Codex account lists, and the efforts each model supports.
- Gemini CLI and Cursor agent: the CLI's own default model. They have no effort setting.
- OpenCode: the models OpenCode lists for the providers you're signed in to (written
provider/model), plus its free models. No effort setting.
How Styx finds agents
Styx looks for each CLI where your terminal would find it, and in the places the vendors install it:
- Your shell's PATH. Styx asks your login shell, so a CLI that works when you type its name in a terminal is found, including one behind an alias or a version-manager shim (nvm, fnm, volta, asdf, mise and so on).
- The usual install folders, even when they aren't on your PATH:
~/.local/bin,~/.opencode/bin, Homebrew, npm's global folders, and on Windows%USERPROFILE%\.local\bin,%APPDATA%\npm, WinGet and Scoop. - Copies bundled with other apps: the Claude Code and Codex extensions in VS Code, Cursor and Windsurf, and the Claude desktop app.
Styx watches those folders, so an agent you install in a terminal shows up within a second or so. The row's location says where each copy came from (PATH, shell, install folder, VS Code extension, set up by Styx, located manually and so on).
When an agent isn't detected
Open Settings › Agents, select Connect on the agent's row, then I'll do it myself for the manual tools:
- Check it runs in a terminal. Open a new terminal and run
claude --version(orcodex,gemini,cursor-agent,opencode,goose,amp). If that fails too, the CLI isn't installed or isn't on your PATH: use the dialog's Install link, which runs the vendor's installer in a terminal you can watch, or Install guide for the vendor's instructions. - Rescan. If you just installed it, select Rescan in Settings › Agents. A CLI installed into a brand new folder may also need you to open a new terminal so your shell picks up the PATH change.
- Point Styx at it. Type a path or a command name into Path or command (for example
~/.local/bin/claude, or justclaude) and select Use, or Locate binary to pick the file. Styx runs it before accepting it, and tells you if you picked a folder, a file that doesn't report a version, or a different agent's CLI. - See where Styx looked. Looked in n folders and Show where list every folder searched, so "not installed" is never a mystery.
To go back to automatic detection after locating a binary by hand, select Forget binary, or choose Detected automatically in the agent's binary row under Preferences.
More problems and fixes, such as an agent that's signed out or out of usage in the middle of a task, are in Troubleshooting.