Roscoe desktop app

The desktop app is the no-terminal way to run Roscoe on macOS and Windows. It's a thin native shell around the same roscoe binary the CLI uses. Everything the CLI install walks you through by hand, the app does for you on launch. It downloads the binary, runs roscoe serve, opens the dashboard, and wires up Claude. The dashboard you see is the same web UI you'd reach at localhost:7777, embedded in the app window.

Prefer the terminal, or on Linux? Use the CLI instead. The two share the same data and server, so you can switch freely.

Platform availability#

macOS 11 (Big Sur) or later ships as a single universal build for both Apple Silicon and Intel. Roscoe ships the .dmg Developer-ID signed and notarized, so it opens without a Gatekeeper warning.

Windows 10 or 11 on x64 ships as an .exe installer. Roscoe doesn't Authenticode-sign it yet, so SmartScreen shows a "Windows protected your PC" prompt on first run: click More info, then Run anyway. The app still verifies every auto-update's signature before it installs.

There's no Linux desktop build. On Linux, run Roscoe from the CLI.

Get it#

On macOS:

1. Download the .dmg from the download page.
2. Open it and drag Roscoe to Applications.
3. Launch it.

On Windows, download the .exe installer from the same download page and run it. It installs Roscoe along with the WebView2 runtime it needs to render the dashboard.

What happens on first launch#

The app gets you from zero to a running dashboard without a terminal:

• Installs the engine. It drops the bundled roscoe binary at ~/.roscoe/bin/roscoe (the canonical location) if that's missing or older than the bundled one. This also puts the roscoe CLI on your machine. The setup wizard's readiness check tells you whether it's on your PATH yet, and offers to add it for you.
• Starts the server. It runs roscoe serve in the background (logging to ~/.roscoe/logs/desktop.log) and shows a splash screen until the server is healthy. If a roscoe serve is already running, the app attaches to it instead of starting a second one.
• Finds your tools. Apps launched from Finder don't inherit your shell PATH, so the app resolves your login-shell PATH before starting the server. That's how it locates the claude CLI if you use it as your AI backend (the service that actually answers a workflow's AI steps).
• Opens the dashboard. Once the server is healthy, the window loads the local web UI.

First-run setup#

The first time you open the app, a short setup wizard walks you through getting connected. It appears only in the desktop app, not in a browser:

1. Readiness check: shows what's ready on this machine. It confirms the local server is running. It also checks whether the roscoe command is on your PATH, and offers a one-click fix if it isn't, which you can undo later from Settings. It looks for the Claude desktop app and an AI backend (the claude CLI or an ANTHROPIC_API_KEY). All of these are optional, so none block setup. Workflows with no AI steps need neither.
2. Connect Claude: one click registers Roscoe as an MCP (Model Context Protocol) server in the Claude desktop app's config (~/Library/Application Support/Claude/claude_desktop_config.json). The entry points at the canonical ~/.roscoe/bin/roscoe, so it keeps working across app updates. Restart the Claude desktop app afterward. You can re-run this any time from Settings. The same click also drops a /roscoe slash command into ~/.claude/commands/. If you also use Claude Code or Cowork, you can launch a workflow there with /roscoe <workflow-name>. (The desktop chat app itself has no slash commands.)
3. Set up an AI backend, if you skipped it earlier: install the claude CLI or set an ANTHROPIC_API_KEY. This step doesn't block setup, since only a workflow's AI steps need a backend. Add one now or later.
4. Pick a starting point: seed a set of example workflows, or start with a blank workspace.

Once Claude is connected, ask it to run a workflow: the AI steps run on your Claude subscription. See Running on your Claude subscription.

The menu bar#

Roscoe lives in your menu bar while it's running, a small monochrome icon up top, next to the clock. It's there so a long-running workflow can run unattended: kick it off, close the window, and get on with your day.

Closing the window no longer quits Roscoe. The window tucks away, and the server keeps running in the background, so anything in flight keeps going. To quit for real (and shut the server down), use Quit Roscoe from the menu-bar icon (or ⌘Q).

Click the Dock icon, or Open Roscoe in the menu, to bring the window back.

Open the menu and you'll see:

• What's running now: each active workflow, with the ones waiting on you flagged awaiting input. Click any to jump straight to it in the dashboard.
• Recent runs: the last few that finished, marked success or failure.
• Start a workflow: pick one from the submenu and its run dialog opens, ready for you to fill in and start.
• Open Roscoe, Check for updates, and the quit item.

You'll also get a native notification when a run finishes or pauses for your input, then open it from the menu bar's What's running now. Don't want the notifications? Toggle Notify me when runs finish off in the menu. The count next to the icon tells you how many runs are active at a glance.

Staying up to date#

The app updates itself. In the background, it checks for a new signed build and downloads it. Then it asks whether you want to Relaunch now or leave it for next time. Either way, there's nothing to re-download by hand. The old "grab the latest DMG" step is gone.

Updating the app also updates the engine. A new app bundles a newer roscoe binary. On relaunch it refreshes the canonical runtime at ~/.roscoe/bin/roscoe (it never downgrades), and restarts the server on the new version. You don't manage two updates. The app is the single updater.

That's why Settings → Updates shows a read-only "Managed by desktop app" state inside the app, instead of the CLI's own check/install buttons. The app owns updates, so the engine's own self-update stands down. That way two updaters never step on each other. Run roscoe serve on its own from a terminal, and the CLI updater is back in charge.

To turn auto-update off, set ROSCOE_DISABLE_UPDATE_CHECK=1 in the app's environment. The app then never checks or downloads. Update instead by grabbing a new build from the download page yourself.

Where your data lives#

Everything is under ~/.roscoe/ (or $ROSCOE_HOME if you set it), the same home the CLI uses:

Project-scoped workflows still live in <repo>/.roscoe/workflows/ when you're working in a repo; the desktop app serves those too. See Global vs Project.

Run links open in the app#

Once the app is installed, clicking a run link opens that run in the app window rather than a browser tab. Links that Claude gives you over MCP already point at the right place; so does o in the CLI's live run view.

You don't have to configure anything. The installer registers a roscoe:// URL scheme, and the local server checks for it each time a link is opened:

• App installed — the run opens in the app. If the app was closed it starts up and lands directly on that run. If it was already running you never get a second copy: the link goes to the window you already have. (On Windows, if another app currently owns the foreground, the taskbar button may flash instead of the window raising — that is Windows' foreground rule, not Roscoe.)
• App not installed — the link opens in your browser exactly as before, with a one-line note that a desktop app is available.

Two things worth knowing:

• Upgrading from a version without deep links? On macOS the scheme is carried inside the app bundle and the system reads it when the app launches, so run links start routing to an already-installed app from its next start. On Windows the installer writes the registration directly, so it takes effect as soon as the install finishes.
• If you deliberately quit the app, clicking a link will start it again. To stop that, set ROSCOE_DISABLE_OPEN=1 for the server — links then always open in the browser.

Using it alongside the CLI#

The desktop app and roscoe serve share one home and one server, so they coexist:

• If a terminal roscoe serve is already running, the app attaches to it rather than starting a duplicate.
• Opening a second copy of the app focuses the existing window instead of spawning another server.
• The same workflows and runs show up whether you open the app or browse to the local server. It's the same server either way.

See also#

• Install Roscoe (CLI) — the terminal path.
• MCP integration — how Claude drives workflows.
• Running on your Claude subscription — where AI inference runs.