hivemind-context-governance
Advanced tools
Context-Aware Governance Layer for OpenCode - prevents drift and manages session state across lifecycles
The operating system for AI coding sessions.
HiveMind là plugin OpenCode giúp AI agent không bị trôi ngữ cảnh, không quên quyết định kiến trúc, và không mất trạng thái khi session kéo dài. Trọng tâm v2.8: onboarding rõ ràng, governance chặt, và triển khai thực chiến cho team Việt Nam trước.
SaaS 0→1 cho người không biết code: menu hỏi đáp + auto-lane để ra PRD có thể triển khai.Giải cứu prompt hỗn loạn của team enterprise: bóc tách yêu cầu, ambiguity map, risk register.War-room production incident: ép agent đi theo checklist bằng chứng trước khi kết luận fix.TDD autopilot: agent chuyển tự động từ spec -> build -> validate với gate kiểm thử.MCP-first research sprint: phối hợp Context7/DeepWiki/Tavily/Exa/Repomix và chấm điểm confidence.Brownfield modernization: quét codebase cũ, lập workflow refactor theo từng lane và checkpoint.Cross-domain planning: cùng một khung cho dev + marketing + finance + office-ops.Subagent swarm governance: giao việc song song nhưng vẫn giữ được trace, export, và hồi cứu.Bilingual coaching mode: đầu ra EN/VI cùng cấu trúc, hỗ trợ onboarding team đa vai trò.No-command recovery: người dùng nói tự nhiên, hệ thống tự realign sang lệnh phù hợp và xin quyền bước tiếp theo.Phần này không phải bản dịch — mà được viết riêng cho người dùng Việt Nam, với giải thích kỹ hơn về cách hoạt động và lý do tại sao.
Cảm thấy hữu ích?
Hãy tưởng tượng bạn thuê một lập trình viên AI rất giỏi, nhưng anh ta có một vấn đề: mỗi 30 phút anh ta quên hết mọi thứ đang làm.
Đó chính xác là điều xảy ra với các AI coding agent hiện tại:
HiveMind giải quyết tất cả bằng một hệ thống quản trị context đơn giản nhưng hiệu quả.
Mỗi session làm việc với AI đều tuân theo một quy trình:
declare_intent → map_context → [làm việc] → compact_session
(khai báo) (cập nhật) (code) (lưu trữ)
declare_intentTrước khi bắt đầu bất kỳ công việc nào, agent phải nói rõ:
plan_driven (có kế hoạch), quick_fix (sửa nhanh), hoặc exploration (tìm hiểu)Nếu không khai báo, ở chế độ strict agent sẽ bị khóa — không thể ghi file cho đến khi khai báo. Điều này đảm bảo mọi công việc đều có mục tiêu rõ ràng.
map_contextKhi agent chuyển focus (ví dụ: từ "thiết kế database" sang "viết API"), nó phải gọi map_context để HiveMind biết. Hệ thống theo dõi 3 cấp:
| Cấp | Ý Nghĩa | Ví Dụ |
|---|---|---|
| Trajectory | Mục tiêu lớn | "Xây dựng hệ thống thanh toán" |
| Tactic | Chiến thuật cụ thể | "Tích hợp Stripe API" |
| Action | Hành động đang làm | "Viết test cho webhook handler" |
Nếu agent làm nhiều turn mà không cập nhật, HiveMind phát hiện drift (trôi dạt) và cảnh báo ngay.
compact_sessionKhi xong việc, compact_session sẽ:
Quan trọng: Mems Brain (bộ nhớ dài hạn) vẫn tồn tại sau compact. Những gì agent đã học được (save_mem) sẽ không bao giờ mất.
npx hivemind-context-governance init
Điều gì sẽ xảy ra (đảm bảo):
.hivemind/ với brain.json, config.json.opencode/opencode.json (để OpenCode tự động load).opencode/OPEN (assisted) hoặc LOCKED (strict)Hoạt động trên mọi máy, mọi project. Không ngoại lệ.
Wizard sẽ hướng dẫn bạn từng bước:
◆ Welcome to HiveMind Context Governance!
◆ Select governance mode:
│ ○ strict — Session starts LOCKED. Must declare intent before writes.
│ ● assisted — Session starts OPEN. Guidance without blocking. (recommended)
│ ○ permissive — Always OPEN. Silent tracking only.
◆ Select language:
│ ○ English
│ ● Tiếng Việt
◆ Select automation level:
│ ○ manual — No automation, you control everything
│ ○ guided — Suggestions only
│ ● assisted — Balanced automation (recommended)
│ ○ full — Maximum automation
│ ○ coach — Maximum handholding, skeptical of everything
◆ Configuration saved! .hivemind/ created.
npx hivemind-context-governance init --mode strict --lang vi --automation full
Lệnh này làm đúng như wizard tương tác:
.hivemind/.opencode/opencode.jsonXong. Plugin tự động hoạt động. AI agent sẽ nhận governance context được inject vào mỗi turn.
npx hivemind-context-governance status
Hoặc kiểm tra thủ công .opencode/opencode.json có chứa:
{
"plugin": ["hivemind-context-governance"]
}
Gõ /hivemind-scan trong OpenCode để quét dự án và tạo bản đồ cơ sở trước khi bắt đầu code.
Hoặc dùng CLI trực tiếp:
npx hivemind-context-governance scan --action analyze --json
npx hivemind-context-governance scan --action recommend
npx hivemind-context-governance scan --action orchestrate --json
Khi người dùng nói: "Hãy quét dự án và refactor", chạy theo thứ tự:
scan_hierarchy({ action: "analyze", json: true })scan_hierarchy({ action: "recommend" })scan_hierarchy({ action: "orchestrate", json: true })declare_intent(...) + map_context(...) để khóa focus trước khi sửa codeMục tiêu:
gsd/spec-kit/both/none) và tín hiệu BMAD| Công Cụ | Khi Nào Dùng | Tại Sao Quan Trọng |
|---|---|---|
declare_intent | Bắt đầu làm việc | Không có ý định rõ ràng = không có cơ sở để đánh giá drift |
map_context | Đổi hướng/focus | Mỗi lần đổi mà không cập nhật = context bị ô nhiễm |
compact_session | Xong việc | Không compact = mất toàn bộ intelligence tích lũy |
| Công Cụ | Khi Nào Dùng | Tại Sao Quan Trọng |
|---|---|---|
scan_hierarchy | Muốn xem nhanh trạng thái | Nắm bắt tình hình trong 1 giây |
think_back | Cảm thấy lạc | Hồi phục context sâu sau compaction |
scan_hierarchy (include_drift) | Trước khi kết luận xong | Kiểm tra độ lệch hướng theo trajectory/tactic/action |
| Công Cụ | Khi Nào Dùng | Tại Sao Quan Trọng |
|---|---|---|
save_mem | Học được bài học quan trọng | Quyết định, pattern, lỗi — tồn tại vĩnh viễn |
recall_mems | Gặp vấn đề quen thuộc | Tìm giải pháp từ quá khứ |
save_anchor | Sự thật bất biến | Port number, schema, API endpoint — không bao giờ quên |
| Công Cụ | Khi Nào Dùng | Tại Sao Quan Trọng |
|---|---|---|
hierarchy_manage | Cây nhiều nhánh hoặc cần nâng cấp | Gộp cả prune và migrate trong một công cụ |
export_cycle | Subagent vừa trả kết quả | Không export = mất intelligence từ subagent |
Khi HiveMind được load nhưng chưa cấu hình:
Mục tiêu: Tránh tình trạng "vừa vào đã sửa code" khi chưa hiểu project.
HiveMind is an OpenCode plugin that prevents AI agents from drifting, forgetting, and losing coherence during long coding sessions. It enforces one backbone: declare what you're doing, track as you go, archive when done.
10 tools · 6 hooks · 5 skills · 3 slash commands · interactive CLI · Ink TUI dashboard · EN/VI
Found this useful?
Without governance, long AI sessions decay:
| Problem | What Happens | HiveMind's Solution |
|---|---|---|
| Drift | Agent changes focus without checkpointing | Drift detection + escalating warnings |
| Amnesia | Context compaction erases why decisions were made | Hierarchy + anchors survive compaction |
| Blind spots | Agent writes code without reading first | FileGuard tracks write-before-read |
| Lost subagent work | Task results vanish into the void | export_cycle captures into hierarchy + mems |
| Session restart chaos | New session starts from zero | Mems Brain persists across sessions |
| No accountability | No record of what was planned vs. what happened | Full session archive with metrics |
npx hivemind-context-governance init
What happens (guaranteed):
.hivemind/ directory with brain.json, config.json.opencode/opencode.json (so OpenCode auto-loads it).opencode/OPEN mode (assisted) or LOCKED mode (strict)Works on any machine, any project. No exceptions.
The wizard walks you through step by step:
◆ Welcome to HiveMind Context Governance!
◆ Select governance mode:
│ ○ strict — Session starts LOCKED. Must declare intent before writes.
│ ● assisted — Session starts OPEN. Guidance without blocking. (recommended)
│ ○ permissive — Always OPEN. Silent tracking only.
◆ Select language:
│ ● English
│ ○ Tiếng Việt
◆ Select automation level:
│ ○ manual — No automation, you control everything
│ ○ guided — Suggestions only
│ ● assisted — Balanced automation (recommended)
│ ○ full — Maximum automation
│ ○ coach — Maximum handholding, skeptical of everything
◆ Configuration saved! .hivemind/ created.
npx hivemind-context-governance init --mode strict --lang vi --automation full
This does exactly the same as the interactive wizard:
.hivemind/ structure.opencode/opencode.jsonAfter running init, verify everything is set up:
npx hivemind-context-governance status
Or manually check .opencode/opencode.json contains:
{
"plugin": ["hivemind-context-governance"]
}
That's it. The plugin auto-activates. The AI agent gets governance context injected into every turn.
Important: If you run init again on an existing project, it will:
.hivemind/ state.opencode/opencode.jsonHow it works:
init automatically registers hivemind-context-governance in .opencode/opencode.json's plugin array.opencode/opencode.json, make sure plugin is an array containing "hivemind-context-governance"Every HiveMind session follows one pattern:
declare_intent → map_context → [work] → compact_session
This creates a 3-level hierarchy:
Trajectory (Level 1) — "Build authentication system"
└─ Tactic (Level 2) — "Implement JWT validation"
└─ Action (Level 3) — "Write middleware tests"
HiveMind fires 6 hooks automatically on every turn:
| Hook | When | What It Does |
|---|---|---|
experimental.chat.system.transform | Every LLM turn | Injects <hivemind> block with hierarchy, drift, warnings |
experimental.chat.messages.transform | Before LLM response | Injects stop-checklist and continuity context (<anchor-context>, <focus>) |
tool.execute.before | Before any tool | Governance gate — warns on writes without intent |
tool.execute.after | After any tool | Tracks metrics, detects violations, captures cycles |
session.compacting | On context compaction | Preserves hierarchy + metrics across compaction |
event | On session events | Reacts to idle/file edits/compaction and persists todo.updated into task manifest |
┌──────────────┐
│ brain.json │ ← Session state, metrics, counters
└──────┬───────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌────────────────┐ ┌─────────────┐
│hierarchy │ │ sessions/ │ │ mems.json │
│ .json │ │ manifest.json │ │ (memory) │
│ (tree) │ │ archive/ │ │ │
└──────────┘ └────────────────┘ └─────────────┘
| Mode | Session Start | Write Protection | Drift Warnings | Best For |
|---|---|---|---|---|
| strict | LOCKED | Must declare_intent first | Strong escalation | High-compliance, regulated projects |
| assisted | OPEN | Warnings on blind writes | Balanced guidance | Most projects (default) |
| permissive | OPEN | Silent tracking only | Minimal | Expert users who want freedom |
| Level | Behavior |
|---|---|
manual | No automation — you control everything |
guided | Suggestions only, never auto-acts |
assisted | Balanced automation (default) |
full | Maximum automation, minimal prompting |
coach | Maximum handholding — strict governance, skeptical output, strongest discipline |
| Tool | Agent Thought | What It Does |
|---|---|---|
declare_intent | "I want to start working" | Sets focus + mode, unlocks session |
map_context | "I'm switching focus" | Updates hierarchy, resets drift |
compact_session | "I'm done, archive this" | Archives session, preserves memory |
// Start working
declare_intent({ mode: "plan_driven", focus: "Build auth system" })
// → Session: "Build auth system". Mode: plan_driven. Status: OPEN.
// Switch focus
map_context({ level: "tactic", content: "Implement JWT validation" })
// → [tactic] "Implement JWT validation" → active
// Done
compact_session({ summary: "Auth middleware complete" })
// → Archived. 15 turns, 4 files. Session reset.
| Tool | Agent Thought | What It Does |
|---|---|---|
scan_hierarchy | "Quick status check" | Shows session state, metrics, anchors |
think_back | "I feel lost" | Deep refocus with plan review + chain analysis |
| Tool | Agent Thought | What It Does |
|---|---|---|
save_mem | "This is worth remembering" | Store decisions/patterns to persistent memory |
recall_mems | "I've seen this before" | Search or list Mems Brain by keyword/shelf |
| Tool | Agent Thought | What It Does |
|---|---|---|
save_anchor | "This must not be forgotten" | Persist constraints that survive compaction + chaos |
| Tool | Agent Thought | What It Does |
|---|---|---|
hierarchy_manage | "Clean up or migrate the tree" | Unified prune and migrate operations |
| Tool | Agent Thought | What It Does |
|---|---|---|
export_cycle | "Subagent returned — capture it" | Saves subagent results to hierarchy + mems |
HiveMind ships 3 OpenCode slash commands that work immediately after install:
| Command | Purpose |
|---|---|
/hivemind-scan | Brownfield reconnaissance — analyze, recommend, orchestrate baseline context |
/hivemind-status | Full governance status — session, hierarchy, metrics, mems, config |
/hivemind-compact | Guided session archival with pre-compact checklist |
/hivemind-scan runs a practical sequence with scan_hierarchy actions:
action: "analyze" — detect framework mode (gsd/spec-kit/both/none) + BMAD signalsaction: "recommend" — generate remediation runbookaction: "orchestrate" — persist non-destructive baseline anchors + memorySkills teach the agent how to use governance effectively:
| Skill | Purpose |
|---|---|
hivemind-governance | Bootstrap gate — loaded every turn, activates discipline |
session-lifecycle | Teaches declare → update → archive workflow |
evidence-discipline | Prove claims with output before concluding |
context-integrity | Detect drift, repair state, survive compaction |
delegation-intelligence | Subagent patterns, parallel dispatch, export_cycle |
npx hivemind-context-governance # Interactive setup wizard
npx hivemind-context-governance init # Same (or use flags)
npx hivemind-context-governance scan # Brownfield scan wrapper
npx hivemind-context-governance sync-assets # Sync packaged OpenCode assets to .opencode
npx hivemind-context-governance status # Show session state
npx hivemind-context-governance settings # Show configuration
npx hivemind-context-governance dashboard # Launch live TUI dashboard
npx hivemind-context-governance purge # Remove .hivemind/ entirely
npx hivemind-context-governance help # Show help
| Flag | Values | Default |
|---|---|---|
--mode | permissive · assisted · strict | assisted |
--lang | en · vi | en |
--automation | manual · guided · assisted · full · coach | assisted |
--expert | beginner · intermediate · advanced · expert | intermediate |
--style | explanatory · outline · skeptical · architecture · minimal | explanatory |
--code-review | (flag) | off |
--tdd | (flag) | off |
--target | project · global · both (for init/sync-assets) | project |
--overwrite | (flag, for sync-assets) | off |
--force | (flag) — removes existing .hivemind/ before re-init | off |
--action | status · analyze · recommend · orchestrate (for scan) | analyze |
--json | (flag, for scan) | off |
--include-drift | (flag, for scan status) | off |
HiveMind can sync packaged OpenCode assets (commands, skills, and optional ecosystem groups) into OpenCode paths.
# Default: project-local .opencode/
npx hivemind-context-governance sync-assets
# Global OpenCode config path (~/.config/opencode or platform equivalent)
npx hivemind-context-governance sync-assets --target global
# Sync both project and global targets
npx hivemind-context-governance sync-assets --target both
# Replace existing files (default behavior is no-clobber)
npx hivemind-context-governance sync-assets --overwrite
init also performs asset sync automatically. Re-running init on an existing project refreshes missing assets without resetting .hivemind state.
Public v2.8 package intentionally ships only the operational pack:
commandsskillsagentsworkflowsInternal playbooks (docs, templates, tasks, and local dot-folders) are kept out of public release flow.
npm install hivemind-context-governance@latest
npx hivemind-context-governance sync-assets --target project
Use --target both if you want project-local and global OpenCode paths updated together.
# Analyze framework + stack + artifact risks
npx hivemind-context-governance scan --action analyze --json
# Generate remediation sequence
npx hivemind-context-governance scan --action recommend
# Persist safe baseline anchors + memory
npx hivemind-context-governance scan --action orchestrate --json
The live terminal dashboard requires optional peer dependencies:
npm install ink react
npx hivemind-context-governance dashboard --refresh 1
Shows real-time: session state, hierarchy tree, drift score, tool call metrics, recent activity.
When OpenCode loads HiveMind before hivemind init was run:
This prevents the "agent starts coding immediately without understanding the project" failure mode.
Recommended execution order:
scan_hierarchy({ action: "analyze", json: true })
scan_hierarchy({ action: "recommend" })
scan_hierarchy({ action: "orchestrate", json: true })
declare_intent({ mode: "exploration", focus: "Brownfield stabilization" })
map_context({ level: "tactic", content: "Context purification and framework resolution" })
map_context({ level: "action", content: "Execute safe cleanup checkpoints" })
This sequence ensures framework detection, context purification, baseline persistence, and drift-safe execution before large refactors.
.hivemind/ Directory Structure.hivemind/
├── config.json # Governance settings (mode, language, automation)
├── brain.json # Session state machine (metrics, counters, hierarchy)
├── hierarchy.json # Navigable decision tree (timestamp-based nodes)
├── anchors.json # Immutable facts (survive everything)
├── mems.json # Persistent memory brain (cross-session)
├── logs/ # Runtime logs
│ └── HiveMind.log
├── templates/
│ └── session.md # Session template
└── sessions/
├── manifest.json # Session registry
├── active.md # Current session (legacy compat)
├── index.md # Project trajectory history
└── archive/ # Completed sessions
└── exports/ # Export data
# 1. Update
npm install hivemind-context-governance@latest
# 2. Re-initialize (preserves existing data)
npx hivemind-context-governance
# 3. Verify
npx hivemind-context-governance settings
# 4. Optional: clean re-init
npx hivemind-context-governance init --force
Migration handled automatically:
??= operatorssentiment_signals cleaned upCause: The plugin was never registered in .opencode/opencode.json.
Fix: Run the init command once:
npx hivemind-context-governance init --mode assisted
This does all of the following:
.hivemind/ directory structure.opencode/opencode.json (so OpenCode auto-loads it).opencode/Important: If you run init again on an existing project:
.hivemind/ state ✅| Symptom | Cause | Fix |
|---|---|---|
| Setup guidance keeps appearing | .hivemind/config.json missing | Run npx hivemind-context-governance init --mode assisted |
| Framework conflict warning | Both .planning/ and .spec-kit/ exist | Select one framework via locked menu |
| Dashboard won't start | Optional deps not installed | npm install ink react |
| Session feels stale after idle | Auto-archive rotated state | Use scan_hierarchy + think_back |
| Want fresh start | Old config causing issues | npx hivemind-context-governance purge then re-init |
| "Plugin already registered" message | Normal behavior on upgrade | No action needed |
npm run build # Full build (clean + compile + chmod)
npm run typecheck # TypeScript type checking
npm test # Run all test files (700+ assertions)
npm run dev # Watch mode
MIT
Dashboard hiển thị trạng thái real-time trên terminal:
# Cài đặt phụ thuộc
npm install ink react
# Chạy dashboard
npx hivemind-context-governance dashboard --lang vi --refresh 1
Dashboard hiển thị:
# 1. Cập nhật
npm install hivemind-context-governance@latest
# 2. Chạy lại wizard (dữ liệu cũ được giữ nguyên)
npx hivemind-context-governance
# 3. Kiểm tra
npx hivemind-context-governance settings
# 4. Nếu cần reset hoàn toàn
npx hivemind-context-governance init --force
declare_intent — Đây là "chìa khóa" mở sessionmap_context khi đổi hướng — Giữ điểm drift cao, agent không bị lạcsave_mem cho bài học quan trọng — Intelligence tích lũy qua nhiều sessionexport_cycle sau subagent — Đừng để kết quả subagent biến mấtcompact_session — Lưu trữ có cấu trúc, session sau vào lại không bị "reset trí nhớ"/hivemind-scan khi mới vào project — Hiểu project trước khi codeHiveMind được xây dựng bởi shynlee04 — một lập trình viên đã quá mệt mỏi với việc AI agent quên mất đang làm gì giữa chừng phiên code. Sau quá nhiều lần tự hỏi "khoan đã, tại sao mình lại quyết định kiến trúc này nhỉ?", ý tưởng về một hệ thống quản trị context đã ra đời.
Khi không bận xây dựng công cụ để AI "trung thực" hơn, mình thường làm việc với full-stack applications, mày mò developer tooling, và ủng hộ phong cách phát triển có sự hỗ trợ của AI mà thực sự hiệu quả.
Cảm thấy hữu ích? Mời mình ly cà phê ☕ — nó tiếp thêm năng lượng cho những đêm code muộn để tạo ra những công cụ như thế này.
Nếu bạn coi HiveMind như "bộ điều phối context" thay vì "một bộ tool phụ", chất lượng session sẽ khác biệt rõ rệt.
┌─────────────────────────────────────────────────┐
│ OpenCode Runtime │
│ ┌──────────────────────────────────────────┐ │
│ │ HiveMind Plugin (src/index.ts) │ │
│ │ │ │
│ │ ┌─────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Hooks │ │ Tools │ │ Events │ │ │
│ │ │ (6) │ │ (10) │ │ handler │ │ │
│ │ └────┬────┘ └────┬─────┘ └────┬─────┘ │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │ src/lib/ (Core) │ │ │
│ │ │ persistence · detection · │ │ │
│ │ │ hierarchy-tree · planning-fs · │ │ │
│ │ │ mems · anchors · staleness │ │ │
│ │ └──────────────┬──────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ .hivemind/ (Disk) │ │
│ └──────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ Skills (5) · Commands (3) · CLI │ │
│ └──────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
Architecture boundary: src/lib/ never imports @opencode-ai/plugin (platform-portable). Only src/hooks/ touches the SDK.
HiveMind is built by shynlee04, a developer who got tired of AI agents forgetting what they were doing halfway through coding sessions. After one too many "wait, why did we decide this architecture again?" moments, the idea for a context governance system was born.
When not building tools to keep AI honest, you'll find me working on full-stack applications, tinkering with developer tooling, and advocating for AI-assisted development that actually works.
Found this useful? Buy me a coffee ☕ — it fuels the late-night coding sessions that make tools like this possible.
Built for developers who believe AI agents should be accountable, not just capable.
FAQs
Context-Aware Governance Layer for OpenCode - prevents drift and manages session state across lifecycles
The npm package hivemind-context-governance receives a total of 20 weekly downloads. As such, hivemind-context-governance popularity was classified as not popular.
We found that hivemind-context-governance demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
TC39’s March 2026 meeting advanced eight ECMAScript proposals, including Temporal reaching Stage 4 and securing its place in the ECMAScript 2026 specification.
Research
/Security News
Since January 31, 2026, we identified at least 72 additional malicious Open VSX extensions, including transitive GlassWorm loader extensions targeting developers.
Research
Six malicious Packagist packages posing as OphimCMS themes contain trojanized jQuery that exfiltrates URLs, injects ads, and loads FUNNULL-linked redirects.