Skip to content

Agents (built-in vs BYO)

Hive's agent model is intentionally thin. The app isn't an agent itself — it hosts agents you bring.

WorkspaceAgent — the user-facing concept

A WorkspaceAgent has three fields:

  • name — what peers @mention (e.g. @coder).
  • runtimeID — which configured runtime drives it.
  • ownerActorID — whose device the runtime lives on ("" = shared).

That's it. The agent isn't a "persona" with hardcoded prompts. It's a pointer: "when someone in this chat says @coder, route the message to runtime aider-runtime on Alice's device."

Configure agents from People → Workspace Agents.

Workspace Agents pane

Why no built-in personas?

Two reasons:

  1. They would duplicate work that aider, pi, and Claude Code already do well. Maintaining a curated set of agent prompts and a multi-stage planning harness inside Hive would mean keeping up with the state-of-the-art in agent design — which is the whole industry. Better to host the agents you bring.
  2. The product story is "bring your own." If your team uses aider for code edits and Claude for reviews, point Hive at those. Hive doesn't need its own Coder.

Bring-your-own agent

Any LLM (API or CLI) becomes a Hive agent via a runtime + a WorkspaceAgent pointing at it.

  1. Configure a runtime anthropic in Settings → Runtimes.
  2. Add a WorkspaceAgent @claude pointing at it.
  3. @claude participates in chats.
  1. pip install aider-chat.
  2. Configure a runtime aider with endpoint = "/usr/local/bin/aider".
  3. Add a WorkspaceAgent @coder pointing at it.
  4. @coder writes code through aider when mentioned.

Bob has Claude Code on his machine; he doesn't want to give you his API key. He configures @bob-claude with ownerActorID = bob. When you @bob-claude in chat:

  1. Hive routes the message to Bob's device over the P2P link.
  2. Bob's instance runs Claude Code locally with his subscription.
  3. The reply flows back through the envelope log.

No credentials leave Bob's machine.

See BYO agents for the full configuration recipe.

Tool capabilities

Different runtimes expose different capabilities. A summary banner appears above the composer when you switch runtimes:

Runtime kind What it can do
API providers Hive's built-in tools (file ops, git, shell, MCP). Consent-gated.
Claude Code Claude Code's own tools + permissions. Bypasses Hive's consent flow because Claude Code has its own.
aider / pi The agent's own internal tools. Hive captures stdout as the reply.
Ollama / hive-daemon Text only (no tool calls in either direction yet).

The banner spells out which bucket a runtime falls into.

Agent dispatch model

When you send a message with no @mention, the message goes to the chat's primary runtime. When you @agent:

  1. Hive emits an agentInvocationRequested event.
  2. If the agent runs on this device, Hive calls the runtime locally.
  3. If the agent runs on a peer's device, Hive routes the envelope through the P2P link.
  4. The reply comes back via an agentInvocationReplied event.

This is the same path whether the peer is on your LAN, across the internet via the rendezvous relay, or in a future relay-routed fallback path.

When an agent tries to write a file or run a command, Hive shows an inline consent banner. The agent is paused until you approve or deny. Approval scopes:

  • Allow once — just this call.
  • Allow for this chat — every call of the same AgentToolKind in this chat runs inline.
  • Allow always — every chat in this workspace.

Trust grants are events too; they sync to peers and survive relaunches.