Provider setup

How providers work

Verde does not host a model and does not relay your prompts through a hosted backend. It spawns and talks to the coding-agent CLIs you already have on your machine, and supports each agent in one or both of two modes:

• GUI chat — the provider drives Verde's native chat panes over its own protocol: streaming transcript, composer, slash commands, approvals.
• Terminal TUI — Verde launches the agent's own TUI inside an embedded Ghostty terminal pane, wired into the sidebar's live status pips.

All of them run against the project directory you imported into Verde. Tokens, transcripts, and project files stay on your machine.

Readiness check

If none of the GUI providers is available at launch, Verde opens Connect an AI provider. Each provider reports Ready, CLI not found, Sign-in needed, or Could not verify while Verde checks its executable and local authentication. Install or sign in using the instructions below, then choose Check again. Open setup guide returns to this page and Not now dismisses the screen.

Amp is excluded from this check because it is TUI-only. A GUI provider can also become unavailable later—for example, after credentials expire—in which case sending shows an explicit error instead of dropping the prompt.

Codex

Install the Codex CLI and authenticate:

codex login

Verify codex is on PATH from a normal shell. Verde starts codex app-server when a Codex thread begins; you do not need to start it yourself.

Codex threads expose Default and Fast under the composer's Run pill. The setting maps to Codex's service_tier / fast_mode. The Run menu also shows the reasoning levels supported by the selected model and the thread's access setting.

Claude Code

Install Claude Code and log in on your machine. Verde talks to the local runtime through Anthropic's Claude Agent SDK — there is no Verde-side authentication. Make sure the Claude Code binary and node are both reachable from the shell environment Verde was launched from. Packaged Verde installs include the provider bridge; Verde runs it with the Node.js executable found on PATH.

OpenCode

Install OpenCode and verify opencode is on PATH. Verde starts opencode serve on demand when an OpenCode thread begins.

OpenCode does not have a Codex-style speed tier concept, so the Speed row is hidden when OpenCode is selected.

Cursor

Install the Cursor CLI, make sure agent is on your PATH, and authenticate:

agent login

CURSOR_API_KEY is also supported for headless environments where interactive login is not possible. Verde talks to the Cursor ACP server (agent acp) over its native protocol.

Cursor models that advertise fast-mode support show Default and Fast under the Run pill. The row is hidden for Cursor models without that capability.

Amp

Install Amp and make sure amp is on your PATH. Amp is TUI-only: it does not appear in the chat composer's provider switcher. Instead, launch it from the command palette (Ctrl+Shift+P → Start New Amp TUI) and Verde opens the amp CLI in a new embedded terminal pane in the current workspace.

To wire Amp into the sidebar's live status pips, install Verde's Amp plugin:

verde integrations install amp --global

That writes a small lifecycle plugin to ~/.config/amp/plugins/verde-notify.ts which reports working / done / error to the pane's status pip as the agent runs (only when Amp is running inside a Verde pane). You can also toggle it from the settings modal under Status pip hooks, and remove it with verde integrations remove amp --global.

Models and run settings

The searchable model picker groups models by provider, marks defaults, and supports Ctrl+1 through Ctrl+9 for its visible results. OpenCode, Claude Code, and Cursor model lists are loaded from the installed provider; Codex uses Verde's supported model list.

Before a new thread sends its first message, choosing a model can also switch the provider. Once the transcript has started, the provider is locked to keep the provider session consistent. The Run pill contains only controls the selected provider/model supports: reasoning, Default/Fast speed, and Supervised/Full access permissions. See Chat, models & runs for the complete behavior.

To run several providers side by side, create additional chat threads (one per provider) and tile them in the same workspace. Each thread keeps its own provider, model, and transcript; the layout is shared.

Driving provider CLIs from terminal docks

You can also launch any provider's TUI directly inside a terminal pane — useful when you want the agent's native UI rather than Verde's chat surface. The command palette (Ctrl+Shift+P) has a Start New … TUI entry for each of Codex, Claude, OpenCode, Cursor, and Amp, plus Open Current Thread in TUI entries that promote a running GUI chat thread into that provider's terminal TUI. Right-clicking inside a terminal offers the same launch profiles as tabs.

From the CLI:

verde live agent open --provider codex
verde live process restart --name codex

The first command opens a managed Codex TUI without requiring a verde.yml entry. The second launches or restarts a Codex agent declared in your verde.yml agents: block. See Configuration & state for the stack schema and the CLI reference for the full command surface.

Troubleshooting provider auth

If prompt sending fails, check in this order:

1. Is the provider installed? which codex, which opencode, which agent, etc., from the shell Verde was launched in. GUI launches on some platforms inherit a different PATH than a terminal — relaunch Verde from a terminal if you suspect this.
2. Is the provider authenticated? Re-run the provider's login command (codex login, agent login, etc.) and confirm credentials are still valid.
3. Is the project imported? Verde runs the provider against the imported project directory. A provider CLI in a different working directory will not see the same files.
4. Check the logs. Provider helper stderr is written to the runtime log alongside Zig panics. On Linux:
   bash

   tail -f ~/.local/share/verde/Native/logs/verde.stderr.log

For broader install and runtime issues, see Troubleshooting.