The Problem

Coordinating several CLI agents on a single machine is brittle: long‑running sessions scatter across terminals, progress is lost in scrollback, and there is no central dispatcher to allocate tasks, collect reports, or resume work after a crash. Hive adds a “team shell” layer that keeps each agent as a real PTY process while providing a shared task file (<workspace>/.hive/tasks.md) and a protocol (team) for the orchestrator to spawn, assign, and collect work from workers.

What This Does

Hive is a browser‑native dashboard (React, Vite) that orchestrates genuine CLI agents. The backend lives in src/server/; the UI in web/src/. Key files:

  • src/server/app.ts – starts the HTTP server (createApp, sendStatic) and wires routes.
  • src/server/agent-manager.ts together with src/server/agent-manager-support.ts – creates and manages agent runtimes; the two files form a circular import (high‑severity soundness finding).
  • web/src/i18n.tsx – i18n provider (getInitialLanguage, readStoredLanguage, writeStoredLanguage) called from 42 other modules (hub‑module finding).
  • web/src/api.ts – defines fromPayload, readErrorMessage, initializeUiSession, etc., called from 10 modules and four internal subsystems.
  • src/server/workspace-shell-runtime.ts (start at line 186) – the entry point that reaches 101 functions and itself is called from two places.

The internal call graph shows useI18n invoked from 52 places, resolve from 31, and apiFetch from 28, indicating high‑traffic hubs that any change ripples through.

How It Is Wired

Execution starts at start in src/server/workspace-shell-runtime.ts:186, which calls startAgent → deleteWorker → getWorkspace → hydrateWorkspaceFromDb – a shortest path that touches the database (db.prepare('SELECT id, name, path FROM workspaces …')). A typical run follows run → syncRun → syncPersistedRun → updatePersistedRun (db.prepare('UPDATE agent_runs SET status = ?, exit_co…')).

Outbound effects: 42 functions read/write a SQLite database, 5 make network calls (e.g., API fetches), and 1 reads/writes files (workspace task markdown). The module graph contains 387 internal modules with 924 import edges and two circular dependencies (src/server/agent-manager.ts ↔ src/server/agent-manager-support.ts). Hubs such as src/shared/types.ts (63 importers) and web/src/api.ts (46 importers) have wide blast radius; any modification there risks many downstream files.

How To Use It

  • Setup: npm install -g @tt-a1i/hive (or pnpm add -g @tt-a1i/hive). The lockfile (pnpm-lock.yaml) and package.json guarantee reproducible installs.
  • Configuration: No explicit env‑var file is committed; the server reads process.env.HIVE_PORT (default 3000) and expects a supported agent CLI (claude, codex, gemini, etc.) on PATH.
  • Running it: hive launches the backend PTY server and opens http://127.0.0.1:3000/ in the browser. Specify a port with hive --port 4010. The first run creates <workspace>/.hive/tasks.md and starts the orchestrator PTY, injecting the team protocol.
  • PWA install: Open http://127.0.0.1:3000/ in Chromium‑based browser and click the install icon; the UI shell is standalone but the backend must stay running.

Real‑World Use

A team lead opens Hive, selects a project folder as workspace, chooses the “code‑review” orchestrator preset, adds three workers (codex, gemini, opencode). The orchestrator writes a markdown task into .hive/tasks.md and sends team send codex "refactor auth flow". Each worker runs in its own PTY, reports back with team report, and the orchestrator aggregates progress on the dashboard. When the lead closes the tab, Hive prompts a native confirm‑close to preserve the session state.

Code Health & Issues

  • Measured static‑analysis (43 findings): 10 high, 33 medium.
  • High: import‑cycle member (src/server/agent-manager.ts, src/server/agent-manager-support.ts); hub modules (src/shared/types.ts, web/src/api.ts, web/src/i18n.tsx); duplicated code blocks (689 repeated 6‑line patterns across 134 files).
  • Medium: six oversized files (>750 lines), nine files with high branching density, ten files with deep nesting (max indent 6).
  • SDLC observations:
  • High – Pin third‑party GitHub Actions to commit SHA (.github/workflows); currently pnpm/action-setup@v6.
  • Medium – Enable Dependabot/Renovate (no bot configured).
  • Medium – Gate PRs on dependency vulnerability scan (absent from CI).
  • Medium – Set persist-credentials: false on checkout (release workflow keeps token).
  • Medium – Review post‑install lifecycle script; consider disabling scripts in CI.
  • Low – Add timeout-minutes to workflow jobs (release.yml has no job timeout).

The Bottom Line

Hive provides a practical “team shell” for running multiple real CLI agents from a single browser UI, with clear entry points and a well‑mapped call graph. The codebase is sizable (≈850 files) and contains several high‑impact hotspots—most notably the import cycle and hub modules—that merit refactoring before large‑scale extensions. It is well suited for teams that already rely on CLI agents and need coordinated task dispatch, progress tracking, and session persistence without replacing their existing tools.