Skip to content
Back to search

agent-hive

MarketplaceWorks with Claude CodeGitHub

Plan first. Execute with trust. Context persists.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tctinh--agent-hive/badge.svg)](/listings/tctinh--agent-hive)

HTML

<a href="/listings/tctinh--agent-hive"><img src="/api/listings/tctinh--agent-hive/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# inside Claude Code
/plugin marketplace add tctinh/agent-hive
/plugin install hive@agent-hive

The marketplace definition lives at [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) and points at [`packages/claude-code-hive`](packages/claude-code-hive). The plugin spawns the MCP runtime on demand via `npx -y -p @tctinh/agent-hive-mcp@latest hive-mcp`, so you don't need to install the MCP package separately — npx fetches and caches it the first time `/hive` runs.

Requirements: Node.js 18+ on your PATH so `npx` is available.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 35 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-plugin-marketplace.json",
  3. "name": "agent-hive",
  4. "owner": {
  5. "name": "tctinh",
  6. "url": "https://github.com/tctinh"
  7. },
  8. "metadata": {
  9. "description": "Plan-first, gate-driven, parallel-worker development for Claude Code.",
  10. "version": "1.4.8"
  11. },
  12. "plugins": [
  13. {
  14. "name": "hive",
  15. "source": "./packages/claude-code-hive",
  16. "version": "1.4.8",
  17. "description": "Plan-first AI development with batched parallelism. Native Claude Code implementation of the Agent Hive workflow.",
  18. "author": {
  19. "name": "tctinh",
  20. "url": "https://github.com/tctinh"
  21. },
  22. "homepage": "https://github.com/tctinh/agent-hive",
  23. "repository": "https://github.com/tctinh/agent-hive",
  24. "license": "MIT",
  25. "keywords": [
  26. "hive",
  27. "planning",
  28. "orchestration",
  29. "worktree",
  30. "parallel",
  31. "tdd"
  32. ]
  33. }
  34. ]
  35. }
