Bring-your-own agents

Hive doesn't ship hardcoded agent personas. Instead, any CLI agent you trust can become a workspace participant. Built-in support for aider and pi; a generic subprocess provider for anything else.

Why BYO?

Aider, pi, Claude Code — these projects each maintain state-of-the-art code-editing agents. Recreating that work inside Hive would mean staying current with a fast-moving field of agent design. Instead, Hive treats them as runtimes: they generate the replies, Hive hosts the conversation, presence, sync, and consent.

Installing an agent

Pick whichever you like:

aiderpiClaude CodeCustom CLI

pip install aider-chat
which aider
# → /usr/local/bin/aider

pip install promptflow
which pi
# → /usr/local/bin/pi

Already supported as provider = "claude-code". Install:

npm install -g @anthropic-ai/claude-code
which claude
# → /usr/local/bin/claude

Any binary that reads a prompt and writes a response. Use provider = "subprocess".

Configuring as a runtime

In Settings → Runtimes → Add Runtime, or directly in TOML:

[[runtimes]]
id = "aider"
name = "Aider"
provider = "aider"
kind = "local"
endpoint = "/usr/local/bin/aider"
preferred_model = "gpt-4o"
supports_tools = true

[[runtimes]]
id = "my-tool"
name = "My custom agent"
provider = "subprocess"
kind = "local"
endpoint = "/path/to/my-binary"
preferred_model = ""

The provider determines how Hive talks to the binary:

Provider	Prompt delivery	Default flags
aider	stdin	interactive CLI; prompt piped in
pi	positional arg (-p … "<prompt>")	-p --no-session --offline --mode text; adds --provider/--model and a temp Ollama provider config when an Ollama base URL is set
subprocess	stdin	none
claude-code	stdin, stream-json	-p --output-format stream-json --include-partial-messages

For agents that need a different invocation, the per-provider wiring lives in crates/hive-runtime/src/provider/dispatch.rs (with the generic spawn/stream helper in subprocess.rs). It supports stdin delivery or final-positional-arg delivery, and bounds each run with a wall-clock timeout (HIVE_AGENT_TIMEOUT_SECS, default 300s).

Attaching to a workspace agent

Configure a WorkspaceAgent that points at the runtime:

# WorkspaceAgent isn't in hive.config.toml — it's in the workspace's
# event log. Easier to add via the People → Workspace Agents UI.

Or via UI: People → Workspace Agents → New Agent:

• Handle: coder (so peers @coder to invoke)
• Runtime: pick aider
• Owner: this device (for runtimes that need your local binary)

Peers can now @coder in chat; Hive routes the message through aider, captures stdout as the reply, and broadcasts the envelope.

Capability banner

When the active runtime is a subprocess agent, the composer area shows a banner:

aider runs as a local subprocess and edits files on this machine itself. Hive captures its stdout as the agent's reply; consent flows still gate any built-in tools Hive offers.

Subprocess agents typically have their own consent UX — aider prompts before each write unless --yes-always is set, Claude Code has its own permission model, etc. Hive's consent layer only gates Hive's own built-in tools when they're invoked by the LLM (not when the agent edits files directly).

Output handling

The bridge captures stdout as the agent's reply. Stderr surfaces as an error if the process exits non-zero. Multi-step flows (aider's "I'll edit these files, do you want me to commit?") just become multi-turn conversations — the user types a reply, Hive sends it again, aider continues from where it left off.

For streaming output (incremental token display), use provider = "claude-code" which has a dedicated streaming bridge, or fork the subprocess bridge to add streaming. Default subprocess mode is whole-stdout-on-completion.

Peer-owned agents

A workspace agent's ownerActorID controls where the runtime runs:

• Empty → runs on whichever device handles the chat.
• Set to a peer's account ID → runs on that peer's device.

The second mode is the killer feature: Bob has Claude Code on his machine with his Pro subscription; you don't have a Claude subscription, but you can still @bob-claude and have Bob's device respond with Claude's output. No credentials cross machines.

Bob has to be online for the invocation to complete. When he's offline, Hive surfaces the message as pending and routes it when he reconnects.

See Agents (built-in vs BYO) for the agent dispatch model in full.