Claude Agent SDK provider

Run agents through Anthropic's official Claude Agent SDK (Claude Code's harness) from inside Cerevisor.

What this provider is

Cerevisor's Claude Agent SDK provider hands an entire agent run to Anthropic's Claude Agent SDK, running inside Cerevisor. This is the same agent engine that powers Claude Code.

Unlike the native Anthropic provider (where Cerevisor runs the agent itself and you can approve every tool call as it happens), here Claude Code runs the work in its own engine while Cerevisor supervises: you set the rules up front, then the SDK works on its own from start to finish. You get Claude Code-style agent behavior (read, write, edit, bash, glob, grep tools out of the box) without leaving Cerevisor.

Best fit for users who want Claude Code's agent UX inside a Cerevisor workflow.

Setup

You can sign in two ways — pick whichever matches how you already pay for Claude. The choice is a toggle at the top of the provider's setup screen (How do you want to sign in?), and you can change it later by editing the provider.

Option A — Anthropic API key (billed per token)

You need an Anthropic API key from console.anthropic.com.

  1. Settings → Providers → + Add provider → Claude Code (Claude Agent SDK).
  2. Leave the sign-in toggle on Anthropic API key.
  3. Paste your API key into the API key field.
  4. Click Test connection. Cerevisor verifies the SDK is installed and the key authenticates.
  5. Click Save.

The key is stored in a dedicated OS keychain slot, distinct from the native Anthropic provider's slot. You can have both providers configured side by side with the same key without conflict.

Option B — Your Claude Pro/Max subscription (no API key)

If you already pay for Claude Pro or Max, you can power agent runs from that subscription's quota instead of buying API credits — the same way the Codex CLI provider uses a ChatGPT subscription.

  1. Open the setup pane's Claude Pro / Max tile (small label: via Claude Code), or Settings → Providers → + Add provider.
  2. Switch the sign-in toggle to Claude plan.
  3. Click Sign in with Claude. Your browser opens and Cerevisor captures the sign-in for you — no terminal, nothing to paste. There is nothing to install either: Cerevisor carries its own copy of Claude Code and uses yours instead when yours is newer. - Already signed in to Claude on this machine? Most people land on connected without doing anything — the setup screen says so when it finds an existing sign-in. - The wait can end: help appears after a minute, the wait stops after five, and Cancel ends it at any time.
  4. Click Test connection. Cerevisor asks Claude one real question and checks that a real answer comes back. If you later sign out of Claude, this test fails with the sign-in message rather than passing on a stale hint.
  5. Click Save.

Heads-up: subscriptions have usage limits. Pro/Max plans cap usage over rolling windows. Because a Cerevisor workflow can fan out many agents per run, a heavy run can hit that cap and throttle — where an API key would simply keep going (and keep billing). Use the subscription for everyday runs; reach for an API key (Option A, or the native Anthropic provider) when you need to run large workflows without interruption.

Your sign-in is passed only to that run. On a Claude plan, Cerevisor also makes sure an Anthropic API key that happens to be set on your computer can't quietly take over and bill API credits instead.

Models

The default is claude-sonnet-5 (cost-effective production default for SDK runs). You can override it in the Library entry's default model field, or per-agent via Agent Config → Provider override.

In API-key mode the model dropdown is pulled live from your account. In subscription mode there's no key to list the catalog with, so Cerevisor offers a short curated list (claude-sonnet-5, claude-opus-5, claude-fable-5, claude-opus-4-8, claude-haiku-4-5) — you can also just type any model id. To target a specific model, type its id in the default model field or the agent's override.

Cost

In API-key mode, Cerevisor records the usage Claude Code reports and the run is billed through your Anthropic account. The estimate before a run shows $0, because how much work the agent will do isn't known in advance.

In subscription mode, runs are quota-billed against your Pro/Max plan, so Cerevisor reports the cost as $0 and analytics tags the session as Subscription (the same treatment as Codex CLI). The SDK may report a list-price figure internally, but it isn't real per-token spend, so Cerevisor deliberately doesn't surface it.

Current limitations

