Hive_review: Multi-agent AI code-review loop

Notifications You must be signed in to change notification settings

Fork 0

Star 1

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

1 Commit

1 Commit

agents

agents

lib

lib

skills

skills

unit_tests

unit_tests

.gitignore

.gitignore

README.md

README.md

hive_review

hive_review

logo.png

logo.png

model_config.json

model_config.json

Repository files navigation

./hive_review \

Git worktree to review; subdirs normalize to the Git root.

--repo-dir /path/to/repo \

Prompts, responses, ids, logs, transcripts, and status live under --session-dir.

--session-dir sessions/my-review \

One implementor model config from model_config.json.

--implementor 'GPT-5.5-xhigh-login' \

One or more reviewer model configs, comma-separated.

--reviewers 'GPT-5.4-xhigh-login,Claude-Opus-4.8-max-login' \

Pause after --max-rounds review/fix rounds; interactive mode can continue.

--max-rounds 5 \

Optional; omit --prompt to review the current diff.

--prompt "Fix the failing parser tests"

hive_review automates a multi-agent review loop:

An implementor agent writes or fixes code.

One or more reviewer agents review the current diff.

Reviewer feedback is sent back to the implementor.

The loop repeats until all reviewers return HIVE_REVIEW_STATUS: PASS.

It is a Ruby CLI and library. Runtime state is local to this repo: provider homes, transcripts, prompt/response artifacts, session ids, and cleanup logs are kept out of user-global Codex, Claude, Gemini, Grok, OpenCode, or Kimi config by default. Codex, Claude, Gemini, Grok, OpenCode, and Kimi are supported as real unattended implementor/reviewer providers. DeepSeek is supported through OpenCode: use the agents/opencode wrapper with a DeepSeek model config and DEEPSEEK_API_KEY.

Commands

hive_review agents/codex agents/claude agents/gemini agents/grok agents/opencode agents/kimi lib/log_in lib/login_all lib/log_out lib/logout_all lib/cleanup

agents/codex, agents/claude, agents/gemini, agents/grok, and agents/opencode, and agents/kimi are model-config driven wrappers.

Provider CLI Installation

--check, lib/log_in, and lib/login_all try to install a missing real provider CLI before printing manual instructions.

Codex:

npm install -g @openai/codex

Claude:

npm install -g @anthropic-ai/claude-code curl -fsSL claude.ai/install.sh | bash

Gemini:

npm install -g @google/gemini-cli brew install gemini-cli

Grok:

curl -fsSL https://x.ai/cli/install.sh | bash npm install -g @xai-official/grok

OpenCode:

curl -fsSL https://opencode.ai/install | bash npm install -g opencode-ai

DeepSeek support uses OpenCode, so no separate DeepSeek wrapper is required. Install OpenCode, then select an OpenCode-backed DeepSeek config such as OpenCode-DeepSeek-V4-Pro-high-api.

Kimi:

curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash npm install -g @moonshot-ai/kimi-code

On Linux, use the npm commands or provider curl installers. On macOS, Homebrew alternatives are supported where listed.

Platforms

Supported:

macOS

Linux

Windows through WSL

Native Windows terminals such as PowerShell and cmd.exe are intentionally not supported. On Windows, clone and run this project inside WSL.

Model Config

Selectable implementor and reviewer names come from top-level model_config.json. The file is a plain object keyed by display name:

{ "GPT-5.5-xhigh-login": { "agent": "codex", "model": "gpt-5.5", "effort": "xhigh", "auth": "login" }, "Codex-GPT-5.3-xhigh-api": { "agent": "codex", "model": "gpt-5.3-codex", "effort": "xhigh", "auth": "api-key", "api_key_env": "OPENAI_API_KEY" }, "Claude-Opus-4.8-max-login": { "agent": "claude", "model": "claude-opus-4-8", "effort": "max", "auth": "login" } }

The display-name key is the CLI selector and the interactive menu label. It is also used for local provider-home names, so keep it path-safe: letters, numbers, dots, underscores, and hyphens.

Default seeded configs:

GPT-5.5-xhigh-login

GPT-5.4-xhigh-login

