Delegating coding tasks to Blackbox CLI

How to use

Blackbox CLI installed: npm install -g @blackbox_ai/blackbox-cli (binary: blackbox)

Run blackbox configure and enter your API key to complete configuration.

Use pty=true in terminal calls — Blackbox CLI is an interactive terminal app.

Run a one-shot task with --prompt "task" (-p) for non-interactive execution.

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

For quick scratch work, start from a fresh temporary directory.

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

Use background mode for long tasks.

For tasks that take minutes, use background mode so you can monitor progress.

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

After a task completes, resume from a saved checkpoint with --resume-checkpoint "tag" and 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)

During an interactive session, use these commands:

/compress shrinks conversation history to save tokens, /clear wipes history and starts fresh, /stats shows current token usage, and Ctrl+C cancels the current operation.

For PR reviews, clone the repository to a temporary directory first.

Clone to a temp directory to avoid modifying the 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)

For parallel work, spawn multiple Blackbox instances in background mode, one per independent task, and monitor them all with process(action=list).

Spawn multiple Blackbox instances for independent tasks.

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

Blackbox can run the same task through multiple models and judge the results: configure which models to use via blackbox configure, selecting multiple providers to enable the Chairman/judge workflow where the CLI evaluates outputs from different models and picks the best one.

Key flags: --prompt "task" (-p) runs a non-interactive one-shot; --resume-checkpoint "tag" resumes from a saved checkpoint; --yolo (-y) auto-approves all actions and model switches; --vlm-switch-mode <mode> sets image handling (once, session, or persist); -c, --checkpointing enables checkpointing of file edits; blackbox configure changes settings, providers, and models; blackbox update updates the CLI to the latest version; blackbox mcp manages MCP servers; blackbox extensions manages CLI extensions; blackbox voice <action>/blackbox shortcut configure voice input and the b shortcut.

Blackbox automatically detects images in input and can switch to multimodal analysis. VLM modes: "once" switches the model for the current query only.

"session" switches the model for the entire session.

"persist" stays on the current model with no switch.

Control token usage via .blackboxcli/settings.json, for example by setting a session token limit.

Control token usage via .blackboxcli/settings.json.

{
  "sessionTokenLimit": 32000
}

Always use pty=true — Blackbox CLI is an interactive terminal app and will hang without a PTY.

Use workdir to keep the agent focused on the right directory.

For long tasks, run in background with background=true and monitor with the process tool.

Don't interfere — monitor with poll/log and don't kill sessions just because they're slow.

After completion, check what changed and summarize the results for the user.

Credits cost money: Blackbox uses a credit-based system, and multi-model mode consumes credits faster.

Check prerequisites before delegating: verify the blackbox CLI is installed.

Links

• Blackbox AI