The Claude Agent SDK provider intentionally trades some Cerevisor features for the SDK's full agent engine:

  • No mid-run conversation continuation. Cerevisor's automatic retries after an output check don't run for these agents.
  • No Cerevisor subagents. Claude Code has its own way of starting subagents, separate from Cerevisor's.
  • No skills from Cerevisor. Claude Code finds its own skills (it reads .claude/skills/ directly). Skills you assign in Cerevisor are not passed in.
  • No interactive permission prompts. Every tool call is still checked against your workflow permissions (see below), but there is no mid-run "Allow this?" dialog: a tool your policy blocks is denied outright.

These limitations mirror the Codex CLI and Cursor Agent providers, which share the same shape: the external tool runs the work while Cerevisor supervises.

How your workflow permissions apply

Cerevisor gates each tool call the SDK makes, live, against the same workflow permissions the native providers enforce — with no interactive prompt:

Tool the SDK wants What Cerevisor checks
Bash The actual command is evaluated: shell execution must be allowed, and the command must pass the same git / package-install / destructive-command rules as native runs.
Write (new files) Allow file creation.
Edit / MultiEdit / NotebookEdit Allow file modification.
WebFetch / WebSearch Allow web access.
Read / Glob / Grep and other read-only tools Always allowed.

A blocked call is denied with a message explaining which permission blocked it, and the agent continues with that knowledge. Runs are also capped at 50 turns so a stuck agent can't burn your quota unattended.

Chatting with a finished agent

Workflow runs persist their SDK session, so after a run completes you can chat with the agent to revise its output — the conversation resumes with full context of what it did. (Claude Code keeps this session history on your disk, outside Cerevisor; the provider card notes this too.)

Background features on this provider

Background features (run retrospectives, meta-cognition enrichment, skill summaries, memory upkeep) still work when this is your default: each call runs as one small agent task on your Claude sign-in. If a call fails (not signed in, quota exhausted), Cerevisor automatically retries it on another provider in your library that can answer it, and any fallback spend shows in Analytics → Models.

See Provider overview → Background features for the full split.

Chat builder on a subscription

The chat builder is a special case. By default it also needs a chat-capable provider, and when your provider can't chat it offers an inline panel to point the builder at a separate chat-capable credential (the most reliable path).

But you can run the chat builder directly on Claude Code (including subscription auth), Codex, or Cursor: turn on Settings → Chat Builder → "Build with a subscription provider." With it on, each builder message runs as a single agent task that inspects your project (read-only) and emits the workflow changes, which Cerevisor applies exactly as a normal build. Trade-offs:

  • Slower and less precise. Complex multi-step builds occasionally need a follow-up message. A provider that can chat directly is still the smoother experience.
  • Uses your subscription quota. Every builder message is a full agent run.
  • Read-only. The builder can read your project for context but never modifies files while building.

Off by default — when off, you get the inline "pick a builder provider" panel instead.

Common errors

Error What it means Fix
"This copy of Cerevisor is missing the part that talks to Claude Code" A part of the app this needs did not load. Reinstall Cerevisor from cerevisor.com — your workflows and settings are kept. You are never asked to repair an installed app yourself.
The connection test fails on a Claude plan No valid Pro/Max sign-in was found. Press Sign in with Claude and finish the browser sign-in. A free Claude account has no agent quota and won't work.
"The key works, but Claude Code could not start on this computer" In API-key mode the key is fine, but Claude Code itself could not start here. The message names the reason. This test is one real question-and-answer, so a first start can take up to two minutes; the screen says so while it waits. It runs only when you press Test — opening a model list never starts one.
Runs work but show a cost in API-key mode you didn't expect You're in API-key mode (the default), billing per token. Edit the provider and switch the sign-in toggle to Claude subscription to bill against your Pro/Max plan instead.
A tool call fails with "Blocked by Cerevisor workflow permissions" Expected. Your workflow's permissions block that tool (see "How your workflow permissions apply" above). Loosen the relevant permission on the workflow if the agent genuinely needs it.

Where to go next

Back to docs