@hiveai/cli

hAIve - repo-native memory and context policy for coding-agent harnesses.

hAIve makes your team knowledge enforceable inside the harness around AI coding agents. It gives agents a required briefing before work starts, stores decisions/gotchas/failed attempts as version-controlled Markdown, and adds MCP, Git, CI, and wrapper gates so AI-generated changes cannot quietly bypass project policy.

The memory system is the mechanism. The CLI is the control plane: initialize context policy, run agents inside hAIve, check the repo, and block unsafe workflow states. hAIve complements tests, linters, evals, and observability by carrying the repo-specific knowledge they cannot infer.

Install

npm install -g @hiveai/cli

This installs the haive command globally. The MCP server is bundled — use haive mcp --stdio in your AI client (no separate @hiveai/mcp install required for normal use).

Semantic search (optional): install @hiveai/embeddings for local embedding-based search (no data leaves your machine).

Legacy configs may still use the standalone haive-mcp binary from @hiveai/mcp; prefer haive so CLI and MCP versions always match.

Quick start

# 1. Initialize hAIve in your project (strict enforcement ON by default)
cd my-project
haive init                          # .ai/, MCP config, hooks, CI, code-map
haive agent status                  # confirm MCP/wrapper/fallback mode
haive enforce install               # re-apply strict MCP + Git + CI enforcement gates

# 2. Point your AI client at the MCP server
# Add to ~/.claude.json / ~/.cursor/mcp.json:
# { "mcpServers": { "haive": { "command": "haive", "args": ["mcp", "--stdio", "--root", "/absolute/path"] } } }

# 3. Bootstrap project context (run once in your AI client)
# → Use the bootstrap_project MCP prompt to analyze the codebase and fill .ai/project-context.md

# 4. Start work through hAIve
haive briefing --task "add Stripe webhook"
haive run -- <agent-command> [args...]      # for CLI agents without blocking hooks

# 5. Save durable policy knowledge manually (or let the agent use mem_save/mem_tried)
haive memory save \
  --type gotcha --slug "jpa-open-in-view" --scope team \
  --paths src/main/resources/application.properties \
  --body "spring.jpa.open-in-view=false is intentional — do not re-enable."

# 6. Gate the workflow
haive enforce status
haive enforce check --stage pre-commit
haive enforce ci

Commands

The default help is intentionally small and centered on the core harness workflow. Run:

haive --help
haive memory --help

to see the focused surface. Maintenance and experimental commands remain available, but are hidden from default help:

haive --advanced --help
haive --advanced memory --help

This keeps hAIve from feeling like a grab bag: day-to-day users see the core harness loop first - context loading, enforcement, diagnostics, sync, recaps, and the high-signal memory operations.

haive init

Initialize the .ai/ structure in a project. Autopilot mode is ON by default and now installs strict enforcement gates by default.

haive init                    # Autopilot: policy config, hooks, CI, MCP setup, code-map
haive init --manual           # Manual mode: you approve every memory yourself
haive init --no-bridges       # Skip native bridge generation (CLAUDE.md, AGENTS.md, etc.)
haive init --dir /other/path  # Initialize in a specific directory
haive init --yes              # Also approve user-level AI client MCP configuration

Autopilot mode (default):

• Memories are saved directly as validated (no approval cycle)
• Git hooks installed automatically (haive enforce check gates commits/pushes)
• CI workflows generated (haive-enforcement.yml and sync workflow)
• Initial code-map built (.ai/code-map.json) for symbol lookup
• Session recaps saved automatically when the MCP server exits
• Configuration stored in .ai/haive.config.json

Manual mode (--manual):

• Memories start as proposed and require explicit approval (haive memory approve)
• No automatic hooks or CI — set up manually with haive install-hooks and haive init --with-ci
• Full control over when knowledge becomes team policy

What it creates:

