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.
Print mode
hob -p runs one prompt and exits:
hob -p "list the TODO comments in src/"hob reads the prompt from stdin when you pipe one in:
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:
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.
hob -p --input-format stream-json --output-format stream-json--include-partial-messagesadds 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-sessionresume 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:
"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.