Terminal agent harness with an in-code protocol (typed events, tool registry, supervisor/worker IPC), OpenAI-compatible local models (Ollama, vLLM, LM Studio, etc.), and a React + Ink TUI with a cyberpunk-style HUD (workspace/API/session chrome and neon accents).
Published packages — @awi-24/core, @awi-24/tui, and @awi-24/hivemind-cli — are versioned together (currently 0.1.3). The installable CLI on npm is @awi-24/hivemind-cli; the shell command is hivemind.
| Area | Package / tech |
|---|---|
| Runtime | Node 18+ |
| Core | TypeScript, Zod — @awi-24/core |
| TUI | React + Ink — @awi-24/tui |
| CLI | Commander — @awi-24/hivemind-cli |
npm install
npm run buildFor a clean install like CI: npm ci then npm run build.
| Variable | Default | Purpose |
|---|---|---|
HIVEMIND_BASE_URL |
http://127.0.0.1:11434/v1 |
OpenAI-compatible API base (e.g. Ollama) |
HIVEMIND_MODEL |
qwen2.5 |
Model id |
HIVEMIND_API_KEY |
(empty) | Optional bearer token |
HIVEMIND_AUTO_APPROVE |
low |
none / low / low_medium / all — tool auto-approval |
HIVEMIND_VERBOSE |
— | Set to 1 with headless to log events on stderr |
HIVEMIND_DEBUG |
— | Set to 1 for extra timings (e.g. LLM request duration) on stderr |
HIVEMIND_VERBOSE_TOOLS |
— | Set to 1 for full tool arguments and tool output in the TUI (see also /settings verbose) |
HIVEMIND_SHOW_REASONING |
— | Set to 1 to show model reasoning/thinking in the TUI when the API streams it (e.g. some OpenAI-compatible servers) |
HIVEMIND_TUI_TRANSCRIPT_CAP |
(auto) | Max transcript rows (bubbles) rendered in the TUI; older rows stay in session storage. Integer ≥ 10. The TUI root is also clamped to the terminal size so Ink avoids full-screen clears that reset scrollback when content is very tall. |
HIVEMIND_SESSION_LOAD_MAX_MESSAGES |
800 |
When resuming a session, load at most this many tail messages from messages.jsonl. Set to 0 to load the full history (may be slow for huge sessions). |
HIVEMIND_RUN_HOOKS |
(unset) | Set to 1 or true to run framework `hooks/*.js |
HIVEMIND_PROTOCOL_DIR |
— | Absolute path to the Hivemind framework repo (hooks, .claude/commands, skills) |
HIVEMIND_VAULT_DIR |
~/.hivemind |
Personal vault root (preferences, learnings, cross-session log). Set to a writable path for portable installs (e.g. beside the app). Workspace protocol data stays in <workspace>/.hivemind/ and is separate. |
HIVEMIND_SKIP_WORKSPACE_AUTH |
(unset) | Set to 1 to skip the interactive workspace consent prompt (trusted-folder opt-in). Use only for automation/CI — normal use should show the prompt once per folder until you authorize. |
Node heap (optional): Very long TUI sessions or huge streamed replies can push V8 toward its default heap limit. If you see JavaScript heap out of memory, you can raise the limit (this is a workaround, not a substitute for the TUI stream batching in the codebase), for example:
# Windows (cmd)
set NODE_OPTIONS=--max-old-space-size=8192
# macOS / Linux
export NODE_OPTIONS=--max-old-space-size=8192
npm run hivemind -- --cwd .Persistent TUI settings (optional): .hivemind/cli-settings.json in the workspace — model, baseUrl, autoApprove, verboseTools, showReasoning (used when the matching env var is unset).
After publishing, install from the registry (requires Node 18+):
npm install -g @awi-24/hivemind-cli
hivemind --helpFrom this monorepo (before or without npm publish): build and link the three workspace packages into your global npm prefix:
npm run install:global
hivemind --helpPack tarballs for inspection or offline install: npm run pack:cli (CLI only) or npm run pack:all (@awi-24/core, @awi-24/tui, @awi-24/hivemind-cli). Publish all packages (core → tui → hivemind-cli): npm run publish:npm (run from a clean npm run build; you must be logged in to npm — scoped packages use the @awi-24 scope, which must match your npm username unless you change it in the package.json files). The installable package name is @awi-24/hivemind-cli; the shell command remains hivemind (see bin in that package).
Windows setup (.exe installer): Install Inno Setup 6, then from the repo root run npm run installer:win (or pwsh scripts/build-windows-installer.ps1). This runs npm run installer:stage (build + stage under release/global-prefix) and compiles installer/hivemind-cli.iss. The installer copies the staged tree to %LocalAppData%\Programs\Hivemind CLI, appends that folder to your user PATH, and registers uninstall. The hivemind shim still invokes node; Node.js must remain installed and on PATH.
npm run build copies the protocol template from repo hivemind/ into packages/cli/bundled/hivemind when that folder exists; the bundled snapshot in git is included in the published package so global installs still resolve the framework without cloning the monorepo.
Portable / fixed vault path: Point HIVEMIND_VAULT_DIR at a user-writable folder (for example next to an unzip copy of the CLI). Avoid putting the vault directly under Program Files without elevated rights.
The CLI is an ESM Node app (Ink TUI, MCP SDK, bundled packages/cli/bundled/hivemind). A Node Single Executable Application (SEA) build is possible in principle but requires a dedicated asset bundle step and runtime validation. The supported distributions are npm global and run from source; treat SEA as maintainer-only until a checked-in build script exists.
npm quirk: flags after npm run hivemind belong to npm unless you insert --. The flag --workspace is also an npm workspaces selector, so you may see No workspaces found or argument missing. Use either:
npm run hivemind -- --cwd .(recommended), ornpm run hivemind -- tui --workspace ., ornpm run hivemind:herefrom the repo root (TUI with cwd =.)
# Interactive TUI (default when no subcommand)
npm run hivemind -- --cwd .
# Same, from repo root (no extra flags)
npm run hivemind:here
# One-shot (no TUI)
npm run hivemind -- headless -p "Summarize README.md" --cwd .
# TCP supervisor + worker (multi-session / extra terminal)
npm run hivemind -- supervisor --port 7878
npm run hivemind -- worker --port 7878 -p "Hello" --session default
# Best-effort new OS window/tab (Windows: needs `wt.exe`)
npm run hivemind -- spawn-worker --port 7878 --cwd .
# New terminal with the interactive TUI (Windows: wt.exe; macOS: Terminal; Linux: x-terminal-emulator)
npm run hivemind -- spawn-tui --cwd .
# Sanity check: banner, resolved ./hivemind framework, GET /v1/models, health
npm run hivemind -- doctor --cwd .
# Print resolved framework directory only
npm run hivemind -- protocol --cwd .
# List persisted CLI sessions for a workspace
npm run hivemind -- sessions --cwd .
# Copy bundled framework .hivemind/ into the workspace when missing (same as first /hm-init bootstrap)
npm run hivemind -- init --cwd .If the project has no .hivemind/ yet, running /hm-init (or any protocol agent_prompt slash) copies the template from the resolved framework root into <workspace>/.hivemind/. You can do the same without the model using hivemind init --cwd .. After that, tools like read_file(".hivemind/project.json") and workspace memory loading work as documented in the protocol.
When the workspace has .hivemind/ (e.g. memory/MANIFEST.md, memory/shared-context.md, project.json), the agent system prompt is assembled from those sources within a token budget, with railguard snippets from project config. The TCP supervisor path uses the same assembly. Optional output railguards run on the final assistant reply when tools were not used in the turn (mitigation, not a guarantee).
Sessions are stored under .hivemind/cli-sessions/<id>/ (metadata + messages.jsonl). Start the TUI with --session <id> to open one directly, or from a running TUI use /resume <id> (alias /session) after /sessions to switch without restarting. /clear clears the visible history and the on-disk messages for the current session id.
In the interactive UI, messages starting with / are handled locally (no LLM call):
/help, /health, /models, /settings (model, baseUrl, auto, verbose, reasoning), /hm, /hooks, /version, /clear, /sessions, /resume <id> (alias /session <id>), /agent <role> <objective> (delegates a subagent turn using profiles under .hivemind/agents).
Autocomplete: while typing, a hint row shows suggestions; Tab accepts the first suggestion (slash commands, hm-* from .claude/commands, and /resume session ids when available).
Transcript formatting: assistant bubbles render Markdown (headings, lists, tables, blockquotes, fenced code). LaTeX-style math is styled in the terminal: inline $…$ or \(...\), display \[…\] on one line, or $$ … $$ blocks (possibly multi-line).
Interactive tools: the model can call pick_one and pick_many for single- and multi-select prompts. In the TUI this shows an Ink select UI; in headless mode the core falls back to stdin (numbered choices on stderr). Esc cancels a queued pick prompt or interrupts an in-flight model turn when supported.
Open / inspectable runs: enable HIVEMIND_VERBOSE_TOOLS=1 or /settings verbose on to print full tool arguments (pretty JSON) and full tool results, including run_command output with a $ command header. When the provider streams reasoning, HIVEMIND_SHOW_REASONING=1 or /settings reasoning on shows a dim Σ line in the transcript (reasoning is not persisted in saved session history).
The repo’s Hivemind protocol pack lives in hivemind/ (hooks, .claude/commands, skills, .hivemind/). The CLI resolves it via the bundled copy in the published package, ./hivemind under your cwd, or HIVEMIND_PROTOCOL_DIR.
npm test
npm run smokenpm run smoke runs non-interactive CLI checks (--help, doctor, protocol) after a build. Optional static check for unused exports: npm run knip.
ci.yml runs npm ci, npm run build, npm test, npm run smoke, and npm run knip on pull requests and pushes to main / master. Match that locally before opening a PR.
| Doc | Contents |
|---|---|
docs/supervisor-tcp.md |
TCP supervisor / worker mode |
PENDENCIES.md |
Roadmap, phased work, and what is partial or not built |
MIT — see LICENSE.
Note: Local workspace state (.hivemind/ sessions, settings) is not part of this repository; it is created at runtime beside your project and is listed in .gitignore.