Authentication

Workbench does not authenticate to Anthropic on your behalf for agent runs. It spawns the official claude CLI you have installed locally as a subprocess; the CLI authenticates itself using credentials you’ve already configured. This is intentional: a tool that orchestrates Claude Code shouldn’t have to be trusted with the tokens that drive agent traffic.

Where Workbench does and doesn’t touch your credentials

For agent traffic — the bulk of what Workbench does — credentials are off-limits:

Workbench does not read or forward your Claude OAuth tokens to spawned agent subprocesses.
Workbench strips inherited subscription tokens from spawned subprocess environments so they can’t leak into the agent.
Your Claude Code credentials live where the official CLI puts them: macOS Keychain entry Claude Code-credentials, or ~/.claude/.credentials.json on Linux.

There is one exception: the Usage panel. To surface your subscription type, rate-limit tier, and current consumption, Workbench reads the OAuth tokens from the keychain / credentials file, refreshes them when expired, and calls Anthropic’s usage API directly. Tokens never leave the local process boundary except as the standard Authorization header on those requests. If you don’t open the Usage panel, this code path never runs.

If you sign in or out of Claude Code outside Workbench, Workbench picks it up automatically the next time it spawns an agent (and the next time the Usage panel refreshes).

Signing in from inside Workbench

The Settings > Models > Claude Code row checks claude auth status --json with the same resolved Claude binary and sanitized subprocess environment used for agent runs, then triggers claude auth login from inside Workbench when you need to sign in again. You can also run /login in chat to start the sign-in flow for the active model provider without opening settings: Claude models open the same Claude Code browser/manual-code controls, and Codex models launch codex login. The row’s refresh button performs a small authenticated Claude CLI validation request, so it can catch a revoked token that still exists locally. Chat auth failures route you to that row and carry the latest failure message with them, so a revoked token or 401 stays visible even if the CLI still has local credentials. Usage-panel credential failures reuse the same sign-in flow, so sign-in is available even when Usage Insights is disabled. There is no automatic workspace-creation login flow; if you create a workspace before signing in, the agent’s first turn shows a credentials callout and you’ll need to authenticate via Settings > Models, /login in chat, or claude auth login in any terminal.

When Workbench triggers the Claude Code sign-in flow, the CLI:

Starts a localhost HTTP listener.
Opens your browser to the OAuth URL.
Captures the authorization code via the local callback, or asks you to paste the browser code into Workbench when Claude Code prompts for manual entry.
Writes the resulting credentials to the keychain (or .credentials.json on Linux).

Two events stream from the Tauri backend to the Claude Code sign-in panel while this runs:

auth://login-progress — one entry per line of stdout/stderr from the CLI subprocess.
auth://login-complete — fired once when the process exits, indicating success or the error message.

Cancel via the in-panel cancel button (kills the subprocess) or by closing the browser tab; the panel surfaces the error and you can retry.

Pro and Max plans (OAuth)

If you’ve authenticated claude with a Pro or Max subscription, Workbench’s spawned agents use that authentication. Token usage shows up under your Anthropic account at claude.ai/settings/usage, and the Settings > Usage panel inside Workbench can deep-link there when Usage Insights is enabled.

Parallel agents and your plan

Per the Claude Code legal and compliance page:

Advertised usage limits for Pro and Max plans assume ordinary, individual usage of Claude Code and the Agent SDK.

Workbench can run multiple agents in parallel git worktrees. We recommend keeping default parallelism low (1–3 simultaneous agents) and treating heavier use as something you explicitly opt into. Whether running N parallel agents counts as “ordinary, individual usage” under your plan is a judgment Anthropic reserves for itself; Workbench is the affordance, but the responsibility for staying within your plan’s terms is yours.

If you need higher throughput, the supported path is API-key authentication via Claude Console, which is governed by Anthropic’s Commercial Terms.

API keys

To use an API key instead of (or alongside) OAuth, follow the official Claude Code setup — Workbench will pick up whatever credentials the CLI is configured with. There’s no Workbench-specific API-key configuration to set.

Plugin secrets

Claude Code plugins may require their own secrets (API keys, OAuth tokens for third-party services, etc.). Workbench stores these in the same secure-storage object Claude Code itself uses — the macOS Keychain entry Claude Code-credentials or ~/.claude/.credentials.json on Linux — but only under its own pluginSecrets namespace.

Your Claude OAuth tokens (claudeAiOauth.*) are never read or written by Workbench’s plugin code. The two namespaces are isolated by key prefix.

Agent providers

Workbench supports running an agent against agent providers (Ollama, OpenAI, Codex) via Settings > Models. Each provider has its own credential expectations — see the per-provider docs. The Anthropic Pro/Max OAuth flow described above only applies when the active provider is the official claude CLI.

Auth broker

When you run multiple workspaces in parallel, a single expired token can cascade into sign-in prompts across every active session. Workbench’s auth broker centralizes OAuth token recovery: when one session successfully re-authenticates, the broker propagates the refreshed token to all other sessions that were blocked on the same credential failure. You don’t need to sign in once per workspace — one sign-in unblocks them all.

The broker operates entirely within the local Workbench process; tokens are never forwarded to any external service beyond the standard Anthropic OAuth exchange.

Auto-resume after auth recovery

When a turn fails mid-flight because of an expired or revoked token, Workbench holds the failed turn in a pending state rather than discarding it. After you re-authenticate — either through the sign-in modal, Settings > Models, or /login — the interrupted turn automatically resumes from where it left off. No need to retype or resubmit your message.

Proactive auth health check

When Workbench has been idle for a configurable period (default: 4 hours), it begins periodic background checks of your Claude authentication status. If your token has expired during inactivity, a modal appears prompting you to sign in before you start working — preventing failed requests across multiple workspaces.

The inactivity threshold is configurable in Settings > General > Auth health check after inactivity. Set it to “Disabled” to turn off proactive checks.

Dismissing the modal hides it temporarily. If auth is still expired at the next check interval (5 minutes), it will reappear. Re-authenticating through Settings clears the warning and resumes any pending requests that failed due to the expired token.

Signing out

To sign out, run claude auth logout in a terminal — Workbench has no separate sign-out UI because it would only duplicate what the CLI already does. Signing out invalidates the credentials on disk; the next time Workbench spawns an agent, you’ll be prompted to sign in again.