Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@hiveai/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@hiveai/cli

hAIve — policy enforcement for AI coding agents.

hAIve makes your team knowledge enforceable. 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 policy, run agents inside hAIve, check the repo, and block unsafe workflow states.

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 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. Add durable policy knowledge manually (or let the agent use mem_save/mem_tried)
haive memory add \
  --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
haive benchmark report --dir benchmarks/agent-benchmark

Commands

`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 bridge file generation (CLAUDE.md, .cursorrules, etc.)
haive init --dir /other/path  # Initialize in a specific directory

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)
├── .cursorrules                  # Bridge for Cursor (auto-generated)
└── .github/
    └── copilot-instructions.md   # Bridge for GitHub Copilot (auto-generated)

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 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 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

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

`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 add`

haive memory add \
  --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 add --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 query`

Full-text search across id, tags, and body.

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

`haive memory show`

Print the full body, frontmatter, and usage stats of a memory.

haive memory show 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:

Checks every anchored memory: does the file/symbol still exist? → marks stale if not
Re-validates previously stale memories that are now fresh again
Auto-promotes proposed memories that have been read enough times
Reports a decay warning for memories not read in >90 days
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 add        → 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

@hiveai/cli

Package Exports

Readme

@hiveai/cli

Install

Quick start

Commands

haive init

haive enforce

haive benchmark

haive run

haive mcp

haive memory

haive memory add

haive memory list

haive memory query

haive memory show

haive memory update

haive memory verify

haive memory approve / promote / reject

haive memory tried

haive memory import

haive memory for-files

haive memory stats / hot / pending / digest

haive briefing

haive sync

haive install-hooks

haive embeddings

haive index

haive tui

haive session end

Memory lifecycle

Multi-component projects

Semantic search (optional)

License

`haive init`

`haive enforce`

`haive benchmark`

`haive run`

`haive mcp`

`haive memory`

`haive memory add`

`haive memory list`

`haive memory query`

`haive memory show`

`haive memory update`

`haive memory verify`

`haive memory approve` / `promote` / `reject`

`haive memory tried`

`haive memory import`

`haive memory for-files`

`haive memory stats` / `hot` / `pending` / `digest`

`haive briefing`

`haive sync`

`haive install-hooks`

`haive embeddings`

`haive index`

`haive tui`

`haive session end`