Skip to content

The Shell app

The Shell app opens your Projects in an app of their own: Home is your Dashboard, and each Project has a tab. The editor and the Agent work on the host, as they do in your browser. It is for a Mac with Apple silicon and macOS 13 or later.

  1. In the Dashboard’s menu, choose Download the Shell app, then click Download for Mac with Apple silicon. In the editor, File › Download the Shell app… has the same download.
  2. Open the downloaded file, drag the Shell app into Applications and open it there. macOS asks once, saying Apple checked it: choose Open.

Opened from anywhere else, Shell asks Move Shell to Applications? It updates itself only from there.

Shell signs you in through your browser, where you may be signed in already.

  1. Click Sign in with your browser. Your browser opens a page, Sign in to the Shell app: sign in there with Google first if you are not yet.
  2. Click Open the Shell app on that page. Or type its code in the app under Code from the browser, and click Sign in. The code is good for a minute.

If you did not just press Sign in in the app, close that page. Sign Out is in the Shell menu; it closes your Projects’ tabs.

  • Home is the Dashboard. A Project you open from it gets a tab of its own, and the tabs you had come back at the next start.
  • Find a Project… in the Window menu, or ⌘K with Home in front, finds your Projects by name or address. Window also lists the tabs (⌘1 to ⌘8, and ⌘9 for the last) and has Close Tab (⌘W).
  • The editor’s menus are in the Mac’s menu bar. A link to another web page opens in your browser.
  • A tab whose game is playing, or whose Agent has a Run under way, keeps going behind other tabs and windows.
  • The Project’s file at the top of its folder (<project>.shellproject) opens its tab from the Finder.
  • When Shell cannot reach the host, it says You are offline and tries again by itself.

In the app, Work on your computer needs no terminal and no token to copy. The Dashboard’s Agent page has these steps too, for an agent on your computer instead of the Agent in the editor.

  1. In the editor, click Folder in the toolbar, or choose File › Work on your computer…. Then click Choose a folder….
  2. Choose or make the folder for the Project, and click Keep in step.

The Project’s files are brought into it, and each change goes both ways while the app is open, with the Project’s tab or without it. Folder in the toolbar then says how it is, such as Folder · in step.

  • Show in Finder, Open in VS Code and Open in Terminal open the folder. Claude Code started in it edits the Project: the folder is set up for it already.
  • Files changed in both places are listed with Show both. Yours is kept, and the online one is beside it, ending in .online: remove that file to send yours.
  • Change… chooses another folder, and Stop stops keeping it in step.
  • For a folder in Documents, Desktop or Downloads, macOS may ask once whether Shell may use it.
  • In Assets, Open in… on a file’s menu opens a picture, sound, text or data file, 3D model or font in an app of your computer, and such a file dragged out of Assets onto the desktop or into another app arrives as that file. Other files, such as scripts, web pages and SVG files, are not opened, and do not arrive when dragged out.

Shell looks for a new version as it starts, every hour, and when the computer wakes, and downloads it by itself. Update ready · Restart at the end of the row of tabs puts it in; otherwise it goes in at the next start. Check for Updates… is in the Shell menu.

When the host takes only a newer version, Shell shows Update to go on over everything and opens no Project until it is updated. It downloads the new version and offers Restart; where it cannot, it says why, with Try again. Your tabs and folders come back after the update.