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

# Quickstart: your codebase on the canvas

> Go from a folder of your team's code to your app running on the Onlook canvas, with one change made by the agent.

By the end of this page, your team's app will be running on the Onlook canvas, and the agent will have made one change you asked for.

**Before you start,** [install Onlook](/start/install) and sign in. You also need a folder on your Mac with your app's code. To send changes back as a pull request later, use a clone of your team's GitHub repository. If you don't have one, ask an engineer for a copy that runs with the project's normal dev command.

<Steps>
  <Step title="Connect your AI">
    On **Explore more ideas, faster**, choose **Set up Claude** or **Set up ChatGPT** and follow the steps until the tile says **Connected**. Then choose **Continue**.

    For help with this step, see [Connect your AI](/setup/ai).
  </Step>

  <Step title="Choose your codebase">
    On **Create your first workspace**, choose **Choose a codebase folder**. Pick the folder with your app's code and choose **Use this folder**.

    Onlook works on its own copy of the folder. Your files aren't changed, and nothing is uploaded. See [How Onlook keeps your code safe](/start/trust).
  </Step>

  <Step title="Let Onlook set up your app">
    The editor opens, and the chat narrates each step: **Reading**, **Making a copy of**, **Installing dependencies for**, **Starting**. The first message tells you the name of your copy and the branch Onlook made for it.

    Onlook installs your app and starts it for you. When your app answers, a frame on the canvas shows it.

    If a frame says **Press Start to run this app**, press **Start** in the toolbar at the bottom of the canvas.

    If your code holds more than one app, or something else is using its port, the agent asks which to use. Answer in the chat.
  </Step>

  <Step title="Ask for one visible change">
    In the chat box (**Ask for a change…**), ask for something you'll be able to spot. For example: "Make the main heading on the home page say Hello from Onlook." Press Return.

    To point at something specific, click it in the frame first, then ask in the box that appears beside it.

    Before your first change, the agent gives the project a short name. Your project, its tab and its branch take that name.
  </Step>

  <Step title="See the change">
    Each thing the agent does appears in the chat as a row: **Reading**, **Editing**, **Running**. When it's finished, the chat says **Done — look at** and names the frame, and that frame shimmers.

    Most apps update on their own. If yours doesn't, open the frame's menu and choose **Reload**.

    To click through your app like a visitor, switch to **Preview** (press **P**). To go back to selecting and editing, switch to **Design** (press **D**).
  </Step>
</Steps>

## What just happened

The agent changed the code in Onlook's copy, on its own branch. Your folder and your team's repository haven't changed.

When you're ready to share the change, look at the pill in the top bar. It shows the next step, such as **Create PR**. See [Send your work to engineers](/handoff/the-git-status-pill).

## Learn what else you can ask for

To see what Onlook can do, click **Tips** in the lower-left corner of the editor, or press **⌘/**. Tips shows examples you can try, like making variations, opening every page of your app, or matching a screenshot. Choose one, then **Try it in chat** to put it in your chat box. See [Tips](/start/tips).

## If something went wrong

* **Onlook refused the folder.** The dialog says why. See [Troubleshooting](/help/troubleshooting#connecting-a-folder).
* **macOS asked to install developer tools.** Choose **Install**, then **Retry**. See [Install Onlook](/start/install#when-macos-asks-to-install-developer-tools).
* **Setup stopped at a step.** The message in the chat names the step, and **Retry** repeats it. See [Troubleshooting](/help/troubleshooting#creating-a-project).
* **The frame shows a message instead of your app.** See [Troubleshooting](/help/troubleshooting#frames).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.