your-project/
├── .ai/
│   ├── project-context.md        # Shared project overview (fill via bootstrap_project MCP prompt)
│   ├── haive.config.json         # Autopilot settings
│   ├── modules/                  # Per-component context files
│   └── memories/
│       ├── personal/             # Private to one developer
│       ├── team/                 # Shared with the whole team (git-committed)
│       └── module/<name>/        # Scoped to a specific module/component
├── CLAUDE.md                     # Bridge for Claude Code (auto-generated)
├── AGENTS.md / GEMINI.md / …     # 12 native bridges total (Cursor, Cline, Windsurf,
│                                 #   Continue, Cody, Zed, Roo, Aider, Copilot…)
└── .github/
    └── copilot-instructions.md   # Bridge for GitHub Copilot (auto-generated)

Each bridge carries the repo's validated memories and block sensors — not just an empty template — so the enforcement edge travels to non-MCP agents too. Regenerate with haive bridges sync; scope with haive init --bridge-targets cursor,copilot. Bridge files include mandatory rules, but they are not the enforcement boundary. hAIve's portable enforcement comes from MCP policy, Git hooks, CI checks, and haive run -- <agent> for CLI agents.

haive init also runs agent-aware setup. It always writes project-level MCP configs and records the selected mode in .ai/.runtime/enforcement/agent-mode.json. When it needs to change user-level configs such as Cursor, Claude Code, VS Code, Windsurf, or Codex, it asks for confirmation in an interactive shell. In CI/non-interactive shells, re-run:

haive agent setup --yes

haive agent

Detect and configure the best hAIve mode for the current machine.

haive agent detect                 # inspect project MCP + installed agents
haive agent status                 # same report, human-readable or --json
haive agent setup                  # project MCP + optional global MCP setup
haive agent setup --no-global      # project-only setup, no user config writes
haive agent setup --yes            # approve user-level MCP config writes

Modes:

• mcp: native hAIve tools are available through the AI client.
• wrapped: use haive run -- <agent> when native MCP is unavailable.
• fallback: use haive briefing and haive enforce check manually.

haive enforce

Install and run the agent-agnostic policy gates.

haive enforce install                 # strict config + Git hooks + CI + supported client hooks
haive enforce status                  # show whether the repo is protected
haive enforce check --stage local     # local policy gate
haive enforce check --stage pre-push  # used by Git hooks
haive enforce ci                      # used by required CI checks
haive enforce finish                  # final agent-exit gate: commit/push + version/tag protocol
haive enforce cleanup                 # remove generated .ai runtime/cache artifacts

Strict mode checks for:

• a recent hAIve briefing marker before local write workflows
• recent session recap before push/CI gates
• stale important memories anchored to changed code
• decision coverage: changed files must have their relevant anchored policies surfaced in the latest briefing
• known anti-patterns from validated gotchas/decisions
• visible generated artifacts such as .ai/.runtime, .ai/.cache, or Python bytecode
• completed work is committed/pushed; shippable package changes have lockstep version bump + git tag

haive enforce check prints an enforcement score and fails strict gates when the score drops below the configured threshold.

haive sensors

Operate executable regex sensors stored on gotcha/attempt memories.

haive sensors list
haive sensors check                    # scans git diff --cached
haive sensors check --diff-file diff.patch --json
haive sensors promote <memory-id> --yes
haive sensors export --format grep

Autogenerated sensors are conservative: they start as warn and autogen: true. A human can promote high-confidence sensors to severity: block, which makes a deterministic pre-commit blocker when the sensor matches added diff lines.

haive ingest

Seed proposed, anchored memories (with sensors) from scanner output, so a fresh repo has policy from day one instead of an empty corpus.

haive ingest --from sonar issues.json --min-severity major
haive ingest --from sarif report.sarif
haive ingest --from eslint eslint-report.json
haive ingest --from npm-audit audit.json --scope team
haive ingest --from sonar-api --sonar-component my_project   # pull straight from SonarQube
haive ingest --from sarif report.sarif --dry-run             # preview without writing

A quality floor runs by default: auto-fixable stylistic rules (semi/quotes/indent/prefer-const/ prettier… and the equivalent Sonar numeric keys) are dropped as linter-autofix noise, not lessons. Pass --include-stylistic to keep them. Created memories are proposed with warn-only sensors — review with haive memory list --status proposed and promote vetted sensors with haive sensors promote.

