hivemind

<div align="center">

<img src="assets/icon.png" width="116" alt="hivemind" />

# hivemind

**A canvas-per-project mission control for AI coding agents.**

Drop `claude`, `codex`, `gemini`, `opencode`, or `pi` into real workspaces where they can
read issues, update status, mark acceptance criteria, and comment their own
progress — through a Kanban PM model that's just plain markdown on disk.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Platform: Linux](https://img.shields.io/badge/platform-Linux%20x86__64-blue.svg)](#install)
[![Release](https://img.shields.io/github/v/release/dip497/hivemind?color=success)](https://github.com/dip497/hivemind/releases)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6.svg)](#)

Local-first · Markdown-backed · No SDK lock-in · No telemetry · No cloud.

<br/>

<img src="screenshots/diff.png" alt="hivemind — an issues board and a live diff of an agent's fix, side by side on one canvas" width="880" />

<sub>An issue board and the live diff of a fix, side by side on one infinite canvas. The agent edits; the diff updates as you watch.</sub>

</div>

---

## Contents

[Why](#why) · [The whole canvas](#the-whole-canvas) · [Install](#install) · [Quick start](#quick-start) · [How agents talk to hivemind](#how-agents-talk-to-hivemind) · [Features](#features) · [Architecture](#architecture) · [Persistence](#persistence-model) · [Development](#development) · [Contributing](#contributing)

---

## Why

Running a coding agent in a bare terminal throws away everything around the work.
You lose track of *which* task it's on, you can't see its edits without `git diff`,
the conversation dies when you close the window, and the moment you want a second
agent on a second branch you're juggling tmux panes.

hivemind makes the **project** the unit of work, not the terminal. One infinite
canvas per repo. Every tile on it is live — a terminal running an agent, a diff
that updates as the agent edits, a file tree, a code editor, an issues board, even
a real web browser. Group tiles into **frames** (named workspaces), bind each frame
to a local repo, a git **worktree**, or a **remote SSH host**, and watch several
agents work in parallel — each scoped to its own directory, issues, and branch.

The project-management layer underneath is deliberately boring: issues, acceptance
criteria, cycles, and an activity log are **plain markdown files with YAML
frontmatter** under `.hivemind/`. No database, no API, no account. An agent reads
and writes them through a small MCP server, so it can pick up an issue, flip its
state, tick acceptance criteria, and comment its progress — and you see all of it
land live in the board tile.

---

## The whole canvas

<div align="center">
<img src="screenshots/canvas.png" alt="The full hivemind canvas — issues board, code editor, diff, and two agent terminals" width="880" />
</div>

<table>
  <tr>
    <td width="50%"><img src="screenshots/board.png" alt="Kanban issues board backed by markdown" /><br/><sub><b>Issues board</b> — Kanban cards across Backlog → Todo → In&nbsp;progress → In&nbsp;review → Done. Each card is one markdown file you can <code>cat</code>.</sub></td>
    <td width="50%"><img src="screenshots/explorer.png" alt="File explorer and diff tiles side by side" /><br/><sub><b>Explorer + diff</b> — browse the tree, open files in the editor, and review changes in the Pierre-backed diff — all on the same canvas.</sub></td>
  </tr>
  <tr>
    <td width="50%"><img src="screenshots/diff.png" alt="Live diff with a real bug fix" /><br/><sub><b>Live diff</b> — split or unified, changed-files sidebar, per-file <b>reviewed</b> checks, line comments you can send straight to an agent.</sub></td>
    <td width="50%"><img src="screenshots/new-issue.png" alt="New issue modal" /><br/><sub><b>Create an issue</b> — it lives at <code>.hivemind/issues/&lt;id&gt;.md</code>, then hand it to an agent with <b>▶ Work</b>.</sub></td>
  </tr>
</table>

**60-second tour**

1. `hivemind .` in any repo → an infinite canvas opens, scoped to that project.
2. Press `2` (or a frame's **+**) → an agent tile spawns, running in the repo's `cwd`.
3. Click **▶ Work** on an issue → the agent spawns pre-loaded with that issue and the
   full MCP tool surface; it works, you watch the diff update live.
4. Click a frame's **worktree** button to spin a branch into a nested sub-frame, or
   **remote** to bind the frame to a directory on an SSH host — same terminals,
   editor, and diff, now running on that machine.

---

## Install

Linux x86_64 only for now. **No build toolchain needed** — the installer downloads
prebuilt binaries from the latest [GitHub Release](https://github.com/dip497/hivemind/releases).

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/dip497/hivemind/main/install.sh)
```

The script will:

1. Resolve the latest release tag from GitHub.
2. Download the `hive` CLI single-binary and the Electron AppImage into `~/.hivemind

... (truncated)