Headless mode

Run hob without the TUI, from a script, a CI job, an SDK, or an editor that speaks ACP.

hob also runs without its terminal UI: as a one-shot command (print mode), as a process that an SDK drives (SDK mode), or as an agent server for an editor (ACP). The flags and the output are compatible with Claude Code, so you can put hob in place of it in an existing setup.

hob -p runs one prompt and exits:

Terminal
hob -p "list the TODO comments in src/"

hob reads the prompt from stdin when you pipe one in:

Terminal
git diff | hob -p "write a commit message for this diff"
Flag What it does
--output-format text Prints the last answer (default).
--output-format json Prints one JSON result at the end.
--output-format stream-json Prints each event as one JSON line, while hob works.
--verbose Adds every message of each turn to the output.
--image <path> Attaches an image to the prompt. You can repeat it.
-m <provider/model> Sets the model.
--max-turns <n> Stops after n agent turns.
--allowed-tools <list> Allows only these tools, separated by commas.
--disallowed-tools <list> Removes these tools, separated by commas.
--system-prompt <text> Replaces the system prompt.
--append-system-prompt <text> Adds text to the system prompt.
--yolo Skips the permission prompts. Deny rules still apply.

Tool names can be in snake_case (code_execution) or in Claude Code’s PascalCase (CodeExecution).

On macOS, hob keeps the computer out of idle sleep while a -p run works. hob.setup({ agent = { prevent_sleep = false } }) turns that off.

Background tasks

By default, hob -p runs with background tasks off, so it exits right after its answer. --background-timeout <secs> lets the tool calls move to the background. hob then stays up for that long after the input ends, and each result that comes back in time wakes the model for another turn. hob stops the tasks that still run after that time.

Autoreview in print mode

With --autoreview, hob reviews and repairs the changes of the run before it exits:

Terminal
hob -p --autoreview "fix the failing parser test"

When the last review is not clean, hob -p exits with status 3. A script or a CI job can fail on that status. See Autoreview.

CI and containers

A project’s .hob/ folder loads only after you trust the folder. In a container or a CI job, where nothing is kept, --trust loads it for one run without a question and without saving an answer. Use it only on a project that you trust. See Folder trust.

SDK mode

--input-format stream-json with -p speaks the Claude Code SDK protocol on stdin and stdout. The process stays up for many turns.

Terminal
hob -p --input-format stream-json --output-format stream-json
  • --include-partial-messages adds the partial messages of a reply while it streams.
  • --permission-mode <mode> sets the permission mode.
  • --session-id <id> writes the run under an id that you choose.
  • -c, -r <id>, and --fork-session resume a session, as in the TUI.

ACP

hob acp runs hob as an Agent Client Protocol server over stdio, for editors such as Zed. For example, in Zed’s settings.json:

json
"agent_servers": {
  "Hob": {
    "type": "custom",
    "command": "hob",
    "args": ["acp"],
    "env": {}
  }
}

hob acp -m <provider/model> sets the model, and hob acp --yolo skips the permission prompts. Each ACP session has its own state.

Flags that hob ignores

hob accepts some Claude Code flags only so that the existing callers do not break. It prints a warning and ignores them. Among them are --max-budget-usd, --fallback-model, --mcp-config, and --settings. See the CLI reference.

Keyboard shortcuts

Go to

On this page

  • jkNext or previous section
  • 12…The section with that number
  • cCopy the install command
  • iDownload
  • dDocs
  • []Previous or next page

Anywhere

  • ?Show or hide this list
  • EscClose, or stop a "g"