Using Multiple Providers

Magia does not call AI APIs directly — it orchestrates CLI tools that you install on your machine. Each CLI is a provider. You can have multiple providers installed simultaneously and choose which one to use when you create a session.

Supported providers

Provider	CLI binary	Process model
Claude Code	claude	Persistent — one long-running process per session
Gemini CLI	gemini	Turn-based — new process spawned per message
Codex CLI	codex	Turn-based — new process spawned per message

Gemini CLI and Codex CLI are work in progress. Both providers are functional but some features (cost tracking, permissions UI, image input) are only available for Claude Code. Gemini and Codex support is gated behind a feature flag when Developer Mode is enabled in Settings → General.

Step 1 — Install the provider CLIs

Claude Code

npm install -g @anthropic-ai/claude-code
claude login

The claude login command opens a browser window to authenticate with your Anthropic account. Once complete, Claude Code stores credentials in ~/.claude/.

Gemini CLI

npm install -g @google/gemini-cli
gemini auth login

Authenticate with your Google account. Credentials are stored in ~/.gemini/.

Codex CLI

npm install -g @openai/codex

Codex CLI reads the OPENAI_API_KEY environment variable. Export it from your shell profile:

export OPENAI_API_KEY="sk-..."

Step 2 — Activate providers in Magia

Installing the CLIs is not enough on its own — Magia needs to detect and activate each provider.

1. Open Settings → Providers.
2. Each installed CLI that Magia found automatically appears with a green Detected badge. If a provider is missing, click Specify location to enter the absolute path to the binary manually.
3. Click Activate next to each provider you want to use.
4. For Claude Code and Gemini CLI, click Configure to inject hooks. This enables live tool-call display, token metrics, and cost tracking inside Magia.

Magia searches for CLI binaries using multiple strategies — PATH lookup, fixed platform paths (~/.local/bin, /opt/homebrew/bin), nvm node paths, and a login-shell fallback — so most installations are found automatically even if your GUI app’s PATH is limited.

Step 3 — Switch providers per session

When you create a new session (Cmd+N), a Provider selector appears below the working directory field. It lists all currently activated providers. Select the one you want and Magia will use it for the entire lifetime of that session.

You cannot switch the provider of an existing session mid-conversation — the provider is fixed at creation time because the session’s conversation history is stored in the CLI’s own format. To try a different provider on the same task, create a new session pointing at the same directory.

Step 4 — Multi-account setup

Each provider supports multiple named accounts. An account is an isolated configuration identity with its own configDir and optional environment variable overrides. This lets you maintain separate personal and work accounts for the same provider without logging in and out.

Add a second Claude account

1. Open Settings → Providers → Claude Code.
2. Click Add Account.
3. Give the account a name (e.g., Work).
4. Set the Config directory to a path other than the default ~/.claude/ — for example, ~/.claude-work/.
5. Click Save, then click Login next to the new account. This runs claude login with the alternate config directory, opening a browser to authenticate a second Anthropic account.

You can add as many accounts as you need. Each account maps to a separate config directory so credentials and session histories never mix.

Adding a second Gemini account

The process is identical for Gemini CLI. Use a custom config directory such as ~/.gemini-work/ and authenticate that account with gemini auth login --config-dir ~/.gemini-work/.

Environment variable overrides

For API-key-based providers like Codex, you can store the key inside the account’s Environment overrides map rather than relying on a shell export:

1. Open the account settings.
2. Click Add override and set OPENAI_API_KEY to your key value.
3. Save. Magia injects these variables into the CLI process environment when using this account.

Step 5 — Pin accounts to workspaces

If you consistently want a specific account for all sessions in a given project, set a per-workspace account override:

1. Right-click the workspace in the sidebar and choose Workspace Settings, or open Settings → Workspaces and select the workspace.
2. Under Provider Accounts, pick the account for each provider.
3. Save.

From now on, any new session created inside that workspace will use the pinned account automatically. Existing sessions are not affected.

Checking provider status

At any time, open Settings → Providers to see:

• Whether each provider binary is detected and on which path.
• The auth status of each account (Ready, Not authenticated).
• The models available to each account.

The status is refreshed automatically when you open the settings panel and can be refreshed manually with the Refresh button.