README.md · README · 371 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Agent Hive
  2. ## Status: retired — moved to Agentic Hive
  3. **Agent Hive is no longer maintained. Active development has moved to
  4. [Agentic Hive](https://github.com/tctinh/agentic-hive).**
  5. The old Hive method was built around a prescribed **Plan → Approve → Execute**
  6. workflow, fixed agent roles, and orchestrated task batches. I am retiring this
  7. approach because I no longer consider it a good fit for the judgment, creativity,
  8. and autonomy of newer, more capable generalist agents.
  9. Agentic Hive takes a different approach: a persistent Unix habitat that supplies
  10. the environment, shared awareness, durable context, collision avoidance, and
  11. session mechanics. Members supply reasoning, creativity, and implementation;
  12. the human Beekeeper supplies intent, taste, and final semantic authority.
  13. This repository is retained as a historical reference. There will be no further
  14. development, fixes, or releases here. For current documentation, setup, and
  15. discussion, visit **[tctinh/agentic-hive](https://github.com/tctinh/agentic-hive)**.
  16. ---
  17. The documentation below describes the retired Agent Hive system.
  18. **Plan first. Execute with trust. Context persists.**
  19. Agent Hive is a workflow layer that sits on top of your AI coding tool. It imposes just enough structure to make multi-agent, multi-step work traceable and recoverable — without taking ownership of your editor, your model, or your coding style.
  20. [![npm](https://img.shields.io/npm/v/opencode-hive.svg?label=opencode-hive)](https://www.npmjs.com/package/opencode-hive)
  21. [![npm](https://img.shields.io/npm/v/claude-code-hive.svg?label=claude-code-hive)](https://www.npmjs.com/package/claude-code-hive)
  22. [![npm](https://img.shields.io/npm/v/@tctinh/agent-hive-mcp.svg?label=agent-hive-mcp)](https://www.npmjs.com/package/@tctinh/agent-hive-mcp)
  23. [![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/tctinh.vscode-hive.svg?label=vscode-hive)](https://marketplace.visualstudio.com/items?itemName=tctinh.vscode-hive)
  24. [![License: MIT with Commons Clause](https://img.shields.io/badge/License-MIT%20with%20Commons%20Clause-blue.svg)](LICENSE)
  25. ---
  26. ## Demo
  27. https://github.com/user-attachments/assets/6290b435-1566-46b4-ac98-0420ed321204
  28. ---
  29. ## Why Hive
  30. Raw agentic coding has a consistent failure mode: agents spray changes across a codebase, sessions lose context, parallel workers collide, and nobody can reconstruct what happened. Hive fixes this with a small, strict loop:
  31. ```
  32. You describe the work
  33. ↓
  34. Hive discovers, asks, builds plan.md
  35. ↓
  36. You review and approve ← human gate
  37. ↓
  38. Workers execute tasks in isolated git worktrees (batched parallel)
  39. ↓
  40. Results merge. plan/spec/report live in .hive/ forever.
  41. ```
  42. | Without Hive | With Hive |
  43. |---|---|
  44. | Agent touches 40 files, half break | Tasks run in isolated worktrees — discard any worker |
  45. | New session starts from zero | Feature state persists in `.hive/features/<name>/` |
  46. | Parallel agents collide, duplicate | Explicit batches with dependency ordering |
  47. | "What happened here?" | plan.md, spec.md, report.md per task |
  48. | Scope creep mid-execution | Human approval gate before any code change |
  49. ---
  50. ## Choose Your Platform
  51. | Platform | Hive role | Best for |
  52. |---|---|---|
  53. | **[Claude Code](#claude-code)** | Full runtime (plugin + MCP) | Claude Code CLI users |
  54. | **[OpenCode](#opencode)** | Full runtime (plugin) | OpenCode CLI users — most feature-complete |
  55. | **[VS Code](#vs-code)** | Companion UI (review + status) | Visual review alongside a CLI runtime |
  56. The VS Code extension is **not** a runtime. It visualises the `.hive/` state written by Claude Code or OpenCode and lets you approve plans without leaving the editor.
  57. ---
  58. ## Claude Code
  59. The Claude Code plugin ships three Hive agents (`hive`, `forager`, `hygienic`), a `/hive` slash command, 11 on-demand skills, a `SessionStart` hook, and spawns the `@tctinh/agent-hive-mcp` MCP server as a sidecar.
  60. ### Install
  61. ```bash
  62. # inside Claude Code
  63. /plugin marketplace add tctinh/agent-hive
  64. /plugin install hive@agent-hive
  65. ```
  66. The marketplace definition lives at [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) and points at [`packages/claude-code-hive`](packages/claude-code-hive). The plugin spawns the MCP runtime on demand via `npx -y -p @tctinh/agent-hive-mcp@latest hive-mcp`, so you don't need to install the MCP package separately — npx fetches and caches it the first time `/hive` runs.
  67. Requirements: Node.js 18+ on your PATH so `npx` is available.
  68. ### Start
  69. ```
  70. /hive add user authentication
  71. ```
  72. `/hive` is the only entry point you need — it creates a feature, runs discovery, writes the plan, waits for approval, and dispatches workers.
  73. ### What you get
  74. - **`hive:hive`** — Opus-tier orchestrator. Plans features, batches tasks, dispatches workers, merges results.
  75. - **`hive:forager`** — Sonnet-tier worker. Runs a single task in an isolated worktree, commits, exits. Workers cannot spawn sub-workers.
  76. - **`hive:hygienic`** — Opus-tier reviewer. Falsification-first review against the approved plan.
  77. - **`/hive` command** — Single entry point; stateful across sessions via the plan file.
  78. - **MCP gate tools** — `hive_feature_create`, `hive_plan_write`, `hive_plan_approve`, `hive_tasks_sync`, `hive_status`, `hive_worktree_commit`, `hive_merge`, `hive_feature_complete`, plus research tools.
  79. - **`SessionStart` hook** — Re-injects current feature context so a new session doesn't restart from zero.
  80. - **11 skills** — Loaded on demand: writing-plans, executing-plans, dispatching-parallel-agents, parallel-exploration, systematic-debugging, test-driven-development, verification-before-completion, code-reviewer, brainstorming, docker-mastery, agents-md-mastery.
  81. Workers are dispatched via Claude Code's native `Agent` tool with `isolation: worktree` — Claude Code creates a fresh git worktree per worker automatically. The orchestrator never edits code directly; it plans, dispatches, and merges.
  82. ---
  83. ## OpenCode
  84. The OpenCode runtime is Hive's most mature implementation. It integrates with OpenCode's session, plugin, and compaction systems natively.
  85. ### Install
  86. Add the plugin to `opencode.json` — OpenCode handles npm resolution automatically; you do not need to `npm install` yourself.
  87. ```json
  88. {
  89. "$schema": "https://opencode.ai/config.json",
  90. "plugin": ["opencode-hive@latest"]
  91. }
  92. ```
  93. ### Optional config — `.hive/agent-hive.json`
  94. Project-scoped config (preferred); falls back to `.opencode/agent_hive.json` or `~/.config/opencode/agent_hive.json`.
  95. ```json
  96. {
  97. "$schema": "https://raw.githubusercontent.com/tctinh/agent-hive/main/packages/opencode-hive/schema/agent_hive.schema.json",
  98. "agentMode": "unified",
  99. "agents": {
  100. "hive-master": { "model": "anthropic/claude-sonnet-4-20250514", "temperature": 0.5 },
  101. "forager-worker": { "model": "anthropic/claude-sonnet-4-20250514", "temperature": 0.3 }
  102. }
  103. }
  104. ```
  105. ### Start
  106. Chat with OpenCode. Ask it to "create a feature for user authentication" and Hive activates automatically.
  107. ### What you get
  108. - **7 agents** — Unified mode: `hive-master` handles planning + orchestration. Dedicated mode: `architect-planner` + `swarm-orchestrator`. Plus `scout-researcher`, `forager-worker`, `hygienic-reviewer`, `hive-helper`.
  109. - **18 MCP tools** — Full lifecycle: feature, plan, tasks, worktrees, context, merge, status, skills, agents-md, research.
  110. - **11 skills** — Same library as Claude Code, loaded via the `hive_skill` tool.
  111. - **Compaction recovery** — OpenCode sessions compact on long runs; Hive stores durable session metadata in `.hive/sessions.json` so agents re-anchor with the correct role after compaction.
  112. - **Optional research MCPs** — Exa web search, Context7 docs, grep.app, ast-grep. Disable individually via `disableMcps`.
  113. See [`packages/opencode-hive/README.md`](packages/opencode-hive/README.md) for per-agent model routing, derived subagents, and DCP safety.
  114. ---
  115. ## VS Code
  116. The VS Code extension is a **companion**, not a runtime. It shows you the state of `.hive/` that a CLI runtime (Claude Code or OpenCode) is writing, and lets you approve plans and comment on them without leaving the editor.
  117. ### Install
  118. ```bash
  119. code --install-extension tctinh.vscode-hive
  120. ```
  121. Or search **"Agent Hive"** in the Extensions panel.
  122. ### What you get
  123. - **Hive sidebar** (activity-bar view) — features tree, per-task status, inline comments on `plan.md`.
  124. - **One-click plan approval** — opens `plan.md`, lets you add/resolve inline comments, Approve button writes approval state back to `.hive/`.
  125. - **Task detail** — open `spec.md` (what the worker was told) and `report.md` (what it did).
  126. - **`hive.initNest` command** — scaffolds `.hive/`, `.github/agents/`, `.github/prompts/`, `.github/copilot-instructions.md`, `.claude/skills/hive/SKILL.md`, and `.opencode/skill/hive/SKILL.md` so any runtime has the right files to read.
  127. - **Language-model tools** — the extension registers Hive operations (`hive_feature_create`, `hive_plan_write`, `hive_plan_approve`, `hive_status`, etc.) via VS Code's `vscode.lm.registerTool` API. These are read/write wrappers around `.hive/` state that any VS Code LM client can call — useful for quick edits from the editor, **not** a replacement for Claude Code or OpenCode as the execution runtime.
  128. ### Typical setup
  129. Run Claude Code or OpenCode in a terminal pane; keep VS Code open for the Hive sidebar. Plan review and approval happen in VS Code; execution happens in the CLI. The extension watches `.hive/` and reflects changes in real time.
  130. ---
  131. ## The Workflow
  132. Every platform runs the same four phases.
  133. ### 1. Discovery + Plan
  134. Hive asks questions, reads the codebase, checks existing patterns, then writes `.hive/features/<name>/plan.md`:
  135. ```markdown
  136. # User Authentication
  137. ## Overview
  138. Add JWT-based auth with login, signup, protected routes.
  139. ## Tasks
  140. ### 1. Extract auth logic to service
  141. Move scattered auth code to AuthService.
  142. ### 2. Add token refresh mechanism
  143. Implement refresh token rotation.
  144. ### 3. Update API routes
  145. Convert all routes to use AuthService.
  146. ```
  147. ### 2. Human Approval
  148. Nothing executes until you approve — in the chat, via the VS Code Approve button, or by calling `hive_plan_approve`. The human owns the *what*. The agent owns the *how*.
  149. ### 3. Batched Parallel Execution
  150. ```
  151. Orchestrator
  152. ├── Batch 1 (parallel):
  153. │ ├── Forager A → worktree-a → commit
  154. │ ├── Forager B → worktree-b → commit
  155. │ └── Forager C → worktree-c → commit
  156. │ ↓ merge + full test suite
  157. └── Batch 2 (parallel):
  158. ├── Forager D (uses A+B+C results)
  159. └── Forager E
  160. ↓ merge + full test suite
  161. ```
  162. Independent tasks run concurrently. Dependent tasks wait. Each worker runs in its own worktree, verifies its own work, and commits. The orchestrator merges batch-by-batch and runs the full suite after each merge.
  163. ### 4. Audit Trail
  164. ```
  165. .hive/features/01_user-auth/
  166. ├── plan.md # the approved contract
  167. ├── tasks.json # task state
  168. ├── context/
  169. │ └── overview.md # human-facing branch summary
  170. └── tasks/
  171. ├── 01-extract-auth-logic/
  172. │ ├── spec.md # what the worker was told
  173. │ └── report.md # what it did
  174. └── 02-add-token-refresh/
  175. ├── spec.md
  176. └── report.md
  177. ```
  178. ---
  179. ## Platform Comparison
  180. | | Claude Code | OpenCode | VS Code |
  181. |---|---|---|---|
  182. | **Role** | Runtime | Runtime | Companion |
  183. | **Entry point** | `/hive` slash command | Ask in chat | Sidebar + LM tools |
  184. | **Worker dispatch** | `Agent` tool (native) | OpenCode subagent system | N/A |
  185. | **Worktree isolation** | `isolation: worktree` (auto) | `hive_worktree_*` tools | N/A |
  186. | **MCP runtime** | `@tctinh/agent-hive-mcp` sidecar | `opencode-hive` plugin (in-process) | Built-in LM tool bridge |
  187. | **Skills** | 11 bundled | 11 via `hive_skill` | N/A |
  188. | **Context injection** | `SessionStart` hook | Compaction hooks + sessions.json | Watches `.hive/` passively |
  189. | **Distribution** | Plugin marketplace + npm | npm (via `opencode.json`) | VS Code Marketplace |
  190. ---
  191. ## Philosophy
  192. Hive is built on nine principles. They explain why the workflow is shaped the way it is.
  193. **P1 — Context Persists.** `.hive/features/` is durable memory. Plan, tasks, context, reports survive session end, compaction, and restarts.
  194. **P2 — Plan → Approve → Execute.** No code changes before a human approves the plan. Trust is established, not assumed.
  195. **P3 — Human Shapes, Agent Builds.** The human owns *what* and *why*. The agent owns *how*. Scope is fixed at approval.
  196. **P4 — Good Enough Wins.** Workers do best-effort verification at task level; the full suite runs at batch level. No perfectionism spirals.
  197. **P5 — Batched Parallelism.** Independent tasks run in parallel inside a batch. Batches run sequentially so context flows forward.
  198. **P6 — Tests Define Done.** A batch is done when the suite passes, not when a worker says so.
  199. **P7 — Iron Laws + Hard Gates.** Constraints are enforced by tools, not by prompts. A plan without `## Tasks` does not pass; a worker that commits incomplete work gets rejected.
  200. **P8 — Cross-Model Prompts.** Agent instructions work across model families. The workflow design does not depend on any one model's quirks.
  201. **P9 — Deterministic Contracts Beat Soft Memory.** What a version ships is defined by the checked-in artifacts all agreeing on a version. What a feature did is defined by `plan.md`, `spec.md`, `report.md` — not by what anyone remembers.
  202. See [PHILOSOPHY.md](PHILOSOPHY.md) for the full evolution log.
  203. ---
  204. ## Skills
  205. | Skill | When the orchestrator loads it |
  206. |---|---|
  207. | `writing-plans` | Creating or revising a feature plan |
  208. | `executing-plans` | Running a batch execution pass |
  209. | `dispatching-parallel-agents` | Spawning multiple concurrent workers |
  210. | `parallel-exploration` | Multi-domain research |
  211. | `systematic-debugging` | Diagnosing a failing test or regression |
  212. | `test-driven-development` | Implementing new behaviour with tests |
  213. | `verification-before-completion` | Checking work before declaring done |
  214. | `code-reviewer` | Reviewing changes against plan and quality bar |
  215. | `brainstorming` | Exploring options before committing |
  216. | `docker-mastery` | Docker / docker-compose / container debugging |
  217. | `agents-md-mastery` | Reviewing agent instruction files |
  218. ---
  219. ## Troubleshooting
  220. **Worker appears stuck.** Call `hive_status({ feature })` first. Use `continueFrom: 'blocked'` only when status confirms `blocked` — not `pending` or `in_progress`.
  221. **Session resumed without context.** The SessionStart hook (Claude Code) or compaction recovery (OpenCode) should re-inject. If not, call `hive_status` explicitly.
  222. **OpenCode with DCP.** Protect Hive tools from pruning:
  223. ```jsonc
  224. {
  225. "tools": {
  226. "settings": {
  227. "protectedTools": ["hive_status", "hive_worktree_start", "hive_worktree_create", "hive_worktree_commit", "hive_worktree_discard", "question"]
  228. }
  229. }
  230. }
  231. ```
  232. **Claude Code marketplace install, MCP fails to launch.** The plugin invokes the MCP runtime via `npx -y -p @tctinh/agent-hive-mcp@latest hive-mcp`, which requires Node.js 18+ on PATH. If npx is sandboxed or the registry is blocked, pre-cache the package with `npx -y -p @tctinh/agent-hive-mcp@latest hive-mcp --version` (then Ctrl-C) before starting Claude Code.
  233. ---
  234. ## Packages
  235. | Package | Registry | Description |
  236. |---|---|---|
  237. | [`opencode-hive`](https://www.npmjs.com/package/opencode-hive) | npm | OpenCode plugin — full runtime, 7 agents, 18 tools |
  238. | [`claude-code-hive`](https://www.npmjs.com/package/claude-code-hive) | npm | Claude Code plugin assets — agents, skills, hooks, `/hive` |
  239. | [`@tctinh/agent-hive-mcp`](https://www.npmjs.com/package/@tctinh/agent-hive-mcp) | npm | MCP gate-tools server (used by Claude Code) |
  240. | [`vscode-hive`](https://marketplace.visualstudio.com/items?itemName=tctinh.vscode-hive) | VS Code Marketplace | Sidebar, plan review, LM tool bridge |
  241. ---
  242. ## Related Projects
  243. | Tool | How Hive relates |
  244. |---|---|
  245. | [Oh My OpenCode](https://github.com/code-yeongyu/oh-my-opencode) | Companion — OMO handles delegation, Hive adds workflow structure |
  246. | [Conductor](https://github.com/gemini-cli-extensions/conductor) | Similar goal; Hive adds the human approval gate and worktree isolation |
  247. | [Spec Kit](https://github.com/github/spec-kit) | Heavy upfront specs — Hive specs emerge from conversation |
  248. | [Ralph Wiggum](https://awesomeclaude.ai/ralph-wiggum) | Retry-first vs plan-first — different philosophy, both valid |
  249. ---
  250. ## License
  251. MIT with Commons Clause — free for personal and non-commercial use. See [LICENSE](LICENSE).
  252. ---
  253. <p align="center">
  254. <strong>Stop vibing. Start hiving.</strong>
  255. <br>
  256. <em>Plan first. Execute with trust. Context persists.</em>
  257. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.