Hive IDE Docs Introduction

Documentation

Hive IDE is the operator-facing desktop app for agent orchestration. It gives you a single cockpit over a team of autonomous AI coding agents — the in-flight changes they’re producing, the stories they’re working through, and the PRs they’ve opened on your behalf. This guide covers installing it, the concepts behind it, and how to wire it up to a hive.

New here? Read The mental model first — Hive uses a small, consistent vocabulary (requirement, story, worktree, tick, PR) that the whole UI is built around.

Install #

Hive ships as a desktop app for macOS (primary), Windows, and Linux. Grab a build from the releases page, or run it from source.

# macOS — universal .dmg
# Windows — x64 .exe
# Linux — AppImage / .deb
→ github.com/nikrich/hive-ide/releases

Until code-signing secrets are configured, builds ship unsigned. On macOS, right-click the app → Open the first time to bypass Gatekeeper. See Build from source for the signed-release toolchain.

Quickstart #

From a fresh clone, you’re three commands from a running cockpit:

$ git clone https://github.com/nikrich/hive-ide
$ cd hive-ide && npm install
$ npm run dev          # launches Electron on the Vite dev renderer

On first launch Hive opens the Projects hub with seed mock data behind a “Hive not connected” ribbon, so you can explore every surface before wiring up a real hive. When you’re ready, connect a workspace.

The mental model #

Where a normal IDE shows you your files and your changes, Hive shows you everything the hive is doing. A handful of nouns recur across every panel — learn these and the whole UI reads naturally.

requirement

A high-level ask in plain English. Gets a stable ID like REQ-001.

story

A point-scored unit of work decomposed from a requirement. STORY-002, “3 pts”.

agent / worker

An AI team member with a role. Spawned to take a story, reaped when done.

worktree & branch

Each worker gets an isolated git worktree on its own branch agent/<team>--<role>-<id>.

tick

One iteration of the Manager’s supervision loop — drain inbox, spawn, reap, escalate.

escalation & finding

A blocker raised for the human, or a note an agent recorded into team memory.

Status verbs are consistent too: running, pending, in review, blocked, merged, done. The same word means the same thing in the log, the roster, and the PR list.

The agent team #

Hive models a real agile team. Each role maps to a default model and a complexity band, so stories flow to an agent sized for the work.

Role	Default model	Responsibility
Manager	`orchestrator`	Drains the inbox, spawns & reaps workers, re-pends and escalates.
Tech Lead	`Claude Opus`	Decomposes requirements into sized stories with dependencies.
Senior	`Claude Sonnet`	Complex stories (6+ pts), code review, mentors juniors.
Intermediate	`Claude Haiku`	Medium stories (4–5 pts).
Junior	`GPT-4o-mini`	Simple stories (1–3 pts).
QA	`Claude Sonnet`	Lint, types, tests, build — approves PRs.

The core loop #

The whole system is one pipeline, visualised live in the IDE:

requirement → stories (point-scored) → assigned to agents
            → worktree + branch → commits → review → QA → PR

You add a requirement; it enters the Manager’s inbox.
On the next tick, the Tech Lead decomposes it into stories with dependencies.
The Manager spawns a worker per ready story into a fresh worktree.
Workers edit, commit, and push; you watch diffs stream live.
Seniors review and QA gates lint, types, tests, and the build.
On green, Hive opens a PR for you to merge.

Team memory & state #

Orchestration state is files on disk — the single source of truth. State lives under the workspace as markdown-with-frontmatter plus an append-only event log, organised into drawers:

.hive/
  state/
    requirements/   # REQ-*.md
    stories/        # STORY-*.md  (status in frontmatter)
    agents/         # live worker status
    escalations/    # blockers raised for the human
    findings/       # notes agents recorded
  events.ndjson     # append-only event stream

Because state is file-backed, the IDE’s file watcher makes the live viewer fall out for free: an agent writes stories/AUTH-3.md → the watcher fires → the board updates. No daemon, no database to keep in sync.

Semantic memory (the optional mempalace enrichment) is a separate concern from the orchestration spine — you don’t need vector search to know a story is pending.

Connect a hive workspace #

A workspace is a directory that holds .hive/ plus the team’s repo clones under repos/. The IDE remembers which workspace belongs to each project.

Open the project you want to orchestrate.
From the command palette (⌘ K), run “Connect hive workspace…”.
Point at an existing workspace directory. The Run, Stories, and PRs surfaces switch from seed data to live state.

The status bar shows the heartbeat once connected: agents live, the next tick countdown, and mempalace · synced. If you see a “Hive not connected” ribbon, you’re still on seed data.

Reading the cockpit #

The window is laid out like an IDE, with orchestration surfaces woven in:

Activity rail (far left) — Explorer, Projects hub, Pull requests, Team memory.
Explorer + editor — your files; open one an agent owns and it streams read-only.
Agent dock (right) — the active Run, the Stories board, and a Chat with the team.
Bottom panel — manager.log, Problems, and an integrated Terminal.
Status bar — branch, live agent count, next tick, memory sync, active model.

Keyboard shortcuts #

Hive is keyboard-first. The essentials:

Shortcut	Action
`⌘` `K`	Open the command palette — files, projects, agents, actions.
`⌘` `S`	Save the active file.
`⌘` `J`	Toggle the bottom panel (log / problems / terminal).
`⌘` `P`	Quick-open a file by name.
`⌘` `B`	Toggle the Explorer sidebar.
`Esc`	Dismiss the palette or any open overlay.

On Windows and Linux, use Ctrl in place of ⌘.

Build from source #

The renderer is React 18 + TypeScript; the shell is Electron via electron-vite. Workers run as claude --print subprocesses through node-pty.

$ npm install
$ npm run dev          # dev: Electron + Vite renderer
$ npm run typecheck     # tsc -b --noEmit
$ npm test              # vitest
$ npm run build:mac     # → release/<version>/Hive IDE-*.dmg

Releases are automated: conventional-commit messages (feat:, fix:, …) on main drive release-please, which opens a Release PR. Merging it cuts a GitHub Release and triggers the workflow that packages macOS, Windows, and Linux installers.

Signing is opt-in via repository secrets — Developer ID + notarization for macOS, Azure Trusted Signing for Windows. Until those are set, packaged builds are unsigned but fully functional.

Troubleshooting #

“Hive not connected” ribbon won’t go away

You’re still on seed data. Run Connect hive workspace… from the palette and point at a directory containing .hive/.

node-pty fails to load after install

It’s a native module. Re-run the post-install rebuild: npm run postinstall (which runs electron-rebuild --only node-pty).

macOS won’t open the app

Unsigned build — right-click the app and choose Open once, or clear the quarantine attribute with xattr -dr com.apple.quarantine.

← Back

Landing page

The repo on GitHub