How HiveMind works
You send a message. HiveMind plans the work. Your connected device runs a permitted tool and returns the result.
One conversation, work across your devices
The AI can answer directly or start a background task. A task keeps a record of its steps, permissions, results, and progress. You can keep talking while it works.
Your selected model receives the context needed for a call. Hosting HiveMind yourself does not by itself make that model local. You can connect a hosted service or, as host owner, a compatible local model endpoint.
Grant a folder once
Select a shared folder in the desktop app. Then choose an approval level in HiveMind → Devices → Permissions.
| Level | May proceed without another prompt |
|---|---|
| Ask every time | Nothing on a device. |
| Allow routine reads | Device information, listing the folder, and reading its text files. |
| Allow reads and new files | The read actions plus creating new text files in that folder. |
Basic file tools never replace or delete existing files. A folder change resets the grant. Removed capabilities stay unavailable even when a broader approval level is selected. Old queued work is checked again before dispatch.
Commands, registered agents, and browser actions always need exact approval. Commands and agents must also be enabled locally. By default, the desktop asks again before running a process. In its Access tab, you can choose to accept those approvals through HiveMind instead. That local choice is tied to the server address.
A folder grant confines the basic file tools. It does not sandbox an arbitrary program. An approved command or custom agent runs with your computer user's access.
Each person has their own profile
The host administrator creates a one-use invitation in Settings. Its recipient creates a username and password, connects their own model, and pairs their own devices. Nobody needs the administrator's password.
Members cannot borrow the host's model credentials. API destinations come from the host's allowlist. Password changes invalidate other sessions. The administrator can revoke invitations and disable member accounts without deleting their history.
Know why a task is waiting
A task has one parent ID. Each concrete step has a child ID, action, arguments, approval source, and result. The current planner runs up to eight steps in sequence. Independent tasks can progress at the same time; each device runs one action at a time.
| What you see | What it means |
|---|---|
| Your approval is needed | Review the exact action in HiveMind. |
| Confirm on the computer | The desktop requires local confirmation. The dialog expires after 60 seconds. |
| Waiting for device to reconnect | Open and connect the app; for browser work, keep its popup open. |
| Choosing the next action | The model is planning. The model wait, including its queue, has a time limit. |
| Outcome unconfirmed | The server cannot prove what happened. Inspect before starting a new attempt. |
A device's temporary claim lasts 120 seconds and can only be renewed by naming that active task. Stop shortens the remaining time to at most 30 seconds. A local journal prevents repeat execution if a result acknowledgment is lost. Try again creates a new task; it never happens automatically.
Memory is selected, not unlimited
Recent conversation stays in the next model call. Older conversation becomes summaries linked to original messages. When something looks relevant, HiveMind retrieves summaries or source excerpts. A fact becomes a saved note only when you save or accept it.
Current limits
Up to 12 recent messages; a 24,000-character conversation allowance; up to six recalled records and 6,000 characters. Summaries form from batches of 12 messages, then groups of four summaries.
What to improve
Word matching can miss a memory and summaries can lose details. The Memory team can compare retrieval methods and measure what survives. This is a baseline, not an infinite context window.
Deleting a saved note resets older recall and summaries while leaving visible chat. That conservative reset also drops unrelated recalled history. Task records and backups have separate retention behavior.
What devices can do now
| Connection | Available | Limit |
|---|---|---|
| Desktop | Folder listing, text reading, new text files; optional commands and registered agents. | File tools use a 64 KB text limit. Keep the app running. Commands are broader than folder access. |
| Browser | Open a URL; read an explicitly shared tab. | Popup stays open. Read up to 16,000 characters; no clicking, typing, cookies or forms. |
| Phone | Chat, approvals, settings and task monitoring in the web app. | No native Android/iOS execution harness yet. |
| Cloud | Answers, planning and background writing. | No server shell or filesystem tools. |
The Windows installer is unsigned. The Mac launcher requires Python with Tk. Signed releases and automatic updates remain work for the Infrastructure team.
Disconnect revokes access and removes the device. If offline, the app stops locally and keeps a pending disconnect to retry. Close only pauses it and preserves pairing. After a completed disconnect, use a new pairing code.
Where each team can work
| Team | Main area | Next useful question |
|---|---|---|
| Memory & Context | memory.py | Which retrieval method remembers useful facts without stale or irrelevant recall? |
| Planning & Coordination | coordinator.py | Can we independently verify results, then safely add parallel steps? |
| Models & Local AI | providers.py | Which models plan correctly at an acceptable cost and latency? |
| Tools & Devices | connectors/ | Which next tool is useful, bounded and easy to test? |
| Infrastructure | store.py, profiles.py, packaging | Can a new host install, back up and restore using only the docs? |
| Cybersecurity | Profiles, grants, credential and tool boundaries | Do the boundaries hold under hostile inputs and cross-account requests? |
| Testing & Evaluation | tests/ | Do reported completions match the user's actual goal? |
| User Experience | web/ and installer flow | Can a new user connect a device and understand its permissions unaided? |
Detailed ownership and acceptance checks: subteam handoffs. API shapes: connector contract. Full implementation: architecture. Hosting: operations. Boundaries: security.
Code terms, in plain language
A node is a connected device. A connector is its software. A capability is a named tool. A provider connects the AI model. A coordinator chooses and tracks steps. A lease is a temporary claim on a task. A journal records work locally to avoid executing it twice.