jido_hive

jido_hive is a human-plus-AI collaboration system built as a non-umbrella Elixir monorepo.

The governing rule is simple:

• jido_hive_server owns room truth
• jido_hive_client owns reusable operator and room-session behavior
• jido_hive_surface owns the UI-neutral operator surface over the client seam
• jido_hive_worker_runtime owns relay workers and local assignment execution
• Switchyard packages and the Phoenix web app consume that shared surface; they do not redefine it

If a room behavior cannot be reproduced from the headless client surface, the seam is still wrong.

Repo layout

This repo currently contains:

• core/skill_contracts ref-only skill manifest, capability binding, composition, version, and invocation contracts for governed AI skill bundles
• core/skill_engine memory-default skill admission, versioning, bounded composition, and invocation gate logic
• core/agent_coordinator workflow-scoped spawn, handoff, cancel, and supervise contracts for governed agents
• core/inter_agent_messaging bounded inter-agent message contracts with tenant, authority, budget, and trace gates
• core/shared_memory_facade explicit shared-memory grants over governed memory scopes
• core/coordination_patterns bounded orchestrator-worker, debate, consensus, and hierarchical decomposition pattern contracts
• conformance_contracts/skill_conformance_contracts external-author ExUnit helpers that validate safe skill manifests without importing runtime internals
• jido_hive_server authoritative room engine, REST API, websocket room transport, persistence, and connector state
• jido_hive_client headless operator API, JSON CLI, and room-scoped local session boundary
• jido_hive_surface UI-neutral operator workflows for room CRUD, room workspace, provenance, and run-control flows over jido_hive_client
• jido_hive_publications explicit publication planning, execution, persistence, and publication UI models over canonical room resources
• jido_hive_worker_runtime long-lived relay worker runtime, local executor stack, worker CLI, and worker control API
• jido_hive_switchyard_site Jido Hive resource/action mapping over generic Switchyard contracts
• jido_hive_switchyard_tui Jido Hive operator workflow integrated through the generic Switchyard component runtime
• jido_hive_web Phoenix LiveView browser UI over the same shared operator surface
• examples/jido_hive_console runnable composition layer and smoke helper over the Switchyard-backed Jido Hive TUI
• the root workspace project shared quality gates and monorepo tooling

Start with this file, then the package READMEs.

Quick start

Setup

bin/setup

Local runtime

Start the server:

bin/live-demo-server

Start at least two workers in separate shells:

bin/client-worker --worker-index 1
bin/client-worker --worker-index 2

Or use the helper menus:

bin/hive-control
bin/hive-clients

Local operator console

cd examples/jido_hive_console
mix deps.get
mix escript.build
./hive console --local --participant-id alice --debug

Local web UI

cd jido_hive_web
mix setup
mix phx.server

Then open http://127.0.0.1:4100/rooms.

Headless operator CLI

cd jido_hive_client
mix deps.get
mix escript.build

./jido_hive_client room list --api-base-url http://127.0.0.1:4000/api
./jido_hive_client room show --api-base-url http://127.0.0.1:4000/api --room-id <room-id>
./jido_hive_client room workflow --api-base-url http://127.0.0.1:4000/api --room-id <room-id>
./jido_hive_client room focus --api-base-url http://127.0.0.1:4000/api --room-id <room-id>
./jido_hive_client room inspect --api-base-url http://127.0.0.1:4000/api --room-id <room-id>
./jido_hive_client room provenance --api-base-url http://127.0.0.1:4000/api --room-id <room-id> --context-id <context-id>
./jido_hive_client room submit --api-base-url http://127.0.0.1:4000/api --room-id <room-id> --participant-id alice --text "hello"

Production shortcuts

bin/hive-control --prod
bin/hive-clients --prod

Architecture at a glance

flowchart LR
    subgraph Operator[Operator surfaces]
      Headless[Headless CLI]
      Session[RoomSession consumers]
      TUI[Switchyard-backed TUI]
      Web[Phoenix LiveView UI]
      Setup[setup/hive and helper scripts]
    end

    subgraph Client[jido_hive_client]
      OperatorAPI[JidoHiveClient.Operator]
      RoomSession[JidoHiveClient.RoomSession]
      Embedded[JidoHiveClient.Embedded]
    end

    subgraph Surface[jido_hive_surface]
      SurfaceRooms[JidoHiveSurface room workflows]
    end

    subgraph Publications[jido_hive_publications]
      PublishSurface[JidoHivePublications publication workflows]
    end

    subgraph Workers[jido_hive_worker_runtime]
      WorkerCLI[worker CLI]
      RelayWorker[relay worker]
      Executor[executor stack]
    end

    subgraph Server[jido_hive_server]
      API[REST API]
      Relay[websocket relay]
      Rooms[room reducer and snapshots]
      Connectors[connector state]
    end

    Headless --> OperatorAPI
    Headless --> RoomSession
    Session --> RoomSession
    TUI --> SurfaceRooms
    TUI --> PublishSurface
    Web --> SurfaceRooms
    Web --> PublishSurface
    Setup --> API
    SurfaceRooms --> OperatorAPI
    PublishSurface --> OperatorAPI
    PublishSurface --> Connectors
    Web --> RoomSession
    RoomSession --> Embedded
    OperatorAPI --> API
    Embedded --> API
    WorkerCLI --> RelayWorker
    RelayWorker --> Relay
    Relay --> Rooms
    API --> Rooms
    RelayWorker --> Executor