Codex-GPT-5.3-xhigh-api

Claude-Opus-4.8-max-login

Claude-Sonnet-4.6-max-login

Optional provider examples you can add to model_config.json:

{ "Gemini-3.1-Pro-default-login": { "agent": "gemini", "model": "gemini-3.1-pro-preview", "effort": "default", "auth": "login" }, "Gemini-3.1-Pro-default-api": { "agent": "gemini", "model": "gemini-3.1-pro-preview", "effort": "default", "auth": "api-key", "api_key_env": "GEMINI_API_KEY" }, "Gemini-2.5-Flash-Lite-default-login": { "agent": "gemini", "model": "gemini-2.5-flash-lite", "effort": "default", "auth": "login" }, "Grok-Build-0.1-default-login": { "agent": "grok", "model": "grok-build", "effort": "default", "auth": "login" }, "Grok-Build-0.1-default-api": { "agent": "grok", "model": "grok-build", "effort": "default", "auth": "api-key", "api_key_env": "XAI_API_KEY" }, "OpenCode-DeepSeek-V4-Pro-high-api": { "agent": "opencode", "model": "deepseek/deepseek-v4-pro", "effort": "high", "auth": "api-key", "api_key_env": "DEEPSEEK_API_KEY" }, "Kimi-For-Coding-default-login": { "agent": "kimi", "model": "kimi-for-coding", "effort": "default", "auth": "login" }, "Kimi-For-Coding-default-api": { "agent": "kimi", "model": "kimi-for-coding", "effort": "default", "auth": "api-key", "api_key_env": "MOONSHOT_API_KEY" } }

DeepSeek configs use agent: "opencode" and provider-shaped model names such as deepseek/deepseek-v4-pro. You can add more DeepSeek variants by adding more OpenCode entries with different display names, model ids, efforts, or API key env vars.

Kimi configs use agent: "kimi" and model names such as kimi-for-coding. The example API-key config reads MOONSHOT_API_KEY and maps it into Kimi's runtime KIMI_API_KEY environment variable.

You can add multiple entries for the same real provider model with different auth or effort, for example:

{ "GPT-5.5-xhigh-login": { "agent": "codex", "model": "gpt-5.5", "effort": "xhigh", "auth": "login" }, "GPT-5.5-xhigh-api": { "agent": "codex", "model": "gpt-5.5", "effort": "xhigh", "auth": "api-key", "api_key_env": "OPENAI_API_KEY" } }

Validation rules:

agent must be codex, claude, gemini, grok, opencode, or kimi.

Codex auth may be login or api-key.

Claude auth may be login or api-key.

Gemini auth may be login or api-key.

Grok auth may be login or api-key.

OpenCode auth is api-key in hive_review. The key is injected from the configured api_key_env into the isolated OpenCode process environment.

Kimi auth may be login or api-key.

Effort is validated per agent.

Model names are flexible provider-shaped strings, so newly released provider models can be added without changing Ruby code.

Quick Start

Run from inside a repo and use defaults:

/path/to/hive_review/hive_review

Review a specific repo with explicit models:

./hive_review \ --repo-dir /path/to/repo \ --implementor 'GPT-5.5-xhigh-login' \ --reviewers 'Claude-Opus-4.8-max-login'

Use a prompt:

./hive_review \ --repo-dir /path/to/repo \ --prompt "Implement input validation and update tests"

Pipe a prompt:

printf '%s\n' "Fix the current diff until reviewers pass." | ./hive_review --repo-dir /path/to/repo

Try a dry run without launching providers:

./hive_review \ --dry-run \ --no-ui \ --repo-dir /path/to/repo \ --reviewers 'GPT-5.4-xhigh-login,Codex-GPT-5.3-xhigh-api,Claude-Opus-4.8-max-login'

If --implementor or --reviewers is omitted in an interactive terminal, hive_review asks you to choose from model_config.json.

Top-Level CLI

./hive_review [options] [prompt] printf '%s\n' "prompt" | ./hive_review [options] ./hive_review --cleanup DIR ./hive_review --cleanup --all

Important options:

--session-dir DIR Directory for review artifacts. If omitted, defaults to sessions/review-YYYY-MM-DD_HH-MM-SS. If the directory already contains a hive_review session, interactive mode asks whether to resume or quit.

--repo-dir DIR Git repository or worktree directory. Subdirectories normalize to the Git root. Default: current directory.

--implementor NAME One model config display name from model_config.json. Default: GPT-5.5-xhigh-login.

--reviewers LIST Comma-separated model config display names. Duplicate reviewers are ignored. Default: Claude-Opus-4.8-max-login.

--implementor-session-id ID Seed implementor/session.id from an outside provider session. Use this when an implementation was written before starting hive_review and the tool should resume that same implementor conversation. The id must be a UUID.

--initial-implementation Open an interactive implementor session first, wait until you exit it, then start the normal review loop using that provider session as the implementor. Alias: --implement-first.

--max-rounds N Maximum review/fix rounds. Default: 5. If reviewers still request changes at the limit in interactive mode, type continue review to add one more round.

--prompt TEXT Initial user task for the implementor.

--prompt-file FILE Read the initial prompt from a file. Relative paths resolve from the launch directory, not from --repo-dir.

--no-diff Do not include automatic Git diff context in prompts.

--dry-run Validate selections and write session config without launching providers. Still prompts unless --no-ui is also set.

Review Loop

Reviewers must end responses with one marker:

HIVE_REVIEW_STATUS: PASS

or:

HIVE_REVIEW_STATUS: CHANGES_REQUESTED

Reviewers in the same round are launched in parallel. Their outputs are then aggregated in the configured reviewer order. Missing status markers are treated as requested changes.

If all reviewers pass, the session status becomes complete. If max rounds are reached and the human does not continue, status becomes max_rounds_reached.

Provider Wrappers

Real wrappers share this interface:

agents/codex --model-config 'GPT-5.5-xhigh-login' [options] ["review prompt"] agents/claude --model-config 'Claude-Opus-4.8-max-login' [options] ["review prompt"] agents/gemini --model-config 'Gemini-3.1-Pro-default-login' [options] ["review prompt"] agents/grok --model-config 'Grok-Build-0.1-default-login' [options] ["review prompt"] agents/opencode --model-config 'OpenCode-DeepSeek-V4-Pro-high-api' [options] ["review prompt"] agents/kimi --model-config 'Kimi-For-Coding-default-api' [options] ["review prompt"] printf '%s\n' "review prompt" | agents/codex --model-config 'GPT-5.5-xhigh-login' [options] agents/codex --model-config 'GPT-5.5-xhigh-login' --check agents/codex --model-config 'GPT-5.5-xhigh-login' --cleanup

Options:

--model-config NAME Required for direct wrapper calls. The top-level orchestrator passes this automatically.

--check Check or install the underlying CLI, verify auth/config, then exit.

--cleanup Archive/delete provider session state where the provider supports it, then remove the local standalone session.id.

--raw Send the prompt directly instead of wrapping it in reviewer instructions.

--role ROLE Transcript role label. Default: reviewer.

The wrapper must match the config's agent: Codex configs run through agents/codex; Claude configs run through agents/claude; Gemini configs run through agents/gemini; Grok configs run through agents/grok; OpenCode configs run through agents/opencode; Kimi configs run through agents/kimi.

Auth

Provider homes are repo-local and shared by direct wrapper runs and top-level sessions. They are created from configured display names; examples:

.hive_review_state/provider_homes/GPT-5.5-xhigh-login/ .hive_review_state/provider_homes/GPT-5.4-xhigh-login/ .hive_review_state/provider_homes/Codex-GPT-5.3-xhigh-api/ .hive_review_state/provider_homes/Claude-Opus-4.8-max-login/ .hive_review_state/provider_homes/Claude-Sonnet-4.6-max-login/ .hive_review_state/provider_homes/Gemini-3.1-Pro-default-login/ .hive_review_state/provider_homes/Gemini-3.1-Pro-default-api/ .hive_review_state/provider_homes/Gemini-2.5-Flash-Lite-default-login/ .hive_review_state/provider_homes/Grok-Build-0.1-default-

[truncated for AI cost control]