haive coverage

Find changed files that no memory covers — the blind spots in your corpus.

haive coverage                       # cross corpus with git churn + agent-edited hot files
haive coverage --source git          # only committed churn
haive coverage --source agent        # only files agents edited (PostToolUse observation log)

haive eval

Run the repeatable quality gate for hAIve itself or for a project using hAIve:

haive eval
haive eval --semantic-only
haive eval --spec .ai/eval/spec.json --fail-under 80

Without --spec, hAIve synthesizes retrieval cases from anchored memories. If .ai/eval/spec.json exists, it is loaded automatically and merged with those synthesized retrieval cases. Use that file for labeled sensor cases and hard retrieval probes so CI measures both “did the right memory surface?” and “did the executable guardrail fire?”.

haive doctor

doctor is the first stop when hAIve feels inconsistent locally:

haive doctor
haive doctor --json
haive doctor --fix

It reports missing pnpm, stale workspace dist artifacts after a pull, global CLI/MCP version skew, outdated code-search indexes, memory-lint findings, and harness coverage. The output is intentionally actionable: every setup finding should carry the exact command to run next.

haive benchmark

Turn hAIve-vs-plain agent trials into a repeatable demo/report.

haive benchmark demo
haive benchmark report --dir benchmarks/agent-benchmark
haive benchmark report --dir benchmarks/agent-benchmark --out RESULTS.md

The report summarizes agent effort from BENCHMARK_AGENT_REPORT.md files: commands, files read, files modified, test iterations, terminal failures, decision mentions, token proxy, and whether hAIve memory shaped the outcome.

haive run

Wrap any CLI-based coding agent in a hAIve session.

haive run -- claude
haive run -- codex
haive run -- aider
haive run -- <custom-agent> [args...]

The wrapper writes a compact briefing file and exports:

• HAIVE_PROJECT_ROOT
• HAIVE_SESSION_ID
• HAIVE_BRIEFING_FILE
• HAIVE_ENFORCEMENT=strict
• HAIVE_TOOL_PROFILE=enforcement

haive mcp

Run the hAIve MCP server over stdio (bundled into this package — same tools as legacy haive-mcp).

haive mcp --stdio                     # typical MCP client args (stdio marker optional but recommended)
haive mcp -d /path/to/project         # resolve project root from this directory
haive mcp --root /path/to/project     # alias for legacy haive-mcp --root

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "haive": {
      "command": "haive",
      "args": ["mcp", "--stdio", "--root", "/absolute/path/to/your/project"]
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "haive": {
      "command": "haive",
      "args": ["mcp", "--stdio", "--root", "/absolute/path/to/your/project"]
    }
  }
}

VS Code:

code --add-mcp '{"name":"haive","command":"haive","args":["mcp","--stdio","--root","/path/to/project"]}'

haive memory

Manage individual memory entries.

haive memory save

(Canonical verb; haive memory add remains as an alias.)

haive memory save \
  --type <type> \          # convention | decision | gotcha | architecture | glossary | attempt
  --slug <slug> \          # Short identifier used in the filename
  --scope team \           # personal (default) | team | module
  --title "My title" \     # Optional heading (auto-added to body)
  --tags "auth,jwt" \      # Comma-separated tags
  --domain payments \      # Business domain for relevance scoring
  --paths src/auth.ts \    # Anchor to files (enables staleness detection)
  --symbols JwtFilter \    # Anchor to symbols/functions
  --body "The knowledge."  # Memory content (Markdown)

# Read body from a file (useful for long memories):
haive memory save --type architecture --slug "payment-flow" \
  --body-file docs/payment-architecture.md

Memory types:

| Type | When to use | |---|---| | convention | How things are done here: naming, patterns, workflow | | decision | A choice that was made and WHY (tradeoffs, constraints) | | gotcha | Non-obvious behavior, traps, things that surprise newcomers | | architecture | Structural overview of a system or module | | glossary | Domain terms and their meaning in this project | | attempt | Failed approach — prevents the same mistake next session |