Loading

Practical model

• the server decides what the room is
• the client reads and mutates that truth through reusable operator/session seams
• the shared surface turns that seam into UI-neutral room workflows
• optional extensions such as jido_hive_publications layer publication behavior on top of canonical room resources
• the worker runtime executes assignments and publishes structured results
• the Switchyard-backed TUI and the Phoenix web UI both render those seams interactively
• the example console is only a runnable composition layer

Governed authority boundary

Standalone helpers and local demos can keep using explicit CLI flags, local config, and documented operator tokens at boot boundaries. Governed worker and connector paths do not use those inputs as authority. A governed worker launch must provide a governed authority ref, worker ref, and credential ref; provider selection, model selection, control endpoint settings, and credential refs are materialized from that packet and direct singleton/default fields are rejected.

Server connector endpoints accept a governed connector authority packet for install and completion flows. In governed mode raw secrets, direct secret sources, manual token fields, OAuth state fields, and direct identity overrides are rejected at the HTTP boundary. Connector completion stores external secret refs and opaque credential refs only; raw materialized values are not projected into responses, logs, snapshots, or docs.

Product model

What is unique here is not the transcript or the websocket transport. It is the combination of:

• server-owned workflow truth
• a typed shared context graph with provenance, contradiction, and canonical signals
• the same room model exposed through API, headless CLI, and TUI
• explicit extension packages for graph projection and publication workflows

Package guide

• core/agent_coordinator/README.md workflow-scoped spawn, handoff, cancel, and supervision contracts
• core/inter_agent_messaging/README.md bounded inter-agent message routing contracts
• core/shared_memory_facade/README.md explicit shared-memory grants over governed memory scopes
• core/coordination_patterns/README.md bounded reusable multi-agent pattern contracts
• core/skill_contracts/README.md ref-only skill manifest and invocation contracts
• core/skill_engine/README.md memory-default skill admission and invocation gate logic
• docs/persistence.md repo-level persistence tiers, owner scopes, and restart claims
• docs/product_no_bypass.md product-surface scan scope and store-owner package exclusions
• conformance_contracts/skill_conformance_contracts/README.md external-author skill conformance helpers
• jido_hive_server/README.md server truth, routes, publications, deployment
• jido_hive_client/README.md operator API, room session boundary, headless CLI
• jido_hive_surface/README.md UI-neutral operator surface for TUI and web presentation packages
• jido_hive_publications/README.md explicit publication extension over canonical room resources
• jido_hive_worker_runtime/README.md relay workers, executor stack, worker CLI
• jido_hive_switchyard_site/README.md Jido Hive site adapter for Switchyard
• jido_hive_switchyard_tui/README.md Jido Hive operator workflow on the Switchyard component runtime
• jido_hive_web/README.md Phoenix LiveView browser UI over the shared operator surface
• examples/jido_hive_console/README.md runnable console composition layer

Developer workflow

Run repo-wide quality gates from the repo root:

mix ci

Useful workspace shortcuts:

mix mr.deps.get
mix mr.format
mix mr.compile
mix mr.test
mix mr.credo
mix mr.dialyzer
mix mr.docs

Debugging order

Always debug in this order:

1. server truth
2. headless jido_hive_client
3. worker runtime only if the bug is assignment delivery or local execution
4. Switchyard-backed TUI
5. example composition layer

Representative first checks:

setup/hive server-info
curl -sS http://127.0.0.1:4000/api/rooms/<room-id> | jq
curl -sS http://127.0.0.1:4000/api/rooms/<room-id>/events | jq

Then reproduce headlessly:

cd jido_hive_client
mix escript.build

./jido_hive_client room show --api-base-url http://127.0.0.1:4000/api --room-id <room-id>
./jido_hive_client room tail --api-base-url http://127.0.0.1:4000/api --room-id <room-id>
./jido_hive_client room submit --api-base-url http://127.0.0.1:4000/api --room-id <room-id> --participant-id alice --text "debug probe"

Only after that should you open the TUI:

cd examples/jido_hive_console
mix escript.build
./hive console --local --participant-id alice --debug --room-id <room-id>

For the detailed triage sequence, read docs/debugging_guide.md.

Other guides

• docs/architecture.md
• docs/debugging_guide.md
• setup/README.md
• docs/developer/multi_agent_round_robin.md

License

MIT

Persistence Documentation

See docs/persistence.md for tiers, defaults, adapters, unsupported selections, config examples, restart claims, durability claims, debug sidecar behavior, redaction guarantees, migration or preflight behavior, and no-bypass scope when applicable.