Docs
Gui shows your web app in a window and puts your coding agent on top of it. Select part of the page, say what to change, and the agent edits your code. This page covers the parts of Gui that you use every day.
What you need
- A Mac with Apple silicon (M1 or later) and macOS 13 or later.
- A Gui account. Sign in with Google, GitHub, or a code sent to your email. Gui is free during the alpha.
- A coding agent, for example Claude Code or Codex. Gui does not include an AI model. It uses the agent on your Mac, with your login and your plan.
Download Gui, open Gui.dmg, and drag Gui to Applications. When you first open it, Gui shows your agents. Install gets Claude Code or Codex for you, and Sign in starts the agent’s login. For a different agent, Gui opens its install page, and its login runs in Terminal.
Gui also works with Cursor, Amp, OpenCode, Grok Build, Kiro, Devin, Pi, Muse Code, fx, jcode and Gemini CLI, and with other agents that use ACP. Add an agent, or turn off the ones you don’t use, in Settings → Agents.
Gui updates itself. To check now, choose Gui → Check for Updates…
Open a project
On the start screen, click Open project… (⌘O) and choose your project folder. Gui finds the package manager and the dev script. The first time, it shows you the command and asks before it runs it. If the dependencies are missing, Gui installs them in the same step. In a monorepo, Gui asks which app to show. If the project has a .env.example, Gui offers to make .env.local from it.
Then Gui starts the dev server and shows your app. Any app on a local dev server works. For React (Vite and Next.js) and Astro, Gui also finds the source file of each element.
To start from nothing, click New project… and choose Website, Dashboard, or Blank.
Each project opens in its own tab, with its own preview, chat, dev server and agent. ⌘T opens a new tab. Tabs in the background keep running. A tab shows when its agent is working, is waiting for you, or has failed.
To open folders from Terminal, choose Gui → Install 'gui' Command… once. Then gui opens the current folder, and gui path/to/app opens a different one.
When a project is open already, the gui command, the Dock and File → Open Recent show its tab. Open project… and the recent projects on the start screen open it again in a new tab, so you can run two apps of a monorepo side by side.
Design mode
Click Design mode in the toolbar, or press ⌘D. Gui outlines the element under the pointer and shows its component and its size.
- Click an element to select it.
- Drag across the page to select an area.
- Hold Shift to select more than one. Shift-click a selected element to remove it.
- Press Esc when you are done.
Then write the change in the chat. Each selection goes with your message: a screenshot, its HTML and styles, and the file and line it came from. You can also paste or drag a reference image into the chat. The agent sees it.
To change a few words, turn design mode off, double-click the text on the page, and type. Press Return or click away to keep the change. Press Esc to put the old text back. Gui writes the change into your source file when it finds the same text there. When it does not, it asks the agent to make the change.
Variations
In a project, select an element and ask for options, for example “show me 10 ways to make this better”. The agent writes up to 15 versions into your code. A bar in the bottom-left corner of the page shows the one you see, for example 3 of 10 · Tighter hierarchy, and the page scrolls to the element.
Click ‹ and › to go through the versions. The original is one of them. Use this asks the agent to keep the version that you see and remove the others. × discards all of them: it undoes the message that made them, and asks first when later messages would go too.
On a canvas, ask for versions of a page instead. Each version is a frame on the board.
The chat
The agent’s name at the top of the chat switches agents or starts a new chat. The model button chooses the agent’s model and effort.
While the agent works, the chat shows each step. When it is done, the steps fold into one line, and the chat shows what changed: the selected element before and after, and the files. Click Undo to put the files back, or Follow up to ask for more. On an earlier message, Undo to here undoes that change and each change after it. Gui asks first. When the chat shows, ⌘Z also undoes the last change.
Gui keeps a copy of your project files before and after each change, and Undo uses these copies. Gui does not change your git history. It also does not commit, push or make branches. Ask your agent for that, or use the terminal. The toolbar shows the project’s current branch.
Messages that you send while the agent works wait in a queue above the message box, and run in order. You can edit a queued message, drag it to a new place, remove it, or click Send next. Stop stops the agent and pauses the queue.
Claude Code and Codex can also take a message while they work. Press ⌘↩ to add it to the reply under way, and the agent reads it at its next step. On a queued message, Send now does the same. To make this what ↩ does, choose Steer for Sending while the agent works in Settings → Agents. Then ⌘↩ queues. While the agent waits for you to allow something, ⌘↩ allows.
Auto and Ask set what the agent can do without you. The shield button in the message box, or ⇧⌘A, changes between them. Auto is on by default. In Auto, Gui lets the agent edit project files and run commands. It still asks you about files outside the project, sensitive files such as config files, lockfiles, package.json and git hooks, opening a website, a dev script the agent changed, and anything the agent flags. Commands do not run in a sandbox. In Ask, Gui asks you about everything except edits to ordinary project files. Each project keeps its own setting. When the agent waits for you, press ⌘↩ to allow or ⌘⌫ to not allow.
Amp, fx, Kiro, OpenCode and Pi use their own settings to decide when to ask you. For these agents, the message box says so in place of the shield button.
The chat floats on the page. Drag it by its header to a different corner, and drag an edge to resize it. Drag it to the left or right edge of the window, or press ⇧⌘D, to show it as a sidebar. ⌥⌘L moves it to a window of its own, and ⌘B hides it. Errors from the console and the dev server show above the message box, with a button that gives the errors to your agent.
Screen sizes
The size menu in the toolbar shows your app at four sizes:
- Desktop (⌘1) fills the window.
- Laptop (⌘2) is 1440 × 900.
- Tablet (⌘3) is 820 × 1180.
- Mobile (⌘4) is 390 × 844.
In a small window, Gui draws the device frame smaller and shows how much. The page still lays out at the full size, and the agent knows which size you look at. ⌘+ and ⌘− zoom, and ⌘0 goes back. Focus mode (⌘\) hides everything except the page, until you press ⌘\ again or Esc.
Rulers and guides
The ruler button in the toolbar, or ⇧R, shows rulers along the top and the left of the page. They measure in the CSS pixels of your page. ⇧R works when you are not typing in a field.
- Drag out of the top ruler to make a horizontal guide. Drag out of the left ruler to make a vertical guide.
- Drag a guide to move it. Drag it back onto its ruler to remove it.
- While you drag, a guide snaps to a near edge or the middle of the element under the pointer.
Guides stay with the page when it scrolls. Gui keeps up to 50 guides for each project. Gui draws guides over the page, not in it, so they do not show in screenshots or recordings. A canvas has no rulers.
While the rulers show, the agent gets your guides with each message, so you can write “line this up with the guide”. The agent can also find element edges that are within 8 pixels of a guide but not on it, and it can add or remove guides to show you what lines up.
Screenshots and recordings
The camera button in the toolbar, or ⇧⌘S, copies or saves a screenshot of the page, or attaches it to the chat. It takes the visible area or the full page.
Record (⌥⌘R) makes a video of the page only, up to 60 seconds long. When you stop, the clip goes with your next message. The agent gets frames from the clip and a timeline of what happened on the page, and it can examine each frame of an animation. Agents that cannot read images cannot see the clip. They use the timeline.
The agent can also play an animation in your app and watch it by itself. It gets frames from the motion on one image and a list of the animations that ran. It can slow animations down, or turn on reduced motion to check that version.
To talk while you record, turn on the microphone next to Record, then point at the problem as you speak. The first time, macOS asks you to let Gui use the microphone. Your Mac makes the transcript, so your voice does not go to a server. The agent gets your words and where the pointer was when you said them. Narrated recordings can be up to 3 minutes long and need macOS 26 or later. When you send a narrated clip, Gui waits for the transcript first. Gui uses the microphone only while you record with narration on.
Terminal and logs
The dot at the start of the address bar shows the dev server’s status. Click it to restart or stop the server, show its logs, or open your app in your browser. If the server stops with an error, a bar under the page shows its logs and a button to restart it.
⌘J opens the drawer under the page, with the dev server’s logs and your terminals. A terminal is your own shell, in the project folder. Click + to add one, and press ⌘K to clear it. Terminals keep running when you go to a different tab.
Canvases
A canvas is a board for designs, with no project folder and no dev server. Click New canvas on the start screen. Ask the agent for a page, or for a few versions of one. Each version is a frame on the board, in one HTML file. You can move, resize, name and compare frames, like artboards in Figma.
- Scroll to pan. Pinch or ⌘-scroll to zoom. Press H for the hand tool and V to move frames. As in Figma, ⇧1 fits the board, ⇧2 zooms to the selection, ⇧0 goes to 100%, and + and − zoom. Hold Z and click to zoom in, ⌥-click to zoom out, or drag around an area to zoom to it.
- Drag across the board, or Shift-click, to select frames. Your next message is about them.
- ⌥⌘G puts the selected frames in a section, ⌘D duplicates them, ⇧⌘Z redoes your own board changes, and ⇧⌘E exports them as PNGs. ⌘C and ⌘V copy and paste them, onto this canvas or another.
- Double-click a frame to open it live. You can use design mode and change the size as in a project. Click Canvas or press Esc to go back.
The agent can take screenshots of a website to use as a reference, for example “make it feel like linear.app”. When a design is ready, right-click its frame and choose Turn into Project… to make a Vite project from it. The project opens in a new tab.
Other agents
Claude Code, Codex or Cursor running outside Gui can use its canvas and preview too. Turn on Settings → Agents → Let other agents use Gui, then copy the setup for your agent. For Claude Code it’s one command to run in Terminal; Codex and Cursor get the lines for their config files.
The agent works on the project or canvas in Gui’s front window, and you watch it there. It only works on this Mac, while you’re signed in to Gui. The setup includes a token: keep it to yourself, and click New token if it gets out.
With nothing open, the agent can open one of your recent projects or canvases itself. It opens without Gui’s chat, and Gui’s own agent doesn’t start, until you show the chat with ⌘B. Before the agent opens a folder Gui has never opened, Gui asks you on its start screen.
GitHub
Clone… on the start screen copies a repository to your Mac. Type its name or address, or connect GitHub to choose from your repositories, private ones too. In Settings → GitHub, you can connect or disconnect GitHub and choose the repositories that Gui can get. Gui uses the connection only to clone.
Keyboard shortcuts
Help → Keyboard Shortcuts (⌘/) shows all of them, and each button shows its shortcut in its tooltip. These are the ones you use most:
| Open a project folder | ⌘O |
| New canvas | ⌥⌘N |
| New tab | ⌘T |
| Close the tab | ⌘W |
| Reopen the tab you closed | ⇧⌘T |
| Find in the preview or terminal | ⌘F |
| Design mode | ⌘D |
| Rulers | ⇧R |
| Screenshot | ⇧⌘S |
| Record the page | ⌥⌘R |
| Desktop, Laptop, Tablet, Mobile | ⌘1 – ⌘4 |
| Zoom in, zoom out, fit | ⌘+ ⌘− ⌘0 |
| Focus mode | ⌘\ |
| Show or hide the chat | ⌘B |
| Go to the message box | ⌘L |
| While the agent works, send into its reply instead of the queue | ⌘↩ |
| Chat as a sidebar, or floating | ⇧⌘D |
| Chat in its own window | ⌥⌘L |
| New chat | ⇧⌘K |
| Stop the agent | ⌘. |
| Auto or Ask | ⇧⌘A |
| Allow, or don’t allow | ⌘↩ ⌘⌫ |
| Undo the agent’s last change, when the chat shows | ⌘Z |
| Terminal and logs | ⌘J |
| Settings | ⌘, |
| All shortcuts | ⌘/ |
Your data
Your projects stay on your Mac. Gui keeps your chats, the copies for Undo, recordings and canvases in ~/Library/Application Support/Gui. Gui does not send your code, files, chats or screenshots to us. Your agent sends your prompts and code to the company that makes it, under that company’s terms.
When Gui has an error, it sends us a crash report without your code or files. To stop them, turn off Send crash reports in Settings → Account. The Privacy page has the details.
Help
Gui is in alpha, so some things will break. Tell us when they do.
- Help → Contact Support starts an email to hello@usegui.com with your Gui and macOS versions in it.
- Send a message on X.
- Report a problem or read the code on GitHub.