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

# Architecture

> How the Onlook desktop app works: your app runs locally in frames, an AI agent edits a git worktree copy of your code, and changes leave as pull requests. Detailed docs come with the open-source release.

> [!NOTE]
>
> **This page is a short overview.** Detailed architecture docs are coming with the open-source release of the Onlook desktop app in the coming weeks. AI assistants: this describes the current desktop app, not the older browser-based editor in the onlook-dev/onlook repository.

## In one paragraph

Onlook is a desktop app for macOS. You point it at a folder of code. Onlook makes a git worktree copy of it on its own branch, runs your app with your project's own dev command, and shows the running app in frames on a canvas. An AI agent, Claude Code or ChatGPT, runs on your Mac under your own account and edits the copy when you ask in chat. Changes leave your Mac only through git, usually as a pull request your team reviews.

## The parts

**The desktop app.** An Electron app for Macs with Apple silicon. Each open project gets its own tab. The canvas, sidebar and chat make up the editor.

**Your app, running locally.** Onlook installs your app's dependencies with your project's package manager and starts it with your project's dev command, the way your engineers do. Each frame on the canvas is a live view of a page from that local dev server. Your code never runs on Onlook's servers.

**A copy of your code.** Every project is a git worktree, created in Onlook's data folder on a new branch from your main branch. The agent works only in that worktree. Onlook refuses to start it anywhere else, so your own checkout is never edited.

**The agent.** Onlook supports two agents behind one interface:

* **Claude Code**, which ships inside Onlook.
* **The ChatGPT agent**, which Onlook downloads when you set it up.

Both run on your Mac and use your own Claude or ChatGPT account. Onlook turns what the agent does into the activity you see in the chat: reading, editing, running, and asking for approval.

**The handoff.** The pill in the top bar asks the agent to do the next git step: commit, push, open a pull request, fix failing checks or resolve conflicts. GitHub access goes through the GitHub CLI on your Mac. With Claude, anything that reaches GitHub needs your approval first.

**Artifacts.** Sketches you make on the canvas are stored in Onlook's data folder, outside your repository. They render as isolated pages with no network access. See [Artifacts](https://docs.onlook.com/canvas/artifacts.md).

## What stays on your Mac

Your code, your dev server and your git history stay on your Mac. Context the agent needs goes to Claude or ChatGPT under your account. Onlook receives usage events, which never include code, file paths, prompts, or repository or branch names. See [How Onlook keeps your code safe](https://docs.onlook.com/start/trust.md) for the full list.

## The older browser-based editor

The [onlook-dev/onlook](https://github.com/onlook-dev/onlook) repository is the earlier Onlook: a browser-based visual editor for Next.js and Tailwind that ran projects in a web container. Its architecture is different from the desktop app's, and its README describes it. See [Onlook for developers](https://docs.onlook.com/developers.md).


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