# OpenWaggle

> Free desktop AI coding agent for macOS, Windows, and Linux. Pair two agents on one task, hand work to a Hive of Workers, and use your own models.

OpenWaggle is built on Pi. Waggle pairs two agents that take turns on one task; a Hive is a Queen session that delegates work to Worker sessions. The agent can also write OpenWaggle extensions that add panels, commands, and tools, which install only after the user approves them.

Download: https://openwaggle.ai/docs/getting-started/installation/
Source: https://github.com/OpenWaggle/OpenWaggle

## Getting started

- [Get started](https://openwaggle.ai/docs/getting-started/first-run/): Connect a model, open a project, ask about your code, and review your first change in OpenWaggle.
- [Installation](https://openwaggle.ai/docs/getting-started/installation/): How to install OpenWaggle on macOS, Windows, or Linux.

## Using OpenWaggle

- [Conversations and context](https://openwaggle.ai/docs/using-openwaggle/chat-and-tools/): Give the agent a task, follow its tool activity, and continue work in a project conversation.
- [Files, images, and voice](https://openwaggle.ai/docs/using-openwaggle/attachments-voice/): Share a file or screenshot with the agent, or dictate a message and review it before sending.
- [Right panel](https://openwaggle.ai/docs/using-openwaggle/right-panel/): Open Changes, Project Actions, Browser, Files, the Session tree, Resources and extension panels from one rail, and arrange it the way you work.
- [Reviewing changes and Git](https://openwaggle.ai/docs/developer-workflow/git-integration/): Review the agent's file changes, send corrections, and commit or push from the session's working directory.
- [Browser preview](https://openwaggle.ai/docs/developer-workflow/browser-preview/): Open your running web app, check different screen sizes, and send visual feedback to the agent.
- [Terminal](https://openwaggle.ai/docs/developer-workflow/built-in-terminal/): Run commands yourself, manage terminal tabs, and share command output with the agent.
- [Sessions and branches](https://openwaggle.ai/docs/using-openwaggle/session-tree/): Return to an earlier message, try another approach, or copy a conversation into a new session.
- [Session summary](https://openwaggle.ai/docs/using-openwaggle/session-summary/): Check a session's working directory, review changes, and find files and images shared during the conversation.
- [Projects and worktrees](https://openwaggle.ai/docs/developer-workflow/projects-and-worktrees/): Choose whether the agent works in your current checkout or a separate Git worktree.

## Customize

- [Providers and models](https://openwaggle.ai/docs/providers/overview/): Connect a provider account, enable models, and choose a model for your conversation.
- [Approvals and permissions](https://openwaggle.ai/docs/configuration/approvals-permissions/): Choose agent access, review protected actions, and revoke saved approvals.
- [Project instructions](https://openwaggle.ai/docs/extending/agents-md/): Add an AGENTS.md file with the commands, conventions, and constraints the agent should follow.
- [Skills](https://openwaggle.ai/docs/extending/skills-system/): Give the agent a reusable workflow with a SKILL.md file, then select it in a conversation.
- [MCP connections](https://openwaggle.ai/docs/configuration/mcp/): Connect external tools and services, review server permissions, and troubleshoot MCP connections.
- [Extensions](https://openwaggle.ai/docs/extending/plugins/): Install a local extension, review its permissions, and enable or remove it in Settings.
- [Project actions](https://openwaggle.ai/docs/configuration/project-actions/): Save project commands, manage their runs, and prepare new worktrees.
- [Settings](https://openwaggle.ai/docs/configuration/app-settings/): Find settings for models, permissions, appearance, browser previews, and project tools.
- [Keyboard shortcuts](https://openwaggle.ai/docs/getting-started/keyboard-shortcuts/): Default shortcuts for conversations, terminals, browser preview, and navigation.

## Multiple agents

- [Hives](https://openwaggle.ai/docs/using-openwaggle/hives-and-sessions/): Split a task across independent worker sessions, choose their workspaces, and review the results.
- [Waggle](https://openwaggle.ai/docs/using-openwaggle/waggle-mode/): Let two agents take sequential turns on a task in the same conversation.
- [Agent definitions](https://openwaggle.ai/docs/extending/agent-definitions/): Create a reusable role for new sessions, with instructions and optional model or tool defaults.

## Help

- [Troubleshooting and recovery](https://openwaggle.ai/docs/configuration/session-recovery/): Resolve connection problems, waiting sessions, and missing worktrees before considering database recovery.
- [Privacy and data](https://openwaggle.ai/docs/configuration/security-privacy/): Understand what stays on your machine, what can leave it, and what permissions do not protect.
- [Usage statistics](https://openwaggle.ai/docs/configuration/usage-statistics/): Every field in OpenWaggle's anonymous usage statistics and error reports, where they go, and how to turn them off.

## Developer docs

- [Build from source](https://openwaggle.ai/docs/developer-guide/building-from-source/): How to clone, build, and run OpenWaggle from source.
- [Contributing](https://openwaggle.ai/docs/developer-guide/contributing/): Report bugs, suggest features, and improve the documentation through GitHub issues.
- [Architecture](https://openwaggle.ai/docs/developer-guide/architecture/): Find the main processes, session owner, runtime adapter, and UI boundaries in the OpenWaggle source.
- [Pi runtime](https://openwaggle.ai/docs/developer-workflow/pi-runtime/): How OpenWaggle connects Pi's agent execution to desktop tools, session history, and MCP.
- [Command line](https://openwaggle.ai/docs/developer-workflow/command-line/): Open the app, run an agent headlessly, check the Session Host, and find every openwaggle command.
- [Sessions CLI](https://openwaggle.ai/docs/developer-workflow/sessions-cli/): Discover, control, watch, and export OpenWaggle Sessions from a terminal or another agent.
- [Token benchmarks](https://openwaggle.ai/docs/using-openwaggle/token-benchmarks/): Historical first-call input measurements, their source data, and limits of the comparison.
- [Build an extension](https://openwaggle.ai/docs/extending/openwaggle-extensions/): Build a local extension package that adds desktop UI, commands, or agent tools.
- [Pi extensions](https://openwaggle.ai/docs/extending/pi-extensions/): Use Pi extension APIs for agent tools and hooks, and understand OpenWaggle's desktop integration boundaries.

## Package reference

- [Overview](https://openwaggle.ai/docs/packages/overview/): OpenWaggle publishable packages for extension authors, Waggle policy, and Pi Waggle integration.
- [Extension SDK](https://openwaggle.ai/docs/packages/extension-sdk/0.1/): Browser-safe OpenWaggle extension SDK types, broker helpers, theme helpers, and federated-module context helpers.
- [Extension React](https://openwaggle.ai/docs/packages/extension-react/0.1/): React primitives for OpenWaggle extension surfaces that use the extension UI style contract.
- [Waggle Core](https://openwaggle.ai/docs/packages/waggle-core/0.1/): Runtime-neutral Waggle policy, prompts, state, presets, consensus, and turn orchestration primitives.
- [Pi Waggle](https://openwaggle.ai/docs/packages/pi-waggle/0.1/): Run two configurable Pi agents in alternating turns until they reach consensus or a safety limit.