Hive CLI

Hive turns a repository into durable agent workflows. Its built-in coding workflow moves tasks through brainstorm, plan, execute, open PR, review, artifacts, and finalize stages. Reviewed Honeycomb packages provide additional workflows, and the daemon advances enrolled projects in the background.

Use this skill to install or operate the Hive CLI. It is a command adapter, not permission to mutate the host: inspect first and apply the consent rules below.

Install From ClawHub

Install the single public skill with:

openclaw skills install @ivankuznetsov/hive-cli

This installs the /hive slash command. First use is normally:

/hive setup

Common Paths

• /hive setup verifies or installs Hive, provisions local web/daemon support, and offers to enroll the current project.
• /hive doctor --json diagnoses the runtime and managed agent skills without changing them; /hive setup-agents previews unresolved managed skills and asks once before provisioning.
• /hive status --json shows task stages, markers, holds, PR URLs, and next actions; /hive tui and /hive web provide live terminal and browser views.
• /hive new . "build this feature" creates a task. /hive plan <task-slug>, /hive develop <task-slug>, and /hive review <task-slug> operate the main coding path.
• /hive workflow install honeycomb/<name> installs a reviewed workflow package. /hive workflow list --json inspects installed generations.
• /hive patrol <project> runs an ordinary defect patrol; /hive refactor-patrol <project> discovers architecture improvements.
• /hive digest produces the daily shipped digest. /hive bench submit <task-slug> prepares a completed task for the hive-bench corpus.
• /hive wiki compile-log --check verifies wiki/log.md against fragments in wiki/log.d/.

Current Hive also enforces declared task dependencies before dispatch, retains durable ownership across retries, and applies scoped tool/file permissions to reviewed workflow actors. These are runtime guarantees, not extra commands the agent should reproduce.

Custom Workflows

Hive supports project-authored workflows for writing, feedback triage, research, and other staged work:

hive workflow new <id> [--template <name>]
hive init . --workflow <id>
hive new . --workflow <id> "draft launch notes"

Reviewed Honeycomb packages use a separate lifecycle. First preview the exact operation with a supported no-write command:

hive workflow install honeycomb/<name> --dry-run --json
hive workflow update <name> --dry-run --json
hive workflow remove <name> --dry-run --json

After the user reviews that output and explicitly approves the disclosed mutation, execute only the corresponding command:

hive workflow install honeycomb/<name> --yes --json
hive workflow update <name> --yes --json
hive workflow remove <name> --yes --json

Never append --yes unless the user explicitly pre-authorized the displayed action. If the preview discloses high risk or permission growth, explain that separately and get separate explicit approval before adding --allow-escalation; do not infer escalation authorization from ordinary install or update consent. Use hive workflow list --json for read-only inspection of installed generations.

Managed agent-skill provisioning follows the same preview/approval split:

hive setup-agents --json
# Only after the user approves the returned plan:
hive setup-agents --yes --json

When changes are planned, the preview's consent-required response and nonzero exit are expected; present its plan rather than treating that response as a failure. The --yes execution must match the scope the user reviewed.

Agent and council stages may declare budget_usd and timeout_sec. These are per-spawn limits. On subscription-backed providers, a native budget field is a runaway guard and does not mean Hive is making an additional payment.

CLI Detection

Before dispatch, detect Hive without confusing it with Apache Hive:

if hive --version 2>/dev/null | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
  hive_cmd=hive
elif hv --version 2>/dev/null | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
  hive_cmd=hv
else
  hive_cmd=
fi

If hive_cmd is empty, offer guided setup. Explain that setup installs the CLI and per-user services and can enroll the current project. Get explicit user confirmation before running an installer.

Guided Setup

Show the chosen command and wait for confirmation. Keep the package manager's normal transaction review and confirmation prompt; never add flags that suppress it.

• macOS arm64: brew tap ivankuznetsov/hive && brew install ivankuznetsov/hive/hive
• Arch Linux with yay: yay -S --needed hive-bin
• Arch Linux with paru: paru -S --needed hive-bin
• Ubuntu 22.04+ or compatible glibc Linux x86_64/aarch64:

tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
curl -fsSL https://raw.githubusercontent.com/ivankuznetsov/hive/v0.6.4/install.sh -o "$tmpdir/hive-install.sh"
bash "$tmpdir/hive-install.sh"

For Arch Linux, display the selected yay or paru transaction for the user to run in their own real terminal. Do not execute it through a non-TTY tool call, and never add --noconfirm; the operator must review and confirm the package-manager transaction interactively.

The Linux installer obtains and verifies the signed release artifact. After an approved install, repeat the strict hive / hv version check. If neither prints a bare X.Y.Z, stop and report failure or possible Apache Hive shadowing. If verification succeeds, run "${hive_cmd}" setup --no-init --json for core provisioning and summarize the installed version, every setup phase, exact service/install outcome, explicitly skipped enrollment, and any diagnose-only login instructions.

Initial project enrollment is a separate, consent-gated step. Explain that a non-TTY hive init takes defaults that enable medium patrol, architecture discovery, daemon dispatch, and the babysitter. Those facilities consume provider subscription capacity and can eventually open PRs. After the user has reviewed and explicitly approved enrollment, ask them to run hive init . in their own real terminal. They can choose patrol mode off and answer no to the architecture patrol, daemon, and babysitter prompts; do not invent a --no-patrol flag or run init headlessly on their behalf.

/hive install and /hive bootstrap are aliases for this guided flow.

Dispatch Rules

Otherwise, treat the user's slash-command text after /hive as arguments for hive_cmd. With no arguments, run "${hive_cmd}" --help. Run from the current workspace unless the user named another project. Pass arguments safely as an argv array; never interpolate raw user text into a shell string.

