Blackbox Skill for Hermes Agent: Multi-Model Coding Delegation

Blackbox is an optional Hermes Agent skill that hands coding work to the Blackbox AI command-line agent, which runs a task through several models and picks the strongest result. You would reach for it when you want a second opinion baked into the execution itself, or when a task is worth spending extra credits to get a better implementation. If you already delegate to a single-model CLI, this is the variant that trades cost for comparison.

What it does

The skill wraps the Blackbox CLI, an npm package published as @blackbox_ai/blackbox-cli with the binary name blackbox. It is a TypeScript coding agent forked from Gemini CLI, and it supports interactive sessions, non-interactive one-shots, checkpointing, MCP, and vision model switching. What sets it apart from the other coding-agent skills is the multi-model dispatch: the same task can be sent to Claude, Codex, Gemini, and Blackbox Pro, with a judge step selecting the best implementation. Hermes invokes it through the terminal tool, so the skill is really a set of conventions for calling that CLI correctly from an agent loop.

Before you start

The source lists five prerequisites, and each one matters in practice:

• Node.js 20 or newer must be installed.
• The CLI itself must be present: npm install -g @blackbox_ai/blackbox-cli (binary: blackbox).
• You need an API key from app.blackbox.ai/dashboard.
• The key has to be configured: run blackbox configure and enter your API key.
• Terminal calls must use pty=true, because Blackbox CLI is an interactive terminal app.

The last point is the one that bites people. Without a PTY the CLI hangs, so every terminal invocation in this guide carries that flag. The skill is listed for linux, macos, and windows, so the platform itself is not a constraint; the Node version and the global install are.

One-Shot Tasks

For a single, well-scoped job, pass the task with --prompt and point workdir at the project:

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

For quick scratch work, the source shows a throwaway directory pattern that initialises a fresh git repo first:

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

That second form is useful when you want the agent to build something from nothing without touching an existing tree. The git init gives the CLI a repository to work against.

Background Mode (Long Tasks)

Anything that will take minutes should run in the background so you can watch it rather than block. The source's pattern starts the process with a PTY and a background flag, then uses the process tool to poll, read logs, answer questions, 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>")

The submit action is there because an interactive agent may stop and ask. Keep the session id from the start call; every follow-up action needs it.

Checkpoints & Resume

Blackbox CLI has built-in checkpoint support, which lets you pause a line of work and pick it up with a follow-up instruction. The source notes that after a task completes, Blackbox shows a checkpoint tag, and you resume with --resume-checkpoint:

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

This is the right tool when a change is too large for one prompt but you do not want to restart from scratch. Treat the checkpoint tag as state you must capture; if you lose it, you lose the thread.

Session Commands

Inside an interactive session, these commands control 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

/compress is the one you will use most on long sessions, since context growth is what usually forces a restart. /stats tells you where you stand before that happens.

PR Reviews

The source recommends cloning into a temporary directory so the review does not modify your working tree:

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)

This pattern depends on gh being available for the checkout step. The isolation is the point: the agent reads and comments on code in a disposable clone rather than editing the branch you are working on.

Parallel Work

Independent tasks can run as separate Blackbox instances, each in its own scratch directory, with process(action="list") to monitor them all:

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

# Monitor all
process(action="list")

Keep the tasks genuinely independent. Two agents editing the same files in parallel will collide, and the source's separate scratch directories are a hint that isolation is your responsibility.

Multi-Model Mode

The distinguishing feature is running one task through several models and judging the outputs. You configure which models participate through blackbox configure: select multiple providers to enable the Chairman/judge workflow, where the CLI evaluates outputs from different models and picks the best one. This is the reason to choose Blackbox over a single-model coding CLI, and also the reason it costs more, since credits are consumed per model.

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

--yolo deserves caution: it auto-approves actions and model switches, which removes the confirmation step that would otherwise catch a bad plan. Use it in scratch directories, not on a branch you care about.

Vision Support

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

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

Pick once for a single screenshot, session when the whole task is visual, and persist when you want to stay on the current model regardless.

Token Limits

You can cap session token usage through .blackboxcli/settings.json:

{
  "sessionTokenLimit": 32000
}

Setting a limit is a guardrail against runaway context on long sessions, and it pairs naturally with /compress and /stats.

When not to use it

If your task is simple and single-model work is enough, the multi-model judge adds cost without adding much. The source's related skills, claude-code and codex, cover single-agent delegation, and hermes-agent covers the runtime itself. Reach for Blackbox when comparison across models is the value you want.

Limits and gotchas

The source's rules are worth restating in full. Always use pty=true, because the CLI is interactive and will hang without a PTY. Always set workdir so the agent stays in the right directory. Run long tasks with background=true and monitor through the process tool. Do not interfere: use poll and log to watch, and do not kill a session just because it is slow. Report results when it finishes by checking what changed and summarising for the user. Remember that credits cost money, and multi-model mode burns them faster. And verify the blackbox CLI is installed before you attempt delegation, since a missing binary fails the whole call.

What pairs with it

Use claude-code or codex when a single model is sufficient, and hermes-agent for the surrounding runtime. Together they let you route each task to the cheapest agent that can do it well.