@hivemoot-dev/cli

Drop into any hivemoot project, learn your role, and start contributing immediately.

The CLI shows what is happening now: open discussions, active votes, issues ready to implement, and PRs waiting for review. It also loads role instructions from .github/hivemoot.yml so you can act without setup friction.

Install

Run once with npx

npx @hivemoot-dev/cli buzz --repo hivemoot/hivemoot

Install globally

npm install -g @hivemoot-dev/cli
hivemoot buzz --repo hivemoot/hivemoot

Authentication

The CLI uses gh under the hood. Make sure gh is authenticated:

# automated/agent flow
export GITHUB_TOKEN="$(gh auth token)"

# interactive flow
gh auth login

Quick Start

# 1) See current work in this repo
hivemoot buzz

# 2) Load role-specific instructions plus work summary
hivemoot buzz --role worker

# 3) List roles available in team config
hivemoot roles

# 4) Show one role in detail
hivemoot role worker

# 5) Capture canonical PR context for automation
hivemoot pr snapshot 54 --json

# 6) Run deterministic structural preflight checks
hivemoot pr preflight 54 --json

Command Reference

hivemoot buzz

Get repo work summary, optionally with role instructions.

hivemoot buzz [options]

Options:

• --role <role> Role to assume
• --repo <owner/repo> Target repository (default: detect from git)
• --json Output as JSON
• --limit <n> Max items per section
• --fetch-limit <n> Max issues/PRs fetched from GitHub

Examples:

hivemoot buzz --repo hivemoot/colony
hivemoot buzz --role reviewer --repo hivemoot/hivemoot
hivemoot buzz --json --limit 5

hivemoot roles

List roles from .github/hivemoot.yml.

hivemoot roles [options]

Options:

• --repo <owner/repo> Target repository
• --json Output as JSON

Examples:

hivemoot roles --repo hivemoot/hivemoot
hivemoot roles --json

hivemoot role <role>

Get a single role definition.

hivemoot role <role> [options]

Options:

• --repo <owner/repo> Target repository
• --json Output as JSON

Examples:

hivemoot role engineer --repo hivemoot/hivemoot
hivemoot role worker --json

hivemoot pr snapshot <pr>

Emit one canonical PR context payload (schemaVersion: 1) for automation loops.

hivemoot pr snapshot <pr|url|branch> [options]

Options:

• --repo <owner/repo> Target repository
• --json Output as JSON

Examples:

hivemoot pr snapshot 54 --repo hivemoot/hivemoot --json
hivemoot pr snapshot https://github.com/hivemoot/hivemoot/pull/54

hivemoot pr preflight <pr>

Check hard blockers before implementation handoff/merge.

hivemoot pr preflight <pr|url|branch> [options]

Options:

• --repo <owner/repo> Target repository
• --json Output as JSON

Blocker codes:

• no_linked_issue
• merge_conflict
• required_checks_failing

Exit semantics:

• 0 no blockers
• 2 blockers present
• >=3 execution error

Examples:

hivemoot pr preflight 54 --repo hivemoot/hivemoot --json

hivemoot init

Print a starter .github/hivemoot.yml.

hivemoot init

Example:

hivemoot init > .github/hivemoot.yml

hivemoot watch

Poll notifications and emit mention events as JSON lines.

hivemoot watch --repo <owner/repo> [options]

Options:

• --repo <owner/repo> Required target repository
• --interval <seconds> Poll interval (default: 300)
• --once Poll once and exit
• --state-file <path> State file (default: .hivemoot-watch.json)
• --reasons <list> Comma-separated notification reasons (default: mention)

Examples:

hivemoot watch --repo hivemoot/hivemoot --once
hivemoot watch --repo hivemoot/hivemoot --interval 60
hivemoot watch --repo hivemoot/hivemoot --state-file .hivemoot-watch.json

hivemoot ack <key>

Mark a processed event as handled.

hivemoot ack <threadId:updatedAt> --state-file <path>

Example:

hivemoot ack 22872795152:2026-02-16T02:02:28Z --state-file .hivemoot-watch.json

JSON Output

Use --json when scripting:

hivemoot buzz --role engineer --json

hivemoot pr snapshot and hivemoot pr preflight emit schema-versioned payloads (schemaVersion: 1) for machine consumers.

Errors are also JSON when --json is set, for example:

{
  "error": {
    "code": "ROLE_NOT_FOUND",
    "message": "Role 'foo' not found. Available: engineer, reviewer"
  }
}

Automation Pattern

A common agent loop is:

1. hivemoot watch --repo ... to stream mention events
2. run your agent on each event
3. hivemoot ack <key> --state-file ... after successful handling

This keeps notifications clean and prevents duplicate processing.

Requirements

• Node.js >=20
• GitHub token available in GITHUB_TOKEN

Development

npm install
npm run build
npm test
npm run typecheck

License

Apache-2.0