Prefer --json for inspection and summarize the task slug, stage, marker, action, hold/retry state, PR URL, and suggested next command when present.

Daemon auto-advance is covered by the user's previously approved enrollment. When the enrolled coding daemon is healthy, a printed next: line is a manual fallback or recovery command: do not execute the printed command merely because it appeared. Let the daemon own ordinary progression. Stop for needs_input, unanswered questions, destructive or external actions, Safety Boundaries actions, or a request for manual control. When uncertain, inspect hive daemon status --json; if the daemon or enrollment is absent, offer the printed command as an optional action and wait for approval.

For hive wiki compile-log, use --check for verification. Run the mutating compiler only after merge/rebase or when explicitly requested; feature changes add wiki/log.d/<timestamp>-<slug>.md instead of editing compiled wiki/log.md.

Patrol And Architecture Patrol

Patrol is opt-in autonomous agent work and consumes the operator's provider subscription. Before starting a manual /hive patrol or /hive refactor-patrol, show the project, current patrol.mode, and whether the run can open PRs, then get explicit user confirmation. An already configured daemon schedule carries its prior consent; monitor it without re-confirming each tick.

The low, medium, high, and ultrapatrol tiers have successively larger per-cycle launch and token ceilings. Architecture patrol gets 2x the selected tier's per-cycle and per-agent allowance because cross-boundary analysis needs more context, while both patrol types retain the same shared daily ceiling and provider-native budget guard. Missing usage telemetry still consumes launch quota. Do not describe this as a paid patrol: on subscription-backed agents it uses the existing subscription.

Token statistics in hive tui are a human-only interactive handoff: ask the user to open it and press T to inspect today/7d/30d/all usage, including the combined patrol attribution row. An agent may report configured limits and an observed hold/retry state from machine-readable output, but must not claim exact token totals because this skill documents no machine-readable token-stat command. If headroom is exhausted, report the hold or retry time; do not bypass the configured limit or start parallel patrols.

Status Bundle

For a read-only overview, gather:

hive daemon status --json
hive status --json
systemctl --user status hive-daemon.service --no-pager

For each task with a PR URL, run gh pr checks <number> when gh is available. Summarize stage, marker, action, PR URL, CI status, live PID, held/retry, and suggested command. On macOS or without systemctl/gh, report the unavailable field instead of failing the bundle.

Watch Selected Tasks

When asked to monitor tasks, use bounded polling of hive status --json with a clear interval and timeout (defaults: 15 seconds and 30 minutes). Report only meaningful state changes and PR availability, call out entry into 7-artifacts or 8-finalize, and return a final snapshot at timeout. Ctrl-C is safe: this watch never kills Hive agents, never clears markers, and never advances stages.

Daemon Diagnostics And Repair

Diagnose before repairing:

command -v hive
hive --version
hive doctor --json
hive daemon status --json
systemctl --user cat hive-daemon.service

If systemctl is unavailable, use the platform service details returned by Hive. Explain binary drift, missing dependencies, or service state from these read-only results before proposing a fix.

Never patch an installed Hive runtime or write service-manager configuration directly. Prefer Hive-native setup and repair commands:

hive setup --no-init --json
hive daemon install --force --json
hive daemon status --json

The --no-init setup form repairs core provisioning without enrolling the current project; enrollment remains the separate interactive Guided Setup step described above. setup and daemon install --force change persistent per-user state. Show the specific command and diagnosis, restate the effect, and get explicit user confirmation before running either repair. Afterward, verify with doctor, version, and daemon status. If Hive reports a dependency-specific manual command, present it for review; do not execute it automatically.

Safety Boundaries

Read-only inspection includes status, doctor, rebase-status, findings, metrics, daemon/bot status, and workflow list. The exact Honeycomb lifecycle previews documented above (workflow install, workflow update, and workflow remove, each with --dry-run --json) are also no-write inspections. These do not need confirmation.

Do not generalize that exemption to every --dry-run command. In particular, hive patrol ... --dry-run and hive refactor-patrol ... --dry-run still launch agents and consume subscription capacity; ordinary patrol dry-run may also persist scan state. Both remain consent-gated patrol starts.

Before destructive or persistent admin verbs (drop, uninstall, update, forget, prune, or migrate), restate the effect and get explicit user confirmation. Apply the same rule to workflow install/update/remove/publish, setup-agents, patrol starts, outbound digest/bench submit, and nested commands daemon stop, daemon disable --all, daemon install --force, bot stop, bot install --force, markers clear, or approve --force.

Prefer hive daemon start --detach for startup. Before hive daemon start without detach, hive daemon tail, hive bot start --foreground, or hive bot tail, explain that it can hold the session and get explicit user confirmation.

Marker Recovery

Inspect with hive status --json and hive daemon status --json. If the daemon is stopped, offer hive daemon start --detach. When it is running, let the healer handle known bounded recovery cases:

1. REVIEW_ERROR phase=fix reason=fix_failed with claude stop hook did not signal completion: let the healer retry; ask before a manual clear only after its budget is exhausted.
2. Other fix_failed: investigate the actual fix failure. It is manual; ask before clearing.
3. limits_reached with valid retry_after: wait for the cooldown and let the healer requeue. A missing or malformed retry time is manual.
4. Stale agent_working: a live PID/lock means wait; an orphaned agent may be healer-managed; a dead agent rewritten to ERROR reason=agent_died is manual.
5. Other documented healer-managed errors: let the healer use its bounded retry budget, then ask before intervention.
6. Terminal/manual ERROR: inspect the reason and ask before clearing it.

hive markers clear mutates task state and always follows Safety Boundaries. After explicit approval, prefer an observed marker identity:

hive markers clear <folder> --name ERROR --match-attr marker_id=<id>

Then rerun only the stage-specific recovery command reported by current status.