> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whim.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Reference

> Complete reference for settings hierarchy, workspace config, user preferences, and keyboard shortcuts.

## 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
```

<Note>
  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.
</Note>

| 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**.

<AccordionGroup>
  <Accordion title="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:

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

    **HTTP** — runs externally, accessed over HTTPS:

    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="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](/integrations/github-skills-and-plugins#skills--slash-commands) for details.
  </Accordion>

  <Accordion title="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`).
  </Accordion>

  <Accordion title="Plugins">
    Pre-built integrations from the Claude marketplace. Toggled per workspace and per provider. Plugins use merge semantics. See [Plugins](/integrations/github-skills-and-plugins#plugins) for details.

    <Note>Plugins are available for Claude. CCR support is coming soon. Not currently supported for Codex.</Note>
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Auto-Sleep">
    Suspends idle task containers to conserve CUs. Options: Disabled, 1min, 5min, 10min, **15min (default)**, 30min, 1hr. The most specific level wins.
  </Accordion>
</AccordionGroup>

### Provider Defaults

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

<Tabs>
  <Tab title="Model">
    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
  </Tab>

  <Tab title="Permission Mode">
    **Claude / CCR:** Default, Plan Mode, Accept Edits, Bypass Permissions

    **Codex:** Default, Untrusted, On Request, Never Ask, Danger Full Access

    <Note>CCR is currently disabled for alpha users. Its permission modes are listed here for forward compatibility.</Note>

    <Warning>Bypass Permissions and Danger Full Access disable safety checks. Use only when you understand the risks.</Warning>
  </Tab>

  <Tab title="Fast Mode">
    Prioritizes output speed over reasoning depth. Availability depends on the selected model.
  </Tab>

  <Tab title="Reasoning Effort (Codex)">
    Controls depth of reasoning: Default, Low, Medium, High, XHigh.
  </Tab>
</Tabs>

### 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.

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Theme">
    **Light** or **Dark** mode. Saved locally in your browser. Defaults to dark.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Layout preferences">
    Panel visibility (left sidebar, right detail panel) is saved per browser and restored on return.
  </Accordion>

  <Accordion title="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.

    <Warning>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.</Warning>
  </Accordion>
</AccordionGroup>

***

## Keyboard Shortcuts

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

<AccordionGroup>
  <Accordion title="Task creation">
    | Shortcut                          | Action                              |
    | --------------------------------- | ----------------------------------- |
    | <kbd>Cmd</kbd> + <kbd>Enter</kbd> | Submit prompt — create task or todo |
    | <kbd>Tab</kbd>                    | Toggle between Task and Todo mode   |
  </Accordion>

  <Accordion title="Task and todo management">
    | Shortcut                          | Action                                            |
    | --------------------------------- | ------------------------------------------------- |
    | <kbd>Cmd</kbd> + <kbd>.</kbd>     | Toggle read mode (terminal ↔ conversation reader) |
    | <kbd>Cmd</kbd> + <kbd>Enter</kbd> | Launch a todo                                     |
    | <kbd>Cmd</kbd> + <kbd>A</kbd>     | Toggle assignee dropdown                          |
    | <kbd>Escape</kbd>                 | Close dropdown or blur editor                     |
  </Accordion>

  <Accordion title="Conversation reader">
    | Shortcut                                                                            | Action         |
    | ----------------------------------------------------------------------------------- | -------------- |
    | <kbd>Cmd</kbd> + <kbd>F</kbd>                                                       | Open find bar  |
    | <kbd>Escape</kbd>                                                                   | Close find bar |
    | <kbd>Cmd</kbd> + <kbd>G</kbd> / <kbd>F3</kbd>                                       | Next match     |
    | <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>G</kbd> / <kbd>Shift</kbd> + <kbd>F3</kbd> | Previous match |
  </Accordion>

  <Accordion title="Terminal">
    | Shortcut                       | Action                     |
    | ------------------------------ | -------------------------- |
    | <kbd>Ctrl</kbd> + <kbd>C</kbd> | Interrupt process          |
    | <kbd>Ctrl</kbd> + <kbd>Z</kbd> | Suspend foreground process |
    | <kbd>Ctrl</kbd> + <kbd>L</kbd> | Clear screen               |
    | <kbd>Ctrl</kbd> + <kbd>D</kbd> | Send EOF                   |
    | Up / Down                      | Navigate command history   |
    | <kbd>Tab</kbd>                 | Auto-complete              |
  </Accordion>

  <Accordion title="Comments & editors">
    | Shortcut                            | Action            |
    | ----------------------------------- | ----------------- |
    | <kbd>Cmd</kbd> + <kbd>Enter</kbd>   | Submit comment    |
    | <kbd>Shift</kbd> + <kbd>Enter</kbd> | Save config field |
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>