Agent preferences

Set per-workspace default agents and per-project overrides. Configure agent-specific behavior.

Default agent selections are configurable at three levels: workspace, project, and per-prompt. Defaults cascade — a workspace default applies unless a project overrides; a project default applies unless a per-prompt override picks something else.

Where to set defaults

Per-workspace

Workspace settings → Preferences → Default agent. Applies to every project in the workspace.

Per-project

Project settings → Preferences → Default agent. Overrides workspace default.

Per-prompt

The agent dropdown next to the prompt input. Overrides project default for that prompt only.

Recommended starting setup

For most users:

• Workspace default: Claude Code
• Project defaults: don’t override unless a project consistently benefits from a different agent
• Per-prompt: override to OpenAI Codex for tight changes, Gemini CLI for design

Other agent settings

Beyond default selection:

Setting	Default	What it does
Default mode	Plan	Whether new prompts open in Agent or Plan mode
Auto-retry on type errors	On	If the build fails type-check, the agent retries up to 3 times
Max credits per prompt	Unlimited	Cap individual prompt cost (useful for budget control)
Custom instructions	(none)	See Custom instructions
Knowledge base	(project-scoped)	See Knowledge base

Related

Choosing an agent

Decision tree.

Custom instructions

Always-on rules.

Fallback behavior

Agent-unavailable handling.