# Hivemind

> Hivemind is a free, open-source desktop app for Linux, macOS and Windows. It runs Claude Code, Codex, opencode, Cursor, Copilot and any other coding agent with a command line side by side, each in a real terminal, and your agents build the views, widgets and tools of the workspace they work in.

You and your own programs drive it with the `hive` command and an API, from other computers or your phone. Website: https://hivemind.griiken.com/ · Source (MIT): https://github.com/dip497/hivemind · Plugins: https://hivehub.griiken.workers.dev/ · Compared with similar apps: https://hivemind.griiken.com/compare/

Every page is also Markdown: add .md to its address. All of them in one file: https://hivemind.griiken.com/guide/llms-full.txt

## Get started

- [Hivemind](https://hivemind.griiken.com/guide/index.md): A workspace your coding agents build and work in: run them side by side, add your own views, widgets and tools, and reach them from anywhere.
- [Install and run your first agent](https://hivemind.griiken.com/guide/getting-started.md): In about five minutes: install Hivemind, start a coding agent in your project, and answer its first question.
- [Run many agents at once](https://hivemind.griiken.com/guide/run-many-agents.md): A 15-minute tutorial: three agents on three branches of one project, and you answering whichever one waits.
- [Use these docs from your agent](https://hivemind.griiken.com/guide/docs-for-agents.md): Let your coding agent read these docs through llms.txt or any page as Markdown, and teach it Hivemind with the hive skills.

## Use Hivemind

### Agents

- [Run agents](https://hivemind.griiken.com/guide/agents.md): Add an agent, make it your default, switch one off, and put agents to sleep to free memory.
- [Know who is waiting](https://hivemind.griiken.com/guide/know-who-is-waiting.md): See at a glance which agent needs you, jump to it, and get told on your desktop or phone when one does.
- [Coordinate agents](https://hivemind.griiken.com/guide/agent-workflows.md): Have one agent send work to several others, collect their replies and answer their questions, with hive ctl.
- [Review an agent's changes](https://hivemind.griiken.com/guide/review.md): Watch an agent's edits in the Code tile, comment on a line so the agent fixes it, and approve or change an agent's plan.
- [Track work as issues](https://hivemind.griiken.com/guide/issues.md): Keep a project's work as Markdown issues that you and your agents read, pick up and close.
- [Work in a git worktree](https://hivemind.griiken.com/guide/git-worktree.md): Give each agent its own branch and folder with a git worktree, so agents working at once never edit the same files.
- [Switch views](https://hivemind.griiken.com/guide/views.md): Show your workspace as a Canvas, as Windows with tabs and panes, or as a view you install from HiveHub.

### Other computers and people

- [Set up your own network server](https://hivemind.griiken.com/guide/self-hosting.md): Run hive-net so your devices, guests and phone reach each other from different networks.
- [Run agents on another computer](https://hivemind.griiken.com/guide/machines.md): Add a server, a VM or a second laptop over ssh, open one of its folders, and run terminals and agents there.
- [Keep agents running while your laptop sleeps](https://hivemind.griiken.com/guide/host.md): Turn a Linux server into an always-on host that keeps your workspaces, agents and guests up when your computer is off.
- [Connect your devices](https://hivemind.griiken.com/guide/connect.md): Pair your phone or another computer, or let a person in, with one invite from Settings → Connect.
- [Share a workspace](https://hivemind.griiken.com/guide/multiplayer.md): Let other people into a workspace, give each a role, and see who is there and where they point.
- [Answer agents from your phone](https://hivemind.griiken.com/guide/phone.md): Pair your phone's browser, then answer, start, stop and watch your agents from anywhere.
- [Open the app in a browser tab](https://hivemind.griiken.com/guide/browser-tab.md): Serve the whole Hivemind app to a browser tab on this computer, or to another device through Tailscale.

### Settings

- [Change how Hivemind looks](https://hivemind.griiken.com/guide/appearance.md): Pick a preset or a theme from a package, choose any accent colour, set corners and fonts, the wallpaper, frosted glass and overlays, and share your look as a file.

## How it works

### Overview

- [Architecture overview](https://hivemind.griiken.com/guide/architecture.md): What runs on your computer, on your server, on other machines and on your phone, how the parts talk, and what stays on your computer.

### Components

- [The desktop app](https://hivemind.griiken.com/guide/desktop-app.md): What a window, the main process and its helpers each do, and the sockets the app listens on.
- [Terminals and the background process](https://hivemind.griiken.com/guide/background-process.md): How the background process runs every terminal and agent, keeps their screens, and keeps them running when the app closes.
- [The hive command and its sockets](https://hivemind.griiken.com/guide/hive-cli.md): What hive does on its own, how hive ctl reaches the app or a host, and the two local sockets behind it.
- [Plugins](https://hivemind.griiken.com/guide/plugins.md): The four kinds of plugin, where each sits on screen, where HiveHub fits, and how to add or make one.
- [The plugin index](https://hivemind.griiken.com/guide/hub-index.md): What a hub serves, how the app and hive read it, and what happens to an entry they cannot read.
- [Devices and hive-net](https://hivemind.griiken.com/guide/how-devices-connect.md): How your computers, phone and guests find each other and talk: directly, through your relay, always encrypted end to end.
- [The phone page](https://hivemind.griiken.com/guide/phone-page.md): What the phone page is, how it sees your agents through your own server, and what a phone may and may not do.
- [Machines and hosts](https://hivemind.griiken.com/guide/remote-machines.md): How Hivemind runs terminals and agents on another computer: a machine over ssh, or a host over hive-net.

### Core concepts

- [Workspaces, frames and tiles](https://hivemind.griiken.com/guide/workspaces.md): How Hivemind arranges a project: a workspace holds frames, each frame is bound to one folder, and every tile in it runs there.
- [Agent states](https://hivemind.griiken.com/guide/agent-states.md): What working, needs you, idle, exited and asleep mean on an agent's tile, and how Hivemind knows.
- [Trust, permissions and privacy](https://hivemind.griiken.com/guide/security-and-privacy.md): What can reach your files and network, how plugin permissions work, what leaves your computer, and what HiveHub learns.
- [The view protocol](https://hivemind.griiken.com/guide/view-protocol.md): How a view talks to the app: one message port, a hello that says what it may do, and nothing else.
- [Data and where it is stored](https://hivemind.griiken.com/guide/data-and-storage.md): Every file Hivemind keeps, which folder it is in, and what is never written down.
- [When an update changes your data](https://hivemind.griiken.com/guide/data-updates.md): How a new version moves the files on your computer to the shape it reads, once, with a backup, and how to put them back.

## Extend

- [Build a widget](https://hivemind.griiken.com/guide/widgets.md): Make a small live card for your canvas in a few lines of JavaScript, try it, and share it.
- [Write a view](https://hivemind.griiken.com/guide/extension-authoring.md): Build your own way of drawing the workspace: a small web page that lists, groups or charts your agents.
- [Write a tool](https://hivemind.griiken.com/guide/tool-plugins.md): Add a new kind of tile, such as a pull request panel or a commit browser, drawn by your own code.
- [Packages](https://hivemind.griiken.com/guide/packages.md): Put your tools, widgets, views, themes and live wallpapers in one package, check it, install it and publish it on HiveHub, all from the hive command.
- [Make a live wallpaper](https://hivemind.griiken.com/guide/live-wallpapers.md): A scene behind your canvas whose creatures are your agents: build one, ship it in a package, publish it.
- [Add your own agent](https://hivemind.griiken.com/guide/agent-providers.md): Teach Hivemind a coding agent it does not know yet, with one agent.yaml file: how to start it, read its screen and answer it.

## HiveHub

- [What HiveHub is](https://hivemind.griiken.com/guide/hivehub.md): Find agents, views, widgets and tools other people made, see what each one asks for, and install it with every file checked.
- [Publish a plugin](https://hivemind.griiken.com/guide/publish-to-hivehub.md): List your widget, view, tool or agent on HiveHub so anyone can install it from Hivemind: from the web form, the hivehub command or GitHub Actions.

### Reference

- [Signing in to HiveHub](https://hivemind.griiken.com/guide/hivehub-sign-in.md): Every way to sign in to HiveHub to publish: on the web, with hivehub login, with a token in CI, or from GitHub Actions. What each lets you do, how long it lasts, and how to end it.
- [The hivehub command](https://hivemind.griiken.com/guide/hivehub-command.md): Every hivehub command and flag with an example, its --json output, the environment variables it reads, its exit codes and the messages it prints.
- [HiveHub API](https://hivemind.griiken.com/guide/hivehub-api.md): Every public HiveHub route: the index Hivemind reads, search, one plugin, install, publish and the command's sign-in, with the auth each needs, its request, response, limits and errors.

## API

- [API overview](https://hivemind.griiken.com/guide/api.md): Let a program of your own drive a workspace: start agents, read their replies, follow who is waiting, all with a token you can revoke.
- [Make an API token](https://hivemind.griiken.com/guide/api-tokens.md): Make a token so one of your programs can drive a workspace, choose its role, and revoke it when you are done.
- [Connect and call](https://hivemind.griiken.com/guide/api-connect.md): Build a small client with the TypeScript or Python SDK: connect with your token, start an agent, read its reply, answer it, and hear events.
- [Methods by role](https://hivemind.griiken.com/guide/api-methods.md): Every method a program's token can call, grouped by the smallest role that allows it, with its params and an example.
- [Protocol](https://hivemind.griiken.com/guide/api-protocol.md): The raw messages a program sends and receives on the workspace API: the hello line, calls, answers, events and error codes, for any language.

## Reference

- [CLI reference](https://hivemind.griiken.com/guide/cli.md): Every hive command, grouped by what it does, with its options and exit codes.
- [Keyboard shortcuts](https://hivemind.griiken.com/guide/keyboard-shortcuts.md): Every Hivemind key in one place: anywhere in the app, on the canvas, in the Layers panel and in the Windows view.
- [Settings reference](https://hivemind.griiken.com/guide/settings.md): Every page in Settings, and every setting in settings.json with its default and allowed values.
- [Plugin settings and colours reference](https://hivemind.griiken.com/guide/plugin-settings.md): Every kind of setting a view, widget or tool can ask for, how to group and hide them, and the colours a view can add for people to change.
- [Environment variables](https://hivemind.griiken.com/guide/environment-variables.md): Every environment variable you can set to change how Hivemind, the hive command and the installer behave, and the ones Hivemind sets for you.
- [agent.yaml reference](https://hivemind.griiken.com/guide/agent-yaml.md): Every field of an agent file: how Hivemind starts an agent, reads its screen, answers it and resumes its sessions.
- [hive-net reference](https://hivemind.griiken.com/guide/hive-net.md): Every hive-net serve option, port, certificate setting, push key and file to back up, for your own network server.
- [Glossary](https://hivemind.griiken.com/guide/glossary.md): One word per thing: what each Hivemind word means, in a sentence.

## Help

### Help

- [Troubleshooting](https://hivemind.griiken.com/guide/troubleshooting.md): Find your problem by what you see, and fix it: agents that never show as waiting, an app that won't open, agents stopped after an upgrade, and more.
- [FAQ](https://hivemind.griiken.com/guide/faq.md): Short answers: what Hivemind costs, which agents it runs, what leaves your computer, and which systems it supports.
- [Logs and bug reports](https://hivemind.griiken.com/guide/logs-and-bug-reports.md): Where Hivemind writes what it does on each system, what to collect when something breaks, and how to report a bug.
- [Changelog](https://hivemind.griiken.com/guide/changelog.md): What changed in each recent Hivemind release, in plain words.

### Install and update

- [Install](https://hivemind.griiken.com/guide/install.md): Install Hivemind with one command on Linux, macOS or Windows, pick a release channel or an exact version, or build it from source.
- [System requirements](https://hivemind.griiken.com/guide/system-requirements.md): Which systems Hivemind runs on, and what each one gets: the app, the hive command, or both.
- [Update and roll back](https://hivemind.griiken.com/guide/update-and-roll-back.md): Update Hivemind from the app or a terminal, switch between stable and nightly builds, and go back to an older release.
- [Uninstall](https://hivemind.griiken.com/guide/uninstall.md): Remove Hivemind from your computer, with or without your settings and saved sessions.