Using Blackbox AI CLI with Hermes Agent: Multi-Model Coding Tasks

Blackbox AI CLI is a multi-model coding agent that dispatches tasks to several LLMs (Claude, Codex, Gemini, Blackbox Pro) and uses a judge to select the best implementation. You delegate coding tasks to it from the Hermes terminal. This guide covers installation, configuration, and practical usage patterns for one-shot tasks, background mode, checkpoints, PR reviews, parallel work, and multi-model mode.

What it does

Blackbox is a TypeScript coding agent (forked from Gemini CLI) that runs as an interactive terminal application. It supports interactive sessions, non-interactive one-shots, checkpointing, MCP, and vision model switching. The CLI is published as the npm package @blackbox_ai/blackbox-cli and the binary is called blackbox. When you delegate a task, Blackbox can run it through multiple models, compare the outputs, and pick the best result using a judge workflow.

Before you start

• Node.js 20+ must be installed on your system.
• Install the Blackbox CLI globally: npm install -g @blackbox_ai/blackbox-cli (binary: blackbox).
• Obtain an API key from app.blackbox.ai/dashboard.
• Configure the CLI by running blackbox configure and entering your API key.
• In Hermes terminal calls, always set pty=true because Blackbox CLI is an interactive terminal app and will hang without a PTY.

One-Shot Tasks

For a single task that runs and exits, use the --prompt flag. This is useful for quick code generation or refactoring within a specific project directory.

terminal(command="blackbox --prompt 'Add JWT authentication with refresh tokens to the Express API'", workdir="/path/to/project", pty=true)

For scratch work in a disposable directory, you can create a temp directory, initialize a git repo, and run Blackbox in one command:

terminal(command="cd $(mktemp -d) && git init && blackbox --prompt 'Build a REST API for todos with SQLite'", pty=true)

Background Mode (Long Tasks)

When a task takes minutes, run it in the background so you can monitor progress without blocking the terminal. Start the task with background=true, then use the process tool to check status, view logs, send input, or kill the session.

# Start in background with PTY
terminal(command="blackbox --prompt 'Refactor the auth module to use OAuth 2.0'", workdir="~/project", background=true, pty=true)
# Returns session_id

# Monitor progress
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

# Send input if Blackbox asks a question
process(action="submit", session_id="<id>", data="yes")

# Kill if needed
process(action="kill", session_id="<id>")

Checkpoints & Resume

Blackbox CLI has built-in checkpoint support for pausing and resuming tasks. After a task completes, Blackbox shows a checkpoint tag. You can resume from that checkpoint with a follow-up prompt.

# After a task completes, Blackbox shows a checkpoint tag
# Resume with a follow-up task:
terminal(command="blackbox --resume-checkpoint 'task-abc123-2026-03-06' --prompt 'Now add rate limiting to the endpoints'", workdir="~/project", pty=true)

Session Commands

During an interactive session, use these commands to manage the conversation:

Command	Effect
/compress	Shrink conversation history to save tokens
/clear	Wipe history and start fresh
/stats	View current token usage
Ctrl+C	Cancel current operation

PR Reviews

To review a pull request without modifying your working tree, clone the repository to a temporary directory, check out the PR, and run Blackbox with a review prompt.

terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && blackbox --prompt 'Review this PR against main. Check for bugs, security issues, and code quality.'", pty=true)

Parallel Work

You can spawn multiple Blackbox instances for independent tasks. Each runs in its own working directory and background session. Use process(action="list") to monitor all running sessions.

terminal(command="blackbox --prompt 'Fix the login bug'", workdir="/tmp/issue-1", background=true, pty=true)
terminal(command="blackbox --prompt 'Add unit tests for auth'", workdir="/tmp/issue-2", background=true, pty=true)

# Monitor all
process(action="list")

Multi-Model Mode

Blackbox's unique feature is running the same task through multiple models and judging the results. Configure which models to use via blackbox configure, select multiple providers to enable the Chairman/judge workflow where the CLI evaluates outputs from different models and picks the best one.

Key Flags

Flag	Effect
--prompt "task" (-p)	Non-interactive one-shot execution
--resume-checkpoint "tag"	Resume from a saved checkpoint
--yolo (-y)	Auto-approve all actions and model switches
--vlm-switch-mode	Image-handling: once, session, or persist
-c, --checkpointing	Enable checkpointing of file edits
blackbox configure	Change settings, providers, models
blackbox update	Update the CLI to the latest version
blackbox mcp	Manage MCP servers
blackbox extensions	Manage CLI extensions
blackbox voice / blackbox shortcut	Configure voice input / the b shortcut

Vision Support

Blackbox automatically detects images in input and can switch to multimodal analysis. VLM modes:

• "once", Switch model for current query only
• "session", Switch for entire session
• "persist", Stay on current model (no switch)

Token Limits

Control token usage via .blackboxcli/settings.json:

{
  "sessionTokenLimit": 32000
}

Rules

1. Always use pty=true, Blackbox CLI is an interactive terminal app and will hang without a PTY
2. Use workdir, keep the agent focused on the right directory
3. Background for long tasks, use background=true and monitor with process tool
4. Don't interfere, monitor with poll/log, don't kill sessions because they're slow
5. Report results, after completion, check what changed and summarize for the user
6. Credits cost money, Blackbox uses a credit-based system; multi-model mode consumes credits faster
7. Check prerequisites, verify blackbox CLI is installed before attempting delegation

When not to use it

Blackbox is designed for coding tasks. It is not a general-purpose assistant. If your task does not involve writing, reviewing, or refactoring code, consider other tools. Also, because Blackbox uses a credit-based system, avoid using it for trivial or repetitive tasks that could be done with simpler scripts.

Limits and gotchas

• Blackbox CLI is an interactive terminal app; without pty=true, it will hang indefinitely.
• Multi-model mode consumes credits faster than single-model mode.
• The CLI must be installed and configured before use; delegation will fail if the binary is not found.
• Background sessions can be monitored but not interacted with beyond sending input via process(action="submit").
• Checkpoints are shown after task completion; you must note the tag to resume later.

Related skills

This skill pairs well with other autonomous coding agents available in Hermes Agent: claude-code, codex, and hermes-agent itself. Each has different strengths and model backends, so you can choose the best tool for the task at hand.