am-will/gooey-pi

GooeyPi is a desktop workspace for Pi, OMP, and Prime Agent. It gives all three coding agents the same friendly interface on macOS, Linux, and Windows while leaving each harness in charge of its own models, logins, and saved sessions.

Use the switcher in the top-left corner to move between Pi Work, OMP Work, and Prime Work. GooeyPi detects the harnesses installed on your computer and shows the ones that are ready. You can refresh detection or set a custom executable path in Settings.

Each harness keeps its own projects, sessions, model list, provider visibility, and running work. Switching harnesses changes the workspace without stopping work already running in another one.

You only need one harness to get started:

• Pi is the base coding-agent harness in the Pi family.
• OMP adds its own plugins, commands, and approval controls.
• Prime Agent adds Prime's provider integrations and native heartbeats.

• Stream conversations with Markdown, reasoning summaries, tool activity, retries, and context compaction.
• Choose a model, reasoning level, and Fast mode when the selected model supports it.
• Queue a follow-up or steer an agent while it is working.
• Paste or drop PNG, JPEG, GIF, and WebP images into a prompt when the model supports vision.
• Resume, rename, search, and archive persistent sessions.
• See running, finished, failed, and waiting-for-input work in one Activity view, then clear items you have handled.

• Add local folders and reopen sessions grouped by project.
• Search projects, chats, and branches from the sidebar.
• Switch between linked Git worktrees from the composer.
• Create a branch worktree and open it as a new GooeyPi workspace.
• Mention another top-level session with @session, copy its UUID, or let agents create and message model-selected sessions for parallel work.

• Review Git status and diffs, stage or unstage files, restore changes with confirmation, and commit without leaving the app.
• Browse project files and reveal them in your system file manager.
• Open multiple terminal tabs for a session. Highlight terminal output to attach it to the next prompt.
• Open the right-hand Summary, Changes, Browser, or Files panel whenever you need it.

• Use an isolated in-app browser with an address bar, navigation history, downloads, and an external-browser handoff.
• Point at page elements and add notes. GooeyPi attaches those annotations to your next message.
• Enable browser control so an agent can open and operate its own tabs. You can watch its cursor and work in the same tabs when you want to take over.

• Create one-time or recurring schedules for the active harness.
• Pick the project or existing session, model, reasoning level, timezone, and Fast mode.
• Run a schedule immediately, pause or resume it, and inspect the result and run history.
• Manage Prime heartbeats alongside GooeyPi schedules when Prime Agent exposes them.
• On macOS, opt in under Settings → General to keep scheduled work running from the menu bar after closing the window, and optionally launch GooeyPi in the background at login. The packaged app also accepts --background to start without opening its window.

The Capabilities page brings together packages, plugins, extensions, skills, prompts, and MCP servers. GooeyPi can manage local stdio MCP definitions for OMP and adapter-enabled Pi. Network MCP and authentication stay under the selected harness's direct control; those entries are visible but read-only in GooeyPi, with bounded definition-only removal available for cleanup. MCP discovery has an independent 2,500-definition-per-settings-file limit and reports an explicit warning when that limit is exceeded, so unrelated capabilities cannot hide supported MCP rows.

GooeyPi also ships optional capabilities for:

• Let an agent ask you a small set of questions in a native dialog.
• Give agents controlled access to the in-app browser.
• Use TryCUA computer control when the separate CUA Driver is installed.

Ask User and computer control are off by default. You can enable, disable, or remove capabilities from the app.

• Dictate prompts with OpenAI, Groq, Deepgram, or a local whisper.cpp installation.
• Open the realtime voice companion to search, discuss work, and start a task in the currently selected harness.
• Choose an animated desktop pet that reacts while an agent works and carries the realtime voice controls. GooeyPi includes the Orb and GooeyPi pets and can discover compatible Codex pets.

• Choose a light, dark, or system theme and adjust the interface text size.
• Reduce motion, resize the workspace panels, or let them become overlays in a narrow window.
• Use keyboard navigation and the command palette for common actions.

1. Install Pi, OMP, Prime Agent, or any combination of the three.
2. Sign in or configure a model provider through each harness's own CLI.
3. Download GooeyPi from GitHub Releases, or run it from source.
4. Add a project folder and start a session.

GooeyPi checks common install locations automatically. If a harness is missing, open Settings → Harness to refresh detection or choose its executable.

GitHub Releases provides a DMG and ZIP for macOS, common Linux package formats plus AppImage, and a Windows installer and ZIP.

Harness provider credentials stay with the harness. Optional voice keys are encrypted with the operating system's secure storage, and local whisper.cpp dictation needs no API key.

You will need Node.js 24.15.0 or newer and npm 12.0.2 or newer. The repository pins Node.js 24.15.0 in .nvmrc; with nvm, you can select it with:

nvm install && nvm use
npm run toolchain:bootstrap

The bootstrap command verifies the exact size and SHA-512 of the checked-in npm archive, then installs it offline with install-time lifecycle scripts disabled into the invoked npm's configured global prefix, verifies the installed CLI and both tool versions against package.json and .nvmrc, and makes its shim available to subsequent GitHub Actions steps before dependencies are installed.

npm install
npm run dev

If node_modules/electron/dist is missing after installation, fetch Electron's platform binary before starting the app:

node node_modules/electron/install.js
npm run dev

npm install --ignore-scripts skips both Electron's platform download and the native dependency rebuild, so it is not enough on its own for running GooeyPi from source. If you used it, the recovery sequence below runs those two steps explicitly.

node-pty is a native dependency. If Electron cannot rebuild it with your default Python environment, point npm at a Python installation with the required build tools:

export npm_config_python=/path/to/python3
npm install --ignore-scripts
node node_modules/electron/install.js
npx electron-builder install-app-deps

Use ⌘ on macOS and Ctrl on Linux or Windows.

The Queue and Steer shortcuts can be swapped in Settings → Harness → Message shortcuts.

GooeyPi is built around local projects and local harness sessions. It does not rewrite session history or take ownership of Pi, OMP, or Prime Agent credentials.

Remote pages open in a separate browser profile with Node access disabled. Project paths and desktop actions are checked in the main process, and third-party capabilities still run with your operating-system permissions. Review packages, commands, MCP servers, and projects before allowing them to act.

For suspected vulnerabilities, follow the security policy and do not post sensitive details publicly. See docs/security.md for the full technical security model.

Run these before submitting a code change:

npm run typecheck
npm run check
npm test
npm run test:e2e
npm run build

See the validation guide for the source-of-truth checks and reproducible commands.

To make an installable local QA build, run the command for your operating system:

npm run package:mac:local-qa
npm run package:linux:local-qa
npm run package:win:local-qa

Build packages on their target operating system so native dependencies match the release.

GooeyPi is released under the permissive MIT License. See the license text for details.