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

# Quickstart

> Go from sign-up to your first running task in under 5 minutes.

This guide walks you through creating your first AI coding task on Whim, explaining the key concepts as you go.

<Info>
  **Prerequisites:** A GitHub account and a repository you want to work on.
</Info>

## 1. Sign up with GitHub

Go to [whim.run](https://www.whim.run) and click **Start Building**. Sign in with GitHub — no credit card required.

After signing in, you'll fill out a short profile (name, email, role) so Whim can tailor your experience.

## 2. Install the GitHub App

Whim uses a GitHub App to clone and push to your repositories.

<Steps>
  <Step title="Click Install GitHub App">
    You'll be redirected to GitHub to authorize the app.
  </Step>

  <Step title="Choose repositories">
    Grant access to all repos or pick specific ones.
  </Step>

  <Step title="Confirm installation">
    GitHub redirects you back to Whim. Done.
  </Step>
</Steps>

<Tip>
  If your organization already has the Whim GitHub App installed, this step is skipped automatically.
</Tip>

## 3. Create a workspace

A **workspace** is your project home in Whim — it maps to a GitHub repository. Pick the repo you want to work on from your list of available repositories.

Whim creates the workspace and syncs your code. You can also create a brand-new GitHub repo from this screen if you're starting fresh.

<Note>
  You can have multiple workspaces, each linked to a different repo. Switch between them from the workspace selector.
</Note>

## 4. Choose your AI provider

Whim supports multiple **AI providers**, each running their native CLI inside task containers:

| Provider               | Description                                                                                                      |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Claude** (Anthropic) | Native Claude Code CLI. Use Whim's built-in compute or bring your own Claude Pro/Team subscription.              |
| **Codex** (OpenAI)     | Native Codex CLI. Requires your own OpenAI API key.                                                              |
| **OpenRouter**         | Access 10+ models (GPT, Gemini, Grok, DeepSeek, and more) through a single API key. Coming soon for alpha users. |

<Note>
  OpenRouter/CCR is coming soon for alpha users. Today, Whim supports Claude and Codex.
</Note>

Connect Claude or Codex by entering an API key or linking your subscription. You can add more providers later from workspace settings.

### Configure your workspace

After choosing a provider, you can optionally configure:

<AccordionGroup>
  <Accordion title="Model and permissions">
    Pick a default model (e.g., Claude Opus, Sonnet, GPT-4o) and set the agent's permission mode — how much autonomy it has over file edits and shell commands.
  </Accordion>

  <Accordion title="Instructions">
    Write agent instructions that every task in this workspace will receive — coding standards, project context, or architectural guidelines.
  </Accordion>

  <Accordion title="Environment variables, MCP servers, skills, and more">
    Inject env vars, connect MCP servers for external tools, define reusable skills (slash commands), add plugins, and set init scripts. All optional — you can configure these later.
  </Accordion>
</AccordionGroup>

<Tip>
  Already have Claude Code or Codex configured locally? You can **import your local setup** instead of configuring manually.
</Tip>

## 5. Launch your first task

Now for the exciting part. A **task** is a single AI agent session running in its own isolated cloud container.

<Steps>
  <Step title="Write your prompt">
    Describe what you want the AI agent to do. Be specific: "Add a dark mode toggle to the settings page" works better than "improve the UI."
  </Step>

  <Step title="Pick a model">
    Choose the AI model for this task (e.g., Claude Opus, Claude Sonnet, GPT-4o).
  </Step>

  <Step title="Launch">
    Click **Create Task**. Whim spins up an isolated container, clones your repo, checks out a fresh branch, and starts the AI agent with your prompt.
  </Step>
</Steps>

### What just happened?

Behind the scenes, Whim:

1. **Provisioned a container** — a sandboxed Ubuntu environment on Fly.io, dedicated to this task
2. **Cloned your repo** and checked out a new branch (named `whim-<workspace>-<task-id>`)
3. **Injected your configuration** — instructions, env vars, MCP servers, skills, and plugins
4. **Started the AI agent** (Claude Code or Codex) with your prompt
5. **Began streaming** the agent's terminal output to your browser in real time

Each task gets its own **git branch** automatically, so multiple tasks can work on the same repo without conflicts.

## 6. Watch it work

Once launched, you'll see the agent's terminal streaming live. You can:

* **Watch the terminal** — see every command and file edit as it happens
* **Open additional panes** — add a shell terminal, file browser, or live preview
* **Send follow-up prompts** — guide the agent if it needs course correction

## 7. Review the results

When the agent finishes, you'll have:

* **A git branch** with all the changes, ready for review
* **A pull request** (if the agent created one) linked from the task
* **Full conversation history** showing the agent's reasoning and every action

From here you can merge the PR, fork the task to try a different approach, or launch a new task.

## Key concepts recap

| Concept                 | What it is                                                                                                                  |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Workspace**           | Your project home — linked to a GitHub repo. Contains all tasks, config, and team collaboration.                            |
| **Task**                | A single AI agent session in its own isolated container with its own git branch.                                            |
| **Todo**                | A planned task in your backlog. Doesn't run until you launch it — useful for queuing work.                                  |
| **Provider**            | The AI runtime powering your agents (Claude or Codex today; OpenRouter coming soon).                                        |
| **Compute Units (CUs)** | How Whim measures usage — a blend of container runtime and AI token consumption. Your plan includes a weekly CU allocation. |

### Task states

Tasks move through a simple lifecycle:

| State         | What's happening                                                   |
| ------------- | ------------------------------------------------------------------ |
| **Running**   | The agent is actively working.                                     |
| **Waiting**   | The container is up but the agent is idle or needs input.          |
| **Sleeping**  | Container suspended to save CUs. Resumes instantly on interaction. |
| **Completed** | Work is done. Branch and results are preserved.                    |

<CardGroup cols={2}>
  <Card title="How Agents Work" icon="microchip" href="/whim-agent/how-agents-work">
    Deep dive into what runs inside a task container.
  </Card>

  <Card title="Orchestrator Mode" icon="sitemap" href="/whim-agent/orchestrator-mode">
    Coordinate multiple agents on complex tasks.
  </Card>
</CardGroup>