HhiveyDOCUMENTATIONGitHub ↗
HIVEY / DOCUMENTATION

Build agents and teams.
Keep them together.

Hivey is a terminal workspace and an always-on agent that coordinates all your AI agents: solo agents for lasting jobs and swarms where a coordinator directs a team. Tell Hivey the goal and keep every agent and team visible in one place.

01 / GET STARTED

Install Hivey

On an Apple Silicon Mac, install Hivey with npm. You need Node.js and Python 3. The lead agent setup uses Claude Code; configure access to your chosen agents separately.

NPM · APPLE SILICON MAC
npm install -g @hivey/cli
hivey setup
hivey

hivey setup runs once: it installs Hivey’s skills and hooks, links the bundled plugins, and guides you through your agents and optional Slack and pet setup. hivey setup --no-setup skips the questions. hivey update installs the latest version from npm.

On Linux or an Intel Mac, or to change Hivey itself, build it from source. Install Git, Rust/Cargo, Zig 0.16.0, Python 3, and Node.js/npx first.

BUILD FROM SOURCE · macOS + LINUX
git clone https://github.com/alyssaaa11/hivey.git ~/hivey
cd ~/hivey
./install.sh
hivey

The installer builds Hivey, installs its skill, links bundled plugins, and guides you through optional Slack, Obsidian, and macOS pet setup. Run ./install.sh --no-setup to skip the interactive setup. The binary installs to ~/.local/bin/hivey.

Check the installationhivey --versionhivey statushivey plugin list
02 / FIRST RUN

Start your first swarm

Open Hivey from the project folder where the team should work. You can ask the Hivey lead agent to create a team, or launch one directly:

TERMINAL
cd ~/projects/my-project
hivey
hivey swarm new "Research and build my next idea"

For one agent instead of a team, run hivey swarm new --agent "Write my weekly newsletter" from the folder it will live in: the agent creator designs a single agent with its own brief and launches it.

A setup provider designs the team. The bundled /swarm workflow creates a coordinator and agents, gives each a working folder, and opens the swarm in its own space. Run hivey swarm providers to see installed providers.

Press ⌥Q or ctrl+b, then q, to detach. Run hivey again to reattach. Your agents continue while your machine stays awake and connected.

03 / THE MODEL

One lead, many teams

You→Hivey→Swarm coordinator→Agents

Hivey creates and manages swarms. Each swarm has a dedicated coordinator and a separate terminal space. Agents can message teammates; coordinators carry work across swarms. Hivey uses the herdr terminal runtime today.

05 / COMMUNICATION

Talk to your agents

Message a coordinator, an individual agent, or the whole swarm. Normal messages wait until the agent is idle; urgent messages can interrupt active work. History is recorded with the swarm.

TERMINAL
hivey msg send my-swarm/coordinator "How is it going?"
hivey msg send my-swarm/scout "Share your sources"
hivey msg send @all --swarm my-swarm "Please summarize"
hivey msg log --swarm my-swarm
06 / CONTROL

Manage a running swarm

hivey swarm listSee swarms, agents, states, and waiting messages.
hivey swarm info my-swarmInspect agents, integrations, addons, and more.
hivey swarm pause my-swarmHold message delivery while messages continue to queue.
hivey swarm resume my-swarmRelease queued messages.
hivey swarm relaunch my-swarmRestart stopped agents and reopen addons.
07 / AWAY FROM DESK

Slack and scheduled check-ins

With the optional Slack relay connected, talk to Hivey in #hivey and to a swarm’s coordinator in its own channel. The computer running Hivey must stay awake and connected.

Schedule a check to wake an idle coordinator at a useful interval:

TERMINAL
hivey swarm schedule add my-swarm --every 2h "Check progress and report blockers"
hivey swarm schedule list my-swarm
08 / CONTEXT

Keep useful memory

Optionally connect an Obsidian folder during setup. A swarm can maintain a local Markdown wiki for sources, findings, decisions, and reusable lessons. You can inspect and edit the files yourself.

09 / EXTEND

Plugins and skills

Hivey ships a skill that teaches Claude Code and Codex how to operate the workspace. Plugins extend workflows such as swarm creation, dashboards, Slack, GitHub, and agent setup.

TERMINAL
hivey skill install
hivey plugin list
hivey swarm providers

For provider and addon development, see the plugin guide ↗.

10 / KEEP GOING

Update and troubleshoot

Run hivey update to install the latest version: from npm if you installed with npm, otherwise it pulls and rebuilds your checkout. If hivey is not found after a source install, add ~/.local/bin to your shell’s PATH. If Option shortcuts type symbols, set your terminal’s Option key to send Alt/Meta.

For detailed setup, platform notes, and troubleshooting, read the full Hivey guide ↗.