Mousedo

A native macOS menu bar agent that can read the screen, operate apps, and keep your work moving without leaving the keyboard.

Mousedo is an open-source computer-use agent for macOS. It lives in the menu bar, expands into a compact task surface, and runs agent sessions directly inside the app process. It is built for fast local workflows: ask it to use apps, inspect browser pages, continue a task from the notch, or review the trace later.

Highlights

• Native menu bar app with a polished popover, task list, task detail view, and dynamic notch companion UI.
• Computer use tools for macOS apps, including app/window inspection, clicking, typing, scrolling, and keyboard actions.
• Browser use tools through the Mousedo browser extension stack for Chromium-compatible browsers.
• Streaming task sessions with persisted history, trace logs, tool timelines, and app-aware task icons.
• OpenAI provider setup with OAuth-first configuration, API-key fallback, model settings, and usage display.
• Sparkle-ready updates and a production release workflow for signed, notarized DMG builds.

Screens

Mousedo currently ships as a menu bar utility:

• The menu bar popover starts tasks and shows recent sessions.
• The task detail page shows messages, tool actions, errors, and follow-up input.
• The notch view mirrors active or completed work when the popover is closed.
• Settings manages permissions, model providers, updates, and app configuration.

Requirements

• macOS 14 or newer
• Xcode 16 or newer
• Swift 6.1 toolchain
• Accessibility and Screen Recording permissions for app automation
• An OpenAI/Codex provider configuration from Mousedo Settings

Clone

git clone --recurse-submodules https://github.com/EYHN/mousedo.git
cd mousedo

If you already cloned without submodules:

git submodule update --init --recursive

Build And Run

For day-to-day local development:

./Scripts/run-menubar-xcode.sh

That script builds the Xcode project and launches the resulting menu bar app.

For a simple SwiftPM build:

swift build --product Mousedo

For an unsigned local .app bundle:

./Scripts/build-menubar-app.sh
open .build/Mousedo.app

Project Layout

Sources/Mousedo/              App source, UI, settings, agent runtime
Sources/Mousedo/Agent/        Agent tool adapters and provider resolution
Sources/Mousedo/NotchKit/     Notch window, layout, and animation runtime
Sources/Mousedo/Settings/     Settings window, provider setup, updates
Scripts/                      Local build and launch helpers
DevKit/Scripts/               Release, signing, notarization, and DMG tooling
docs/                         Browser tool design notes and fixtures
kwwk-browser/                 Browser automation submodule
kwwk-computer-use-core/       macOS computer-use core submodule

Release Builds

The production workflow is .github/workflows/macos-release-production.yml.

It expects these GitHub secrets and variables:

• KEYCHAIN_PASSWORD
• DEVELOPER_ID_KEYCHAIN_GZIP_BASE64
• SPARKLE_PRIVATE_KEY
• CLOUDFLARE_R2_SECRET_ACCESS_KEY
• CLOUDFLARE_R2_ACCOUNT_ID
• CLOUDFLARE_R2_BUCKET
• CLOUDFLARE_R2_ACCESS_KEY_ID
• CLOUDFLARE_R2_PUBLIC_BASE_URL

The workflow builds Mousedo.app, signs it with a Developer ID certificate, notarizes the DMG, uploads Sparkle appcast files to R2, and attaches Mousedo.dmg to the GitHub release.

Privacy And Safety

Mousedo requests Accessibility and Screen Recording permissions because computer-use agents need to inspect and operate local app interfaces. Session data and trace logs are stored locally under Application Support. Provider credentials are configured from Settings and resolved only when sessions need them.

Mousedo can operate real apps and browser pages. Review tasks before running them on sensitive accounts or destructive workflows.

Contributing

Issues and pull requests are welcome. Before sending a PR, run:

swift build --product Mousedo

See CONTRIBUTING.md for the development workflow and review expectations.

License

Mousedo is released under the MIT License.