Configuration Reference

Settings Hierarchy

Whim uses a four-level settings system. Values at lower (more specific) levels override higher ones:

Platform defaults          ← built-in Whim defaults
  └─ Team defaults         ← set by team admins
      └─ Workspace defaults ← set by workspace admins
          └─ User defaults   ← set by individual users

In practice, Platform and Team defaults are rarely visible. The settings UI presents three editable levels: Workspace defaults, User defaults, and per-workspace User overrides.

Level	Who can edit	Scope
Platform	Whim (built-in)	All workspaces, all users
Team	Team owner / admin	All workspaces in the team
Workspace defaults	Team admin	All members of the workspace
User defaults	Any member	Only that user, across workspaces

Merge vs. Replace

Behavior	Settings
Merged (values from workspace + user combined)	Environment variables, MCP servers, Plugins, Skills
Concatenated (values are appended in source order)	Agent Instructions, Init script, Shell config (.bashrc)
Replaced (lower level wins)	Model, Permission mode, Reasoning effort, Auto-sleep, AI provider

Source Badges

Each setting displays a badge showing where its current value originates: Using workspace default, Using user default, Using custom, or Not configured. Click Override to create a workspace-specific value, or Clear Override to revert.

Opening Settings

Click the gear icon in the sidebar, or use the workspace header menu. The settings modal has four sections: Account, Configuration, Workspace, and Team.

Workspace Configuration

Workspace configuration controls the coding environment for every task. Managed in Settings → Configuration → Configurations.

MCP Servers

MCP servers extend your agent’s capabilities with external tools and data sources. Two transport types:Stdio — runs as a local process inside the task container:

{
  "name": "my-mcp-server",
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@example/mcp-server"],
  "env": { "API_KEY": "sk-..." }
}

HTTP — runs externally, accessed over HTTPS:

{
  "name": "remote-server",
  "type": "http",
  "url": "https://mcp.example.com/sse"
}

MCP servers use merge semantics. Servers from workspace and user levels are combined; same-name conflicts are resolved by source ordering.

Skills

Custom slash commands that the agent can invoke during a task (e.g., /deploy, /lint). Defined at workspace and user levels with merge semantics. See Skills & Slash Commands for details.

Environment Variables

Injected into every task container. Managed as env files — named groups of key-value pairs.

Secret detection — keys containing KEY, SECRET, TOKEN, PASSWORD are auto-masked in the UI.
Merge semantics — workspace and user env vars are merged. Source ordering controls priority.
Multiple env files let you organize by concern (e.g., api-keys, database, feature-flags).

Plugins

Pre-built integrations from the Claude marketplace. Toggled per workspace and per provider. Plugins use merge semantics. See Plugins for details.

Plugins are available for Claude. CCR support is coming soon. Not currently supported for Codex.

Scripts

Three types of scripts run at different points:

Agent Instructions — Markdown injected into the agent’s runtime instructions. Concatenated from workspace + user levels without creating repo files.
Initialization script (init.sh) — bash script that runs once when the container starts, before the agent begins. Concatenated from multiple levels.
Shell configuration (.bashrc) — loaded into each terminal session. Concatenated from multiple levels.

Auto-Sleep

Suspends idle task containers to conserve CUs. Options: Disabled, 1min, 5min, 10min, 15min (default), 30min, 1hr. The most specific level wins.

Provider Defaults

Configured per AI provider (Claude, Codex, CCR coming soon) in Settings → Configuration → Providers.

Model
Permission Mode
Fast Mode
Reasoning Effort (Codex)

Select the default AI model for tasks. Available models depend on the provider:

Claude — Claude model variants (Sonnet, Opus, etc.)
Codex — GPT model variants
CCR — models via OpenRouter

AI Provider Selection

Your default AI provider is a user-level setting:

Provider	Runtime	Description
Claude	Claude Code CLI	Anthropic’s native coding agent
Codex	Codex CLI	OpenAI’s native coding agent
CCR (Coming Soon)	Claude Code Runner	Claude models via OpenRouter API keys

User Preferences

Personal settings in the Account section that follow you across all workspaces.

Profile

Name — displayed to teammates in comments, assignments, and member lists. Auto-saves on blur.
Email — pulled from GitHub OAuth. Read-only.
GitHub Username — set during sign-up. Read-only in Whim.
Avatar — upload a custom photo (JPG, PNG, WebP, GIF, max 5 MB) with built-in cropping. Falls back to your GitHub avatar.

Theme

Light or Dark mode. Saved locally in your browser. Defaults to dark.

Notifications

Browser notifications for events when Whim isn’t in focus. Grant browser permission first, then toggle types:

Type	Fires when…
Claude waiting for input	Agent finishes and awaits your response
Comments on my tasks	Someone comments on your task
When I’m @mentioned	Someone mentions you with `@username`
Reactions to my comments	Someone reacts to your comment

Master toggle must be on for any individual notification to fire.

Layout preferences

Panel visibility (left sidebar, right detail panel) is saved per browser and restored on return.

User-level environment variables

Personal env vars applied across all workspaces. Merged with workspace-level vars. Common uses: personal API keys, tool config (EDITOR=vim), feature flags.

Env vars with secrets are masked in the UI but available in plaintext inside containers. Don’t share workspace access with untrusted users if your vars contain sensitive credentials.

Keyboard Shortcuts

On macOS use Cmd; on Windows/Linux use Ctrl.

Task creation

Shortcut	Action
`Cmd` + `Enter`	Submit prompt — create task or todo
`Tab`	Toggle between Task and Todo mode

Task and todo management

Shortcut	Action
`Cmd` + `.`	Toggle read mode (terminal ↔ conversation reader)
`Cmd` + `Enter`	Launch a todo
`Cmd` + `A`	Toggle assignee dropdown
`Escape`	Close dropdown or blur editor

Conversation reader

Shortcut	Action
`Cmd` + `F`	Open find bar
`Escape`	Close find bar
`Cmd` + `G` / `F3`	Next match
`Cmd` + `Shift` + `G` / `Shift` + `F3`	Previous match

Terminal

Shortcut	Action
`Ctrl` + `C`	Interrupt process
`Ctrl` + `Z`	Suspend foreground process
`Ctrl` + `L`	Clear screen
`Ctrl` + `D`	Send EOF
Up / Down	Navigate command history
`Tab`	Auto-complete

Comments & editors

Shortcut	Action
`Cmd` + `Enter`	Submit comment
`Shift` + `Enter`	Save config field

Mobile touch gestures

Swipe left on a task for quick actions (complete, archive, restore, delete).
When the terminal is active, a virtual key toolbar appears with Esc, Tab, arrow keys, Paste, Attach, and Enter.

Getting Started

Whim Agent

Tasks

AI Providers & Models

Workspaces

Git & Version Control

Terminal

Collaboration

Integrations

Configuration

Billing & Plans

Support

Configuration Reference

Settings Hierarchy

Merge vs. Replace

Source Badges

Opening Settings

Workspace Configuration

Provider Defaults

AI Provider Selection

User Preferences

Keyboard Shortcuts

​Settings Hierarchy

​Merge vs. Replace

​Source Badges

​Opening Settings

​Workspace Configuration

​Provider Defaults

​AI Provider Selection

​User Preferences

​Keyboard Shortcuts

Settings Hierarchy

Merge vs. Replace

Source Badges

Opening Settings

Workspace Configuration

Provider Defaults

AI Provider Selection

User Preferences

Keyboard Shortcuts