agent-hive
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.
Badge for your README
Markdown
[](/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)
- {
- "$schema": "https://json.schemastore.org/claude-code-plugin-marketplace.json",
- "name": "agent-hive",
- "owner": {
- "name": "tctinh",
- "url": "https://github.com/tctinh"
- },
- "metadata": {
- "description": "Plan-first, gate-driven, parallel-worker development for Claude Code.",
- "version": "1.4.8"
- },
- "plugins": [
- {
- "name": "hive",
- "source": "./packages/claude-code-hive",
- "version": "1.4.8",
- "description": "Plan-first AI development with batched parallelism. Native Claude Code implementation of the Agent Hive workflow.",
- "author": {
- "name": "tctinh",
- "url": "https://github.com/tctinh"
- },
- "homepage": "https://github.com/tctinh/agent-hive",
- "repository": "https://github.com/tctinh/agent-hive",
- "license": "MIT",
- "keywords": [
- "hive",
- "planning",
- "orchestration",
- "worktree",
- "parallel",
- "tdd"
- ]
- }
- ]
- }
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)
- # Agent Hive
- ## Status: retired — moved to Agentic Hive
- **Agent Hive is no longer maintained. Active development has moved to
- [Agentic Hive](https://github.com/tctinh/agentic-hive).**
- The old Hive method was built around a prescribed **Plan → Approve → Execute**
- workflow, fixed agent roles, and orchestrated task batches. I am retiring this
- approach because I no longer consider it a good fit for the judgment, creativity,
- and autonomy of newer, more capable generalist agents.
- Agentic Hive takes a different approach: a persistent Unix habitat that supplies
- the environment, shared awareness, durable context, collision avoidance, and
- session mechanics. Members supply reasoning, creativity, and implementation;
- the human Beekeeper supplies intent, taste, and final semantic authority.
- This repository is retained as a historical reference. There will be no further
- development, fixes, or releases here. For current documentation, setup, and
- discussion, visit **[tctinh/agentic-hive](https://github.com/tctinh/agentic-hive)**.
- ---
- The documentation below describes the retired Agent Hive system.
- **Plan first. Execute with trust. Context persists.**
- 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.
- [](https://www.npmjs.com/package/opencode-hive)
- [](https://www.npmjs.com/package/claude-code-hive)
- [](https://www.npmjs.com/package/@tctinh/agent-hive-mcp)
- [](https://marketplace.visualstudio.com/items?itemName=tctinh.vscode-hive)
- [](LICENSE)
- ---
- ## Demo
- https://github.com/user-attachments/assets/6290b435-1566-46b4-ac98-0420ed321204
- ---
- ## Why Hive
- 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:
- ```
- You describe the work
- ↓
- Hive discovers, asks, builds plan.md
- ↓
- You review and approve ← human gate
- ↓
- Workers execute tasks in isolated git worktrees (batched parallel)
- ↓
- Results merge. plan/spec/report live in .hive/ forever.
- ```
- | Without Hive | With Hive |
- |---|---|
- | Agent touches 40 files, half break | Tasks run in isolated worktrees — discard any worker |
- | New session starts from zero | Feature state persists in `.hive/features/<name>/` |
- | Parallel agents collide, duplicate | Explicit batches with dependency ordering |
- | "What happened here?" | plan.md, spec.md, report.md per task |
- | Scope creep mid-execution | Human approval gate before any code change |
- ---
- ## Choose Your Platform
- | Platform | Hive role | Best for |
- |---|---|---|
- | **[Claude Code](#claude-code)** | Full runtime (plugin + MCP) | Claude Code CLI users |
- | **[OpenCode](#opencode)** | Full runtime (plugin) | OpenCode CLI users — most feature-complete |
- | **[VS Code](#vs-code)** | Companion UI (review + status) | Visual review alongside a CLI runtime |
- 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.
- ---
- ## Claude Code
- 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.
- ### Install
- ```bash
- # 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.
- ### Start
- ```
- /hive add user authentication
- ```
- `/hive` is the only entry point you need — it creates a feature, runs discovery, writes the plan, waits for approval, and dispatches workers.
- ### What you get
- - **`hive:hive`** — Opus-tier orchestrator. Plans features, batches tasks, dispatches workers, merges results.
- - **`hive:forager`** — Sonnet-tier worker. Runs a single task in an isolated worktree, commits, exits. Workers cannot spawn sub-workers.
- - **`hive:hygienic`** — Opus-tier reviewer. Falsification-first review against the approved plan.
- - **`/hive` command** — Single entry point; stateful across sessions via the plan file.
- - **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.
- - **`SessionStart` hook** — Re-injects current feature context so a new session doesn't restart from zero.
- - **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.
- 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.
- ---
- ## OpenCode
- The OpenCode runtime is Hive's most mature implementation. It integrates with OpenCode's session, plugin, and compaction systems natively.
- ### Install
- Add the plugin to `opencode.json` — OpenCode handles npm resolution automatically; you do not need to `npm install` yourself.
- ```json
- {
- "$schema": "https://opencode.ai/config.json",
- "plugin": ["opencode-hive@latest"]
- }
- ```
- ### Optional config — `.hive/agent-hive.json`
- Project-scoped config (preferred); falls back to `.opencode/agent_hive.json` or `~/.config/opencode/agent_hive.json`.
- ```json
- {
- "$schema": "https://raw.githubusercontent.com/tctinh/agent-hive/main/packages/opencode-hive/schema/agent_hive.schema.json",
- "agentMode": "unified",
- "agents": {
- "hive-master": { "model": "anthropic/claude-sonnet-4-20250514", "temperature": 0.5 },
- "forager-worker": { "model": "anthropic/claude-sonnet-4-20250514", "temperature": 0.3 }
- }
- }
- ```
- ### Start
- Chat with OpenCode. Ask it to "create a feature for user authentication" and Hive activates automatically.
- ### What you get
- - **7 agents** — Unified mode: `hive-master` handles planning + orchestration. Dedicated mode: `architect-planner` + `swarm-orchestrator`. Plus `scout-researcher`, `forager-worker`, `hygienic-reviewer`, `hive-helper`.
- - **18 MCP tools** — Full lifecycle: feature, plan, tasks, worktrees, context, merge, status, skills, agents-md, research.
- - **11 skills** — Same library as Claude Code, loaded via the `hive_skill` tool.
- - **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.
- - **Optional research MCPs** — Exa web search, Context7 docs, grep.app, ast-grep. Disable individually via `disableMcps`.
- See [`packages/opencode-hive/README.md`](packages/opencode-hive/README.md) for per-agent model routing, derived subagents, and DCP safety.
- ---
- ## VS Code
- 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.
- ### Install
- ```bash
- code --install-extension tctinh.vscode-hive
- ```
- Or search **"Agent Hive"** in the Extensions panel.
- ### What you get
- - **Hive sidebar** (activity-bar view) — features tree, per-task status, inline comments on `plan.md`.
- - **One-click plan approval** — opens `plan.md`, lets you add/resolve inline comments, Approve button writes approval state back to `.hive/`.
- - **Task detail** — open `spec.md` (what the worker was told) and `report.md` (what it did).
- - **`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.
- - **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.
- ### Typical setup
- 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.
- ---
- ## The Workflow
- Every platform runs the same four phases.
- ### 1. Discovery + Plan
- Hive asks questions, reads the codebase, checks existing patterns, then writes `.hive/features/<name>/plan.md`:
- ```markdown
- # User Authentication
- ## Overview
- Add JWT-based auth with login, signup, protected routes.
- ## Tasks
- ### 1. Extract auth logic to service
- Move scattered auth code to AuthService.
- ### 2. Add token refresh mechanism
- Implement refresh token rotation.
- ### 3. Update API routes
- Convert all routes to use AuthService.
- ```
- ### 2. Human Approval
- 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*.
- ### 3. Batched Parallel Execution
- ```
- Orchestrator
- ├── Batch 1 (parallel):
- │ ├── Forager A → worktree-a → commit
- │ ├── Forager B → worktree-b → commit
- │ └── Forager C → worktree-c → commit
- │ ↓ merge + full test suite
- └── Batch 2 (parallel):
- ├── Forager D (uses A+B+C results)
- └── Forager E
- ↓ merge + full test suite
- ```
- 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.
- ### 4. Audit Trail
- ```
- .hive/features/01_user-auth/
- ├── plan.md # the approved contract
- ├── tasks.json # task state
- ├── context/
- │ └── overview.md # human-facing branch summary
- └── tasks/
- ├── 01-extract-auth-logic/
- │ ├── spec.md # what the worker was told
- │ └── report.md # what it did
- └── 02-add-token-refresh/
- ├── spec.md
- └── report.md
- ```
- ---
- ## Platform Comparison
- | | Claude Code | OpenCode | VS Code |
- |---|---|---|---|
- | **Role** | Runtime | Runtime | Companion |
- | **Entry point** | `/hive` slash command | Ask in chat | Sidebar + LM tools |
- | **Worker dispatch** | `Agent` tool (native) | OpenCode subagent system | N/A |
- | **Worktree isolation** | `isolation: worktree` (auto) | `hive_worktree_*` tools | N/A |
- | **MCP runtime** | `@tctinh/agent-hive-mcp` sidecar | `opencode-hive` plugin (in-process) | Built-in LM tool bridge |
- | **Skills** | 11 bundled | 11 via `hive_skill` | N/A |
- | **Context injection** | `SessionStart` hook | Compaction hooks + sessions.json | Watches `.hive/` passively |
- | **Distribution** | Plugin marketplace + npm | npm (via `opencode.json`) | VS Code Marketplace |
- ---
- ## Philosophy
- Hive is built on nine principles. They explain why the workflow is shaped the way it is.
- **P1 — Context Persists.** `.hive/features/` is durable memory. Plan, tasks, context, reports survive session end, compaction, and restarts.
- **P2 — Plan → Approve → Execute.** No code changes before a human approves the plan. Trust is established, not assumed.
- **P3 — Human Shapes, Agent Builds.** The human owns *what* and *why*. The agent owns *how*. Scope is fixed at approval.
- **P4 — Good Enough Wins.** Workers do best-effort verification at task level; the full suite runs at batch level. No perfectionism spirals.
- **P5 — Batched Parallelism.** Independent tasks run in parallel inside a batch. Batches run sequentially so context flows forward.
- **P6 — Tests Define Done.** A batch is done when the suite passes, not when a worker says so.
- **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.
- **P8 — Cross-Model Prompts.** Agent instructions work across model families. The workflow design does not depend on any one model's quirks.
- **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.
- See [PHILOSOPHY.md](PHILOSOPHY.md) for the full evolution log.
- ---
- ## Skills
- | Skill | When the orchestrator loads it |
- |---|---|
- | `writing-plans` | Creating or revising a feature plan |
- | `executing-plans` | Running a batch execution pass |
- | `dispatching-parallel-agents` | Spawning multiple concurrent workers |
- | `parallel-exploration` | Multi-domain research |
- | `systematic-debugging` | Diagnosing a failing test or regression |
- | `test-driven-development` | Implementing new behaviour with tests |
- | `verification-before-completion` | Checking work before declaring done |
- | `code-reviewer` | Reviewing changes against plan and quality bar |
- | `brainstorming` | Exploring options before committing |
- | `docker-mastery` | Docker / docker-compose / container debugging |
- | `agents-md-mastery` | Reviewing agent instruction files |
- ---
- ## Troubleshooting
- **Worker appears stuck.** Call `hive_status({ feature })` first. Use `continueFrom: 'blocked'` only when status confirms `blocked` — not `pending` or `in_progress`.
- **Session resumed without context.** The SessionStart hook (Claude Code) or compaction recovery (OpenCode) should re-inject. If not, call `hive_status` explicitly.
- **OpenCode with DCP.** Protect Hive tools from pruning:
- ```jsonc
- {
- "tools": {
- "settings": {
- "protectedTools": ["hive_status", "hive_worktree_start", "hive_worktree_create", "hive_worktree_commit", "hive_worktree_discard", "question"]
- }
- }
- }
- ```
- **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.
- ---
- ## Packages
- | Package | Registry | Description |
- |---|---|---|
- | [`opencode-hive`](https://www.npmjs.com/package/opencode-hive) | npm | OpenCode plugin — full runtime, 7 agents, 18 tools |
- | [`claude-code-hive`](https://www.npmjs.com/package/claude-code-hive) | npm | Claude Code plugin assets — agents, skills, hooks, `/hive` |
- | [`@tctinh/agent-hive-mcp`](https://www.npmjs.com/package/@tctinh/agent-hive-mcp) | npm | MCP gate-tools server (used by Claude Code) |
- | [`vscode-hive`](https://marketplace.visualstudio.com/items?itemName=tctinh.vscode-hive) | VS Code Marketplace | Sidebar, plan review, LM tool bridge |
- ---
- ## Related Projects
- | Tool | How Hive relates |
- |---|---|
- | [Oh My OpenCode](https://github.com/code-yeongyu/oh-my-opencode) | Companion — OMO handles delegation, Hive adds workflow structure |
- | [Conductor](https://github.com/gemini-cli-extensions/conductor) | Similar goal; Hive adds the human approval gate and worktree isolation |
- | [Spec Kit](https://github.com/github/spec-kit) | Heavy upfront specs — Hive specs emerge from conversation |
- | [Ralph Wiggum](https://awesomeclaude.ai/ralph-wiggum) | Retry-first vs plan-first — different philosophy, both valid |
- ---
- ## License
- MIT with Commons Clause — free for personal and non-commercial use. See [LICENSE](LICENSE).
- ---
- <p align="center">
- <strong>Stop vibing. Start hiving.</strong>
- <br>
- <em>Plan first. Execute with trust. Context persists.</em>
- </p>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.