{"id":49504944,"url":"https://github.com/nshkrdotcom/jido_hive","last_synced_at":"2026-05-01T14:34:24.814Z","repository":{"id":349243786,"uuid":"1193199440","full_name":"nshkrdotcom/jido_hive","owner":"nshkrdotcom","description":"Phoenix coordination server and embeddable Elixir client for augmented human-AI telepathy. Transforms multiplayer terminal chat into live, room-scoped structured context graphs and actionable consensus workflows.","archived":false,"fork":false,"pushed_at":"2026-04-12T03:16:57.000Z","size":10299,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-12T03:28:54.232Z","etag":null,"topics":["actor-model","asm","client-server","concurrency","coordination","distributed-systems","elixir","elixir-otp","event-driven","execution-engine","llm-workflows","local-execution","multi-agent","nshkr-ai-agents","phoenix","real-time","relay","room-management","round-robin","websocket"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nshkrdotcom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-27T01:16:57.000Z","updated_at":"2026-04-12T03:17:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nshkrdotcom/jido_hive","commit_stats":null,"previous_names":["nshkrdotcom/jido_hive"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nshkrdotcom/jido_hive","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fjido_hive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fjido_hive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fjido_hive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fjido_hive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nshkrdotcom","download_url":"https://codeload.github.com/nshkrdotcom/jido_hive/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fjido_hive/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32501403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actor-model","asm","client-server","concurrency","coordination","distributed-systems","elixir","elixir-otp","event-driven","execution-engine","llm-workflows","local-execution","multi-agent","nshkr-ai-agents","phoenix","real-time","relay","room-management","round-robin","websocket"],"created_at":"2026-05-01T14:34:23.982Z","updated_at":"2026-05-01T14:34:24.802Z","avatar_url":"https://github.com/nshkrdotcom.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/jido_hive.svg\" alt=\"jido_hive logo\" width=\"200\"/\u003e\n\u003c/p\u003e\n\n# jido_hive\n\n`jido_hive` is a human-plus-AI collaboration system built as a non-umbrella\nElixir monorepo.\n\nThe governing rule is simple:\n\n- `jido_hive_server` owns room truth\n- `jido_hive_client` owns reusable operator and room-session behavior\n- `jido_hive_surface` owns the UI-neutral operator surface over the client seam\n- `jido_hive_worker_runtime` owns relay workers and local assignment execution\n- Switchyard packages and the Phoenix web app consume that shared surface; they\n  do not redefine it\n\nIf a room behavior cannot be reproduced from the headless client surface, the\nseam is still wrong.\n\n## Repo layout\n\nThis repo currently contains:\n\n- `jido_hive_server`\n  authoritative room engine, REST API, websocket room transport, persistence,\n  and connector state\n- `jido_hive_client`\n  headless operator API, JSON CLI, and room-scoped local session boundary\n- `jido_hive_surface`\n  UI-neutral operator workflows for room CRUD, room workspace, provenance, and\n  run-control flows over `jido_hive_client`\n- `jido_hive_publications`\n  explicit publication planning, execution, persistence, and publication UI\n  models over canonical room resources\n- `jido_hive_worker_runtime`\n  long-lived relay worker runtime, local executor stack, worker CLI, and worker\n  control API\n- `jido_hive_switchyard_site`\n  Jido Hive resource/action mapping over generic Switchyard contracts\n- `jido_hive_switchyard_tui`\n  Jido Hive operator workflow integrated through the generic Switchyard\n  component runtime\n- `jido_hive_web`\n  Phoenix LiveView browser UI over the same shared operator surface\n- `examples/jido_hive_console`\n  runnable composition layer and smoke helper over the Switchyard-backed Jido\n  Hive TUI\n- the root workspace project\n  shared quality gates and monorepo tooling\n\nStart with this file, then the package READMEs.\n\n## Quick start\n\n### Setup\n\n```bash\nbin/setup\n```\n\n### Local runtime\n\nStart the server:\n\n```bash\nbin/live-demo-server\n```\n\nStart at least two workers in separate shells:\n\n```bash\nbin/client-worker --worker-index 1\nbin/client-worker --worker-index 2\n```\n\nOr use the helper menus:\n\n```bash\nbin/hive-control\nbin/hive-clients\n```\n\n### Local operator console\n\n```bash\ncd examples/jido_hive_console\nmix deps.get\nmix escript.build\n./hive console --local --participant-id alice --debug\n```\n\n### Local web UI\n\n```bash\ncd jido_hive_web\nmix setup\nmix phx.server\n```\n\nThen open `http://127.0.0.1:4100/rooms`.\n\n### Headless operator CLI\n\n```bash\ncd jido_hive_client\nmix deps.get\nmix escript.build\n\n./jido_hive_client room list --api-base-url http://127.0.0.1:4000/api\n./jido_hive_client room show --api-base-url http://127.0.0.1:4000/api --room-id \u003croom-id\u003e\n./jido_hive_client room workflow --api-base-url http://127.0.0.1:4000/api --room-id \u003croom-id\u003e\n./jido_hive_client room focus --api-base-url http://127.0.0.1:4000/api --room-id \u003croom-id\u003e\n./jido_hive_client room inspect --api-base-url http://127.0.0.1:4000/api --room-id \u003croom-id\u003e\n./jido_hive_client room provenance --api-base-url http://127.0.0.1:4000/api --room-id \u003croom-id\u003e --context-id \u003ccontext-id\u003e\n./jido_hive_client room submit --api-base-url http://127.0.0.1:4000/api --room-id \u003croom-id\u003e --participant-id alice --text \"hello\"\n```\n\n### Production shortcuts\n\n```bash\nbin/hive-control --prod\nbin/hive-clients --prod\n```\n\n## Architecture at a glance\n\n```mermaid\nflowchart LR\n    subgraph Operator[Operator surfaces]\n      Headless[Headless CLI]\n      Session[RoomSession consumers]\n      TUI[Switchyard-backed TUI]\n      Web[Phoenix LiveView UI]\n      Setup[setup/hive and helper scripts]\n    end\n\n    subgraph Client[jido_hive_client]\n      OperatorAPI[JidoHiveClient.Operator]\n      RoomSession[JidoHiveClient.RoomSession]\n      Embedded[JidoHiveClient.Embedded]\n    end\n\n    subgraph Surface[jido_hive_surface]\n      SurfaceRooms[JidoHiveSurface room workflows]\n    end\n\n    subgraph Publications[jido_hive_publications]\n      PublishSurface[JidoHivePublications publication workflows]\n    end\n\n    subgraph Workers[jido_hive_worker_runtime]\n      WorkerCLI[worker CLI]\n      RelayWorker[relay worker]\n      Executor[executor stack]\n    end\n\n    subgraph Server[jido_hive_server]\n      API[REST API]\n      Relay[websocket relay]\n      Rooms[room reducer and snapshots]\n      Connectors[connector state]\n    end\n\n    Headless --\u003e OperatorAPI\n    Headless --\u003e RoomSession\n    Session --\u003e RoomSession\n    TUI --\u003e SurfaceRooms\n    TUI --\u003e PublishSurface\n    Web --\u003e SurfaceRooms\n    Web --\u003e PublishSurface\n    Setup --\u003e API\n    SurfaceRooms --\u003e OperatorAPI\n    PublishSurface --\u003e OperatorAPI\n    PublishSurface --\u003e Connectors\n    Web --\u003e RoomSession\n    RoomSession --\u003e Embedded\n    OperatorAPI --\u003e API\n    Embedded --\u003e API\n    WorkerCLI --\u003e RelayWorker\n    RelayWorker --\u003e Relay\n    Relay --\u003e Rooms\n    API --\u003e Rooms\n    RelayWorker --\u003e Executor\n```\n\n### Practical model\n\n- the server decides what the room is\n- the client reads and mutates that truth through reusable operator/session seams\n- the shared surface turns that seam into UI-neutral room workflows\n- optional extensions such as `jido_hive_publications` layer publication\n  behavior on top of canonical room resources\n- the worker runtime executes assignments and publishes structured results\n- the Switchyard-backed TUI and the Phoenix web UI both render those seams\n  interactively\n- the example console is only a runnable composition layer\n\n### Product model\n\nWhat is unique here is not the transcript or the websocket transport. It is the\ncombination of:\n\n- server-owned workflow truth\n- a typed shared context graph with provenance, contradiction, and canonical\n  signals\n- the same room model exposed through API, headless CLI, and TUI\n- explicit extension packages for graph projection and publication workflows\n\n## Package guide\n\n- [jido_hive_server/README.md](jido_hive_server/README.md)\n  server truth, routes, publications, deployment\n- [jido_hive_client/README.md](jido_hive_client/README.md)\n  operator API, room session boundary, headless CLI\n- [jido_hive_surface/README.md](jido_hive_surface/README.md)\n  UI-neutral operator surface for TUI and web presentation packages\n- [jido_hive_publications/README.md](jido_hive_publications/README.md)\n  explicit publication extension over canonical room resources\n- [jido_hive_worker_runtime/README.md](jido_hive_worker_runtime/README.md)\n  relay workers, executor stack, worker CLI\n- [jido_hive_switchyard_site/README.md](jido_hive_switchyard_site/README.md)\n  Jido Hive site adapter for Switchyard\n- [jido_hive_switchyard_tui/README.md](jido_hive_switchyard_tui/README.md)\n  Jido Hive operator workflow on the Switchyard component runtime\n- [jido_hive_web/README.md](jido_hive_web/README.md)\n  Phoenix LiveView browser UI over the shared operator surface\n- [examples/jido_hive_console/README.md](examples/jido_hive_console/README.md)\n  runnable console composition layer\n\n## Developer workflow\n\nRun repo-wide quality gates from the repo root:\n\n```bash\nmix ci\n```\n\nUseful workspace shortcuts:\n\n```bash\nmix mr.deps.get\nmix mr.format\nmix mr.compile\nmix mr.test\nmix mr.credo\nmix mr.dialyzer\nmix mr.docs\n```\n\n## Debugging order\n\nAlways debug in this order:\n\n1. server truth\n2. headless `jido_hive_client`\n3. worker runtime only if the bug is assignment delivery or local execution\n4. Switchyard-backed TUI\n5. example composition layer\n\nRepresentative first checks:\n\n```bash\nsetup/hive server-info\ncurl -sS http://127.0.0.1:4000/api/rooms/\u003croom-id\u003e | jq\ncurl -sS http://127.0.0.1:4000/api/rooms/\u003croom-id\u003e/events | jq\n```\n\nThen reproduce headlessly:\n\n```bash\ncd jido_hive_client\nmix escript.build\n\n./jido_hive_client room show --api-base-url http://127.0.0.1:4000/api --room-id \u003croom-id\u003e\n./jido_hive_client room tail --api-base-url http://127.0.0.1:4000/api --room-id \u003croom-id\u003e\n./jido_hive_client room submit --api-base-url http://127.0.0.1:4000/api --room-id \u003croom-id\u003e --participant-id alice --text \"debug probe\"\n```\n\nOnly after that should you open the TUI:\n\n```bash\ncd examples/jido_hive_console\nmix escript.build\n./hive console --local --participant-id alice --debug --room-id \u003croom-id\u003e\n```\n\nFor the detailed triage sequence, read\n[docs/debugging_guide.md](docs/debugging_guide.md).\n\n## Other guides\n\n- [docs/architecture.md](docs/architecture.md)\n- [docs/debugging_guide.md](docs/debugging_guide.md)\n- [setup/README.md](setup/README.md)\n- [docs/developer/multi_agent_round_robin.md](docs/developer/multi_agent_round_robin.md)\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnshkrdotcom%2Fjido_hive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnshkrdotcom%2Fjido_hive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnshkrdotcom%2Fjido_hive/lists"}