Skip to main content

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.

This guide walks you through creating your first AI coding task on Whim, explaining the key concepts as you go.
Prerequisites: A GitHub account and a repository you want to work on.

​
1. Sign up with GitHub

Go to 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.
1

Click Install GitHub App

You’ll be redirected to GitHub to authorize the app.
2

Choose repositories

Grant access to all repos or pick specific ones.
3

Confirm installation

GitHub redirects you back to Whim. Done.
If your organization already has the Whim GitHub App installed, this step is skipped automatically.

​
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.
You can have multiple workspaces, each linked to a different repo. Switch between them from the workspace selector.

​
4. Choose your AI provider

Whim supports multiple AI providers, each running their native CLI inside task containers:
ProviderDescription
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.
OpenRouterAccess 10+ models (GPT, Gemini, Grok, DeepSeek, and more) through a single API key. Coming soon for alpha users.
OpenRouter/CCR is coming soon for alpha users. Today, Whim supports Claude and Codex.
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:
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.
Write agent instructions that every task in this workspace will receive — coding standards, project context, or architectural guidelines.
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.
Already have Claude Code or Codex configured locally? You can import your local setup instead of configuring manually.

​
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.
1

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.”
2

Pick a model

Choose the AI model for this task (e.g., Claude Opus, Claude Sonnet, GPT-4o).
3

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.

​
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

ConceptWhat it is
WorkspaceYour project home — linked to a GitHub repo. Contains all tasks, config, and team collaboration.
TaskA single AI agent session in its own isolated container with its own git branch.
TodoA planned task in your backlog. Doesn’t run until you launch it — useful for queuing work.
ProviderThe 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:
StateWhat’s happening
RunningThe agent is actively working.
WaitingThe container is up but the agent is idle or needs input.
SleepingContainer suspended to save CUs. Resumes instantly on interaction.
CompletedWork is done. Branch and results are preserved.

How Agents Work

Deep dive into what runs inside a task container.

Orchestrator Mode

Coordinate multiple agents on complex tasks.