haive memory list

haive memory list                        # All memories
haive memory list --scope team           # Team memories only
haive memory list --status validated     # Only validated
haive memory list --type gotcha          # Gotchas only
haive memory list --tags auth,jwt        # By tags (AND match)
haive memory list --module payments      # Module-scoped memories

haive memory search

Full-text (or semantic) search across id, tags, and body. (haive memory query remains as an alias.)

haive memory search "flyway migration"         # AND search across all tokens
haive memory search "payment mobile wave"      # Falls back to OR if no AND match
haive memory search "jwt" --scope team --limit 5

haive memory get

Print the full body, frontmatter, and usage stats of a memory. (haive memory show remains as an alias.)

haive memory get 2025-01-15-gotcha-flyway-strict

haive memory update

Update a memory's body, tags, or anchor without changing its id or history.

haive memory update <id> --body "Updated content."
haive memory update <id> --tags "auth,jwt,security"
haive memory update <id> --paths src/auth.ts,src/jwt.ts

haive memory verify

Check anchor freshness — detect stale memories when anchored files or symbols have moved.

haive memory verify           # Check all memories
haive memory verify --id <id> # Check a specific one
haive memory verify --update  # Write stale/validated status back to disk

When a file is missing, hAIve searches the project for files with the same basename and suggests possible renames.

haive memory approve / promote / reject

Control the memory lifecycle: draft → proposed → validated or rejected.

haive memory approve <id>       # Mark as validated
haive memory approve --all      # Bulk-approve all proposed/draft
haive memory promote <id>       # Promote personal → team (status: proposed)
haive memory reject <id> --reason "Outdated after refactor"

haive memory tried

Record a failed approach — the most valuable type of negative knowledge.

haive memory tried \
  --what "importing gray-matter with ESM dynamic import" \
  --why-failed "gray-matter doesn't export a default; named import required" \
  --instead "import matter from 'gray-matter'" \
  --scope team \
  --paths src/parser.ts

Auto-validated (no approval cycle needed). Surfaced first in get_briefing so agents see it before making the same mistake.

haive memory import

Import documentation (README, ADR, wiki page) as memories via the import_docs MCP prompt.

haive memory import --from docs/architecture.md --scope team

Prints the MCP import_docs invocation to run in your AI client.

haive memory for-files

Show memories relevant to specific files you're about to edit.

haive memory for-files src/payments/PaymentService.java src/payments/PaymentController.java

haive memory stats / hot / pending / digest

haive memory stats     # Usage stats and confidence levels for all memories
haive memory hot       # Most-read unvalidated memories (good promotion candidates)
haive memory pending   # Proposed memories awaiting review

# Generate a Markdown review digest for bulk approval/rejection:
haive memory digest                  # Last 7 days, team scope (prints to stdout)
haive memory digest --days 14        # Last 14 days
haive memory digest --scope all      # All scopes
haive memory digest --out digest.md  # Write to file

The digest groups memories by type, shows confidence level (⬜ unverified / 🟡 low / 🟢 trusted / ⭐ authoritative), anchor, read count, and action checkboxes for easy bulk review.

haive briefing

Print the full project briefing — project context + relevant memories — in one shot. Use before starting a task.

haive briefing                                           # Full briefing, team scope
haive briefing --task "add a Stripe payment"             # Filter by task relevance
haive briefing --files src/payments/PaymentService.java  # Filter by files
haive briefing --symbols PaymentService,TenantFilter     # Look up symbol locations in code-map
haive briefing --scope all                               # Include personal memories
haive briefing --include-stale                           # Include stale memories
haive briefing --max-memories 15                         # Show more memories

--symbols (requires haive index code): look up where specific symbols are defined across your entire codebase — no grep needed. Returns file, line number, kind (class/interface/function/enum), and JSDoc description for each match.

PaymentProvider  src/payments/PaymentProvider.java:12  [interface]  — Abstract payment provider
PaymentProvider  src/frontend/payment.types.ts:4       [enum]       — Mobile payment provider enum

haive sync

