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

# Creating a Workspace

> Set up a new workspace connected to your GitHub repository.

A workspace is the top-level container where your team runs AI coding tasks. Each workspace is linked to one or more GitHub repositories and provides shared configuration, environment variables, and custom images for every task inside it.

## Prerequisites

* A Whim account (sign up with GitHub OAuth)
* A GitHub account with access to the repositories you want to connect
* Admin or owner role on your Whim team

## Create a workspace

<Steps>
  <Step title="Install the GitHub App">
    Whim needs the **Whim Orchestrator** GitHub App installed on your GitHub account or organization. If it's not installed yet, you'll be prompted to install it when you click **New Workspace**.

    You can grant access to all repositories or select specific ones — this is changeable later in your GitHub settings.
  </Step>

  <Step title="Select a repository">
    Once connected, Whim displays your accessible repositories. You can:

    * **Import existing repositories** — browse or search and select one or more. Repositories already connected to another workspace show a "Connected" badge.
    * **Create a new repository** — switch to the **Create New** tab to create a fresh GitHub repository directly from Whim.

    <Tip>
      You can connect multiple repositories to a single workspace using multi-select mode.
    </Tip>
  </Step>

  <Step title="Workspace creation">
    After selecting your repository, Whim automatically:

    1. Creates the workspace with a name and URL slug derived from your repository name
    2. Sets up a [Git mirror](/git/branch-isolation#mirroring-and-sync) so tasks can clone quickly
    3. Adds you as the first workspace member with admin privileges

    A progress indicator shows each stage.
  </Step>

  <Step title="Configure your AI provider">
    Choose from Claude, Codex, or OpenRouter and provide the required API key. You can also import your existing local configuration — see [Importing existing configuration](#importing-existing-configuration) below.
  </Step>

  <Step title="Enable notifications (optional)">
    Whim can send browser notifications when tasks need attention — for example, when an agent goes idle or someone comments on your task.
  </Step>
</Steps>

## Importing existing configuration

If you already have a local Claude Code setup with MCP servers, skills, environment variables, or other settings, you can import them into your workspace instead of re-creating everything.

### What gets imported

| Category                    | Source files                                                        |
| --------------------------- | ------------------------------------------------------------------- |
| **MCP Servers**             | `.mcp.json`, `settings.json`                                        |
| **Skills**                  | `.claude/skills/*/SKILL.md`                                         |
| **Commands**                | `.claude/commands/*.md` (imported as skills)                        |
| **Plugins**                 | `settings.json`                                                     |
| **Model & Permission Mode** | `settings.json`                                                     |
| **Agent Instructions**      | `CLAUDE.md`, `~/.claude/CLAUDE.md` imported as runtime instructions |
| **Environment Variables**   | `.env`, `.env.*` files                                              |
| **Shell Configuration**     | `~/.bashrc`, `~/.zshrc`                                             |

### How it works

<Steps>
  <Step title="Generate an import token">
    From workspace settings or during onboarding, Whim generates a short-lived import token (valid for 1 hour).
  </Step>

  <Step title="Run the import agent">
    Copy the provided prompt and paste it into your local Claude Code terminal. The agent reads your local configuration and identifies what can be imported.
  </Step>

  <Step title="Review and approve">
    The agent asks about each category individually — nothing is imported without your approval.
  </Step>

  <Step title="Configuration applied">
    Approved settings are saved to your **workspace user overrides** (your personal settings for this workspace). You can later promote them to workspace defaults or user defaults from the settings UI.
  </Step>
</Steps>

<Note>
  Import tokens are single-use, expire after 1 hour, and are scoped to a specific workspace and user. Each new token invalidates any previous unused token.
</Note>

If you already have settings in Whim, imported values use merge semantics — they're applied on top of existing ones. For key-value settings like env vars, imported values override matching keys. For collections like MCP servers, imported items are added alongside existing ones.

## What happens behind the scenes

When you create a workspace, Whim:

* **Generates a unique slug** for your workspace URL (e.g., `my-repo`). If the slug is taken, a numeric suffix is appended.
* **Links your repositories** and triggers an initial Git mirror sync.
* **Sets up defaults** — the workspace inherits your team's default AI provider and model settings, which you can customize in [Settings and Environment](/workspaces/settings-and-environment).

## Next steps

<CardGroup cols={2}>
  <Card title="Settings & Environment" icon="gear" href="/workspaces/settings-and-environment">
    Configure workspace defaults, member settings, and environment variables.
  </Card>

  <Card title="Workspace Images" icon="docker" href="/workspaces/workspace-images">
    Build custom Docker images with your project's dependencies pre-installed.
  </Card>

  <Card title="Creating Tasks" icon="play" href="/tasks/creating-and-running">
    Launch your first AI coding task in the workspace.
  </Card>
</CardGroup>