---
title: "Get started"
description: "Open a folder, connect a model and send your first message in the Codewhale desktop app."
works_on: [desktop]
---

# Get started

Open a folder, connect a model and get your first answer in under a minute.

**Works on:** the desktop app. Web: not available yet. Phone: see [On your phone](#on-your-phone).

## Choose a folder

The first time you open Codewhale, the whale rests in the middle of the
window and says "Pick a folder and I'll get to work."

1. Press **Choose folder**, or use **File › Open folder…** (⌘O, Ctrl+O on
   Windows and Linux).
2. Pick the project you want to work in.

Codewhale opens the same folder next time. The line under the heading shows
the folder and its branch, for example "codewhale · main".

## Trust the folder

The first time you open a folder, Codewhale asks "Can I work with the files
in this folder?"

- **Trust folder** lets the folder's own commands and tools run.
- **Not now** keeps them off for now. Codewhale asks again the next time
  you open the folder.

Trust only folders you know. Files in a folder can try to tell the whale
what to do.

## Connect a model

If no model is connected yet, the whale says "Connect a model to start."
Press **Connect a model**, choose a provider and do the one step it asks for.
The heading changes to "What should we work on?"

[Connect a model](models.md) has every step and what to do if a key doesn't
work.

## Send your first message

Type in the composer and press Enter. Or press a starter to fill the
composer first:

- Fix a failing test
- Explain this codebase
- Review my changes
- Write release notes

The reply streams in as the whale writes it. See
[The conversation](conversation.md) for what you can do while it works.

## What's next

A short list under the composer ticks itself off as you go:

| Item | Ticks when |
| --- | --- |
| Connect a model | a model is connected |
| Send a first message | you have a conversation |
| Review a change | you open a change in Review |
| Try a / command | never; pressing it puts / in the composer and opens the command list |

Once the first three are ticked, the list goes away.

## Anonymous usage counts

The first time, a card says what Codewhale counts: "Codewhale counts which
version you run, how long sessions last, and which features and tools get
used. Never your conversations, code, prompts or files." Counting is on.

The card's **Share usage counts** switch, and the **Anonymous usage counts**
row in **Settings › Trust**, say "Not available yet": you can't turn counting off in
the app yet. If you also use Codewhale in a terminal, this turns it off:

```sh
codewhale config set telemetry false
```

Press × to close the card. It doesn't come back.

## If something goes wrong

| What you see | What to do |
| --- | --- |
| "Codewhale can't open this folder." | Codewhale couldn't start working in this folder. The reason shows under the heading. Press **Choose another folder**, or see [Troubleshooting](troubleshooting.md#codewhale-cant-open-this-folder). |
| "That key didn't work. Check it and paste it again." | Copy the key again and paste it. See [Connect a model](models.md#if-the-key-doesnt-work). |
| "Reconnecting" under the composer | Codewhale is starting again by itself. See [Troubleshooting](troubleshooting.md#reconnecting-under-the-composer). |

## On the web

Not available yet.

## On your phone

The phone app starts from your conversation list, not from a folder: sign in
and pick a conversation, or start a new one. See [Codewhale on your
phone](phone.md) and [Sign in](sign-in.md).

## Related

- [Connect a model](models.md)
- [The conversation](conversation.md)
- [Approvals and permissions](approvals-and-permissions.md)
- [Troubleshooting](troubleshooting.md)

Next: [Sign in](sign-in.md)