---
title: Authentication
description: How Claudette delegates Claude authentication to the official CLI and what that means for Pro/Max plans, API keys, and stored credentials.
---

Claudette **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 Claudette does and doesn't touch your credentials

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

- Claudette does **not** read or forward your Claude OAuth tokens to spawned agent subprocesses.
- Claudette **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, Claudette 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 Claudette, Claudette picks it up automatically the next time it spawns an agent (and the next time the Usage panel refreshes).

## Signing in from inside Claudette

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 Claudette 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, Codex models launch `codex login`, and Pi models show Pi auth guidance so you can run `pi auth` in a terminal. 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 Claudette triggers the Claude Code sign-in flow, the CLI:

1. Starts a localhost HTTP listener.
2. Opens your browser to the OAuth URL.
3. Captures the authorization code via the local callback, or asks you to paste the browser code into Claudette when Claude Code prompts for manual entry.
4. 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, Claudette's spawned agents use that authentication. Token usage shows up under your Anthropic account at [claude.ai/settings/usage](https://claude.ai/settings/usage), and the **Settings > Usage** panel inside Claudette can deep-link there when Usage Insights is enabled.

### Parallel agents and your plan

Per the [Claude Code legal and compliance page](https://code.claude.com/docs/en/legal-and-compliance):

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

Claudette 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; Claudette 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](https://platform.claude.com/), which is governed by Anthropic's [Commercial Terms](https://www.anthropic.com/legal/commercial-terms).

## API keys

To use an API key instead of (or alongside) OAuth, follow the official Claude Code setup — Claudette will pick up whatever credentials the CLI is configured with. There's no Claudette-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.). Claudette 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 Claudette's plugin code. The two namespaces are isolated by key prefix.

## Agent providers

Claudette supports running an agent against [agent providers](/claudette/features/providers/) (Ollama, LM Studio, OpenAI, Codex, Pi) via **Settings > Models**. Each provider has its own credential expectations — see the per-provider docs. Pi credentials and provider config stay under Pi's auth/config system and are refreshed with `pi auth`; Claudette uses its bundled Pi SDK sidecar to discover models, run Pi turns, and execute Claudette-mediated custom tools. The Anthropic Pro/Max OAuth flow described above only applies when the active provider is the official `claude` CLI.

## Signing out

To sign out, run `claude auth logout` in a terminal — Claudette 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 Claudette spawns an agent, you'll be prompted to sign in again.

## See also

- [Usage & Metrics](/claudette/features/usage-and-metrics/) — viewing your token consumption and quota
- [Privacy](/claudette/privacy/) — what Claudette stores locally and what flows over the network
- [Relationship to Anthropic](https://github.com/utensils/Claudette#relationship-to-anthropic) — context on Claudette's independence