Refresh memory state after a git pull or merge.

haive sync                          # Verify anchors + auto-promote eligible memories
haive sync --since main             # Report memories changed since main
haive sync --inject-bridge          # Inject top memories into CLAUDE.md
haive sync --embed                  # Rebuild embeddings index after sync
haive sync --quiet                  # Minimal output (for git hooks)

What sync does:

1. Checks every anchored memory: does the file/symbol still exist? → marks stale if not
2. Re-validates previously stale memories that are now fresh again
3. Auto-promotes proposed memories that have been read enough times
4. Reports a decay warning for memories not read in >90 days
5. Optionally injects the top validated memories into your CLAUDE.md

haive install-hooks

Install git hooks so haive sync runs automatically after every pull/merge.

haive install-hooks         # Install post-merge and post-rewrite hooks
haive install-hooks --dir /path/to/project

haive embeddings

Manage the local semantic search index (requires @hiveai/embeddings to be installed).

haive embeddings index          # Build or refresh the embeddings index
haive embeddings status         # Show index stats (count, last updated, model)
haive embeddings query "how do we handle retries on payment failures"

The model (bge-small-en-v1.5, ~110MB) is downloaded on first use and cached locally. No data leaves your machine.

haive index

Build code navigation indexes.

haive index code        # Build .ai/code-map.json (file → exports + 1-line descriptions)

The code map lets AI agents find where a function lives without grepping — dramatically reducing tool calls at the start of a task.

haive tui

Interactive terminal dashboard with 3 screens — browse, filter, and manage memories without leaving the terminal.

haive tui               # Open the TUI
haive tui --dir /path/to/project

Screens (switch with 1 2 3):

| Screen | Key | What it shows | |---|---|---| | Memories | 1 | Full list + preview panel, filter by status (Tab), actions | | Health | 2 | Stale memories, pending review, anchorless memories | | Stats | 3 | Top-read memories, decaying (>90d unused), totals by status |

Actions (in Memories screen):

| Key | Action | |---|---| | ↑ ↓ | Navigate | | Tab | Cycle filter (all / draft / proposed / validated / stale / rejected) | | a | Approve (→ validated) | | r | Reject | | p | Propose (→ proposed) | | d | Delete | | q | Quit |

haive session end

Save a structured end-of-session recap. Surfaced automatically at the start of the next session via get_briefing.

haive session end \
  --goal "Add Stripe payment integration" \
  --accomplished "Implemented PaymentService, added tests, deployed to staging" \
  --discoveries "The webhook signature must use the raw request body, not parsed JSON" \
  --files "src/payments/PaymentService.ts,src/payments/webhook.ts" \
  --next "Add retry logic for failed webhooks" \
  --scope team

One recap is kept per scope (topic-upsert: revision_count increments on each call).

Memory lifecycle

haive memory save       → status: draft
haive memory promote    → status: proposed  (personal → team)
haive memory approve    → status: validated
haive sync              → status: stale     (if anchor broken)
haive memory reject     → status: rejected

Validated team memories are loaded into every get_briefing call and injected into bridge files.

Multi-component projects

For projects with frontend + backend (or microservices), create one module context per component:

# After haive init, create module context files:
mkdir -p .ai/modules/backend .ai/modules/frontend

cat > .ai/modules/backend/context.md << 'EOF'
# Module: backend
- Spring Boot, Java 17, PostgreSQL
- Always filter by tenantId in every query
- Never modify existing Flyway migrations
EOF

cat > .ai/modules/frontend/context.md << 'EOF'
# Module: frontend
- React 19, TypeScript, TanStack Query
- All API calls go through hooks in features/<domain>/api/
- Env vars must be prefixed with VITE_
EOF

get_briefing auto-loads the relevant module context based on the files the agent is editing.

Semantic search (optional)

Install @hiveai/embeddings for similarity-based memory retrieval:

npm install -g @hiveai/embeddings
haive embeddings index          # First run downloads the model (~110MB)
haive embeddings query "payment retry logic"

From MCP: set semantic: true on mem_search or get_briefing.

License

MIT