Configuration

Every setting of init.lua, the other config files, and where hob keeps its data.

Settings go in init.lua, a Lua script that calls hob.setup(). Same language as plugins.

Two places, both optional:

  • Global: ~/.config/hob/init.lua
  • Project: .hob/init.lua in the active Git checkout, or in the working directory outside Git

When both exist, project settings override global ones. Neither file is required. A project init.lua runs only once you trust that folder, see Folder Trust.

Example

lua
hob.setup({
    ui = {
        splash_animation = true,
        mouse_scroll_lines = 6,
        theme = "tokyonight",
        modals = {
            rewind = { width = 90 },
        },
        tool_output_lines = {
            bash = 6,
            read = 2,
        },
    },
    agent = {
        max_output_lines = 3000,
    },
    provider = {
        default_model = "anthropic/claude-sonnet-4-6",
        allowed_models = { "anthropic/*", "openai/gpt-5" },
        excluded_models = { "*/*-preview" },
    },

    storage = {
        max_log_files = 5,
    },
    plugins = {
        bash = { timeout_secs = 180 },
        index = { max_file_size_mb = 4 },
    },
})

All fields are optional. Typos in field names cause an error right away.

provider.allowed_models is a list of glob patterns for qualified provider/model-id specs. * also matches /, so opencode/* includes nested model IDs. When the list is empty or omitted, every model is allowed. provider.excluded_models removes matching models after that, so exclusions always win. A project list replaces the matching global list; omit it to inherit or use {} to clear it. The policy applies to selectors, CLI and API model changes, delegation, and hob models.

hob.setup() can only be called once per init.lua.

Full Reference

Top-level

Field Type Default Description
yolo bool false Start every session with YOLO mode (skip permission prompts, deny rules still apply)
always_fast bool false Start every session with fast mode (Anthropic Opus or eligible Codex subscription models, ignored elsewhere)
always_workflow bool false Start every session with workflow mode (task callable inside code_execution)
always_thinking bool | string none Pin the thinking level of every new session: true/“adaptive”, false/“off”, “minimal” to “max”, or a token budget. Unset, new sessions start at the last /thinking level

ui

Field Type Default Min Description
splash_animation bool true - Animate the Hob splash. The Hob blinks, and its character art also shows rising thoughts. When disabled, the Hob keeps its eyes open. The splash uses the bundled PNG when terminal graphics are available and falls back to character art
scrollbar bool true - Show vertical scrollbar in scrollable areas
inline_images bool true - Render inline images in terminals with graphics support, falling back to an [image] line where nothing else names the image. Set false to disable graphics for both inline images and the Hob splash
copy_icon bool true - Show a theme-tinted image copy button on message cards in terminals with Kitty graphics support. Requires ui.inline_images = true. Falls back to [copy] when inline images are disabled, graphics support is unavailable, or theme colors are not RGB. Set false to always use [copy]
transparent_background bool false - Use the terminal default background for ordinary theme styles, preserving selection, cursor, and diff highlights. Configure actual transparency in your terminal
selection_style “subtle” | “high_contrast” | “strong” subtle - Selection style: subtle uses the current theme-colored background; high_contrast (alias: strong) swaps foreground and background for high contrast
selection_color string unset - Optional selection background override for subtle selection style only; high_contrast ignores it. Accepts #RRGGBB, ANSI color names (e.g. blue), numeric strings from 0 to 255 (e.g. “42”), or “default” for the terminal background. Unset uses the theme selection background
user_color string unset - Optional color for your messages in the chat, overriding the theme’s user color for every theme. Accepts #RRGGBB, ANSI color names (e.g. blue), numeric strings from 0 to 255 (e.g. “42”), or “default” for the terminal foreground. Unset uses the theme color
assistant_color string unset - Optional foreground color for assistant text in the chat, overriding the theme’s assistant color for every theme without changing its prefix. Accepts #RRGGBB, ANSI color names (e.g. blue), numeric strings from 0 to 255 (e.g. “42”), or “default” for the terminal foreground. Unset uses the theme color
notifications string auto - Notification method: auto, osc9, bell, notify, or off
terminal_progress string auto - Terminal agent progress method: auto, on, or off
flash_duration_ms u64 3000 - Duration of flash messages (ms)
typewriter_ms_per_char u64 2 - Typewriter effect speed (ms/char)
copy_feedback_ms u64 1500 - How long the Copied label and success icon stay on a card (ms)
mouse_scroll_lines u32 4 1 Lines per mouse wheel scroll
max_input_lines u32 20 1 Maximum visible input lines
paste_collapse bool true - Visually collapse large pastes in the chat input without changing the text sent to the model. /paste_collapse on/off saves the choice for every tab and later starts, overriding this option
paste_collapse_lines u32 10 1 Line threshold for collapsing pasted text. /paste_collapse N enables collapsing and saves the threshold, overriding this option on later starts
paste_preview_chars u32 60 1 Maximum Unicode characters in the text shown in each collapsed paste preview, excluding the label and ellipsis
input_wrap “word” | “character” word - Chat-input wrapping only: word keeps words whole, falling back to character wrapping for overlong words. character wraps anywhere
terminal_cursor bool true - Show the terminal’s own cursor in the chat input, with the shape, color and blink your terminal sets. false paints the cell under the cursor with the theme cursor style instead
vim_mode bool false - Edit the chat input, and the guidance after a denied permission, with vim keys. /vim turns it on or off and saves the choice, which wins over this option on later starts
vim_clipboard bool false - Copy what a vim yank takes to the system clipboard
thinking_lines integer -1 - Show model reasoning in full by default (-1). N >= 0 collapses it to a header and its last N wrapped rows. Click to toggle. 0 shows only the header. Legacy show_thinking maps true to -1 and false to 0. Conflicting values in the same config are rejected
show_context_updates bool true - Show concise context-update notices live and in restored transcripts. Hiding them leaves the full updates in model requests and session history
assistant_name string hob - Name shown before the agent’s replies in the chat, e.g. “Robin”. Must not be blank or contain control characters. /youare sets it and saves the choice, which wins over this option on later starts
clock_format String system - Clock format for timestamps: “12h”, “24h”, or “system” (follow the OS preference, 24h when unknown)
hobify_search_commands string[] [] - Tool names and shell programs whose calls get the searching Hob while /hobify is on. They add to the built-in grep, glob, list, websearch, rg, fd, find, ag, ack, ls, tree and locate. A bash call counts by the first program it runs after any cd
hobify_rows u16 6 2 Height in rows of the Hob beside each tool call while /hobify is on, at most 24. Its width follows from its shape. A transcript too narrow for it and the text beside it shows no Hob
worktree_command string[] [] - The command /fork --worktree makes its git worktree with, such as ["git", "wt", "-n"]. It runs in the checkout with the name added, and the last line it prints is the new worktree’s path, absolute or relative to the checkout. Empty runs git worktree add -b <name> next to the checkout

ui.terminal_progress

Reports aggregate agent status to the terminal using OSC 9;4, independently of ui.notifications. Nash needs no hook setup or nash agent-status install.

Value Behavior
auto (default) Enable in Nash and WezTerm when running the interactive TUI with terminal stdout.
on Override terminal detection, still only in the interactive TUI with terminal stdout.
off Send no terminal progress controls, including cleanup.

Hob emits no progress escape sequences with non-TTY stdout or in --print, SDK, and ACP modes, even with on. Notification defaults stay unchanged. Set notifications = "off" in your existing ui table if Nash handles sounds and alerts and you want to avoid duplicate Hob notifications. See Notifications for that setting.

All live Hob sessions share one pane status, regardless of the selected session or terminal focus. Input requests, including permission prompts, questions, authentication retries, and ready plans, take precedence over work in other sessions. Otherwise active or queued runs, their subagents, and compaction keep the status working until all queued work drains. A terminal run failure is reported before clearing, deferred while other sessions remain active. Working and paused states refresh once a second so quiet sessions keep their status. Idle status is not refreshed.

Cancellation clears progress only when no other session owns work or attention. Hob also clears its reported state before exit, reload, editor launch, or suspend, and republishes current status on return. OSC 9;4 has no neutral cancellation state, so Nash may record cancellation or terminal handoff clears as completed. An uncatchable kill cannot send cleanup and may leave stale status, especially inside tmux.

Multiplexers and SSH

tmux requires passthrough. Add this to ~/.tmux.conf and reload it:

set -g allow-passthrough on

Use allow-passthrough all instead for updates from hidden tmux windows. If tmux hides the outer terminal identity, set terminal_progress = "on" in your ui table. Hob does not change tmux configuration for you.

Progress forwarding through GNU screen and Zellij is unverified. Their notification or clipboard support does not establish OSC 9;4 support, and on cannot make a multiplexer forward a protocol it drops.

Over SSH, use on when terminal identity is missing only if the interactive PTY and every intervening layer carry OSC 9;4.

ui.theme

Name of the color theme to load at startup, overriding the theme you last picked interactively. If unset, Hob keeps your last selection (the built-in default on first run). An unknown name is ignored with a warning.

To match a light or dark terminal, give a theme for each:

lua
theme = { light = "catppuccin_latte", dark = "catppuccin_macchiato" }

Hob asks the terminal for its background color once at startup, and uses dark if it gets no answer. Restart Hob after your terminal switches between light and dark.

Add transparent_background = true to the ui table in your existing hob.setup({...}) call, then run /reload. This clears backgrounds from ordinary theme styles while preserving them for selections, cursors, and diffs. Set the terminal’s actual opacity in its own settings. The option defaults to false and stays active when you switch themes.

Available themes: ayu_dark, ayu_light, ayu_mirage, carbonfox, catppuccin_frappe, catppuccin_latte, catppuccin_macchiato, catppuccin_mocha, dark_daltonized, dracula, everforest_dark, fleet_dark, github_dark, gruvbox, gruvbox_dark_hard, gruvbox_dark_soft, gruvbox_light, gruvbox_light_hard, gruvbox_light_soft, kanagawa, kanagawa_ink, kanagawa_plum, material_darker, monokai_pro, night_owl, nightfox, nord, one_light, onedark, rose_pine, rose_pine_dawn, rose_pine_midnight, rose_pine_moon, solarized_dark, solarized_light, system, tokyonight, vscode_dark_plus, zenburn.

You can add your own themes too. Drop a <name>.toml file into themes/ inside your Hob config directory, for example ~/.config/hob/themes/. If it reuses a built-in name, yours wins.

A theme file has three tables: [palette] names colors, [ui] styles the interface, and [syntax] colors code. The [syntax] table takes these roles, most of them named as in Zed themes: comment, comment.doc, keyword, keyword.storage, keyword.exception, preproc, operator, string, string.special, string.regex, string.escape, constant, constant.character, number, boolean, function, function.macro, constructor, type, type.builtin, variant, namespace, variable, variable.special, variable.parameter, property, label, punctuation, punctuation.special, tag, attribute, diff.plus, diff.minus, diff.delta, title, emphasis, emphasis.strong, text.literal, link_uri, punctuation.list_marker, strikethrough, quote. A role that a theme leaves out takes the style of its dotted parent, so type.builtin falls back to type. string.special colors the quotes of single-quoted and raw strings, which is not its meaning in Zed. Hob ignores any other key and names the ignored keys in its log.

Older theme files set syntax keys at the top level, with Helix names. Hob ignores those keys, so such a theme loses its syntax colors. Move the keys into [syntax] and rename them to the roles above. scripts/migrate_theme.py in the Hob repository does this.

Diff signs use diff_old_sign and diff_new_sign, which default to diff_old and diff_new. These styles are applied after code_block, so their properties take precedence. Diff gutters use diff_old_line_nr and diff_new_line_nr, which default to diff_line_nr.

The chat input shows the terminal’s own cursor by default. With ui.terminal_cursor = false, Hob paints the input caret instead, with cursor when the terminal has focus and cursor_unfocused when focus is lost. cursor_unfocused defaults to cursor, so themes only need it when the two should differ. Terminals that do not report focus events keep the focused caret.

Themes use 24-bit colors by default, but not every terminal can show them. Hob checks the environment, terminfo, and the terminal itself, and when truecolor is missing it quietly falls back to the closest of the 256 classic terminal colors. If detection gets it wrong, set HOB_TRUECOLOR=1 to force truecolor or HOB_TRUECOLOR=0 to force the fallback.

Theme files can also name terminal colors instead of giving hex values, using the same names as Helix: default, black, red, green, yellow, blue, magenta, cyan, gray, light-red, light-green, light-yellow, light-blue, light-magenta, light-cyan, light-gray, and white. Write them exactly as listed. lightgray, light_gray and LIGHT-GRAY are all rejected. default means the terminal default. Hob also takes a number from 0 to 255 to pick a palette entry by index, which Helix does not.

These work everywhere a hex value does, including the [syntax] roles, so a theme can be written entirely against the palette your terminal already defines. Hob passes them through as palette references rather than resolving them to RGB, so the colors stay correct in terminals that mangle truecolor, such as nested tmux over ssh.

ui.tool_output_lines

Lines of output a tool call shows before it collapses. Click the call to see all of it.

With 0 you see only the header. The read, index and list tools default to 0, because their header already says how many lines or entries came back. Errors and MCP tools still show their first line.

Field Default Tools
bash 3 bash
code_execution 3 code_execution
task 3 task
index 0 index
grep 3 glob, grep
read 0 list, read
write 5 edit, edit_lines, insert_lines, memory, multiedit, write
web 3 webfetch, websearch
other 3 Every other tool, MCP tools included

ui.modals

Each modal has its own nested table with a width setting. Width is an integer percentage of terminal width, from 1 to 100; omitted widths default to 90. A modal’s minimum readable or content width may make it wider than the requested percentage. The result is always clamped to the screen. This includes native dialogs, built-in Lua modal windows, and LazyGit. sessions controls /resume, tasks controls /tasks, and skills controls the skill browser. Use /reload to apply changes during a session.

Field Type Default Min Max
rewind.width integer 90 1 100
model.width integer 90 1 100
theme.width integer 90 1 100
mcp.width integer 90 1 100
account.width integer 90 1 100
login.width integer 90 1 100
files.width integer 90 1 100
search.width integer 90 1 100
help.width integer 90 1 100
btw.width integer 90 1 100
alert.width integer 90 1 100
timing.width integer 90 1 100
usage.width integer 90 1 100
sessions.width integer 90 1 100
tasks.width integer 90 1 100
skills.width integer 90 1 100
thinking.width integer 90 1 100
prompts.width integer 90 1 100
cost.width integer 90 1 100
memory.width integer 90 1 100
lazygit.width integer 90 1 100

agent

Field Type Default Min Description
max_output_bytes usize 51200 1024 Max bytes of tool output the model sees
max_output_lines usize 2000 10 Max lines of tool output the model sees
max_continuation_turns u32 3 1 Max automatic continuation turns
autoreview bool false - Start each session with autoreview on, at autoreview_level: in the TUI each new, loaded or resumed one, as /autoreview on does, and the session of hob -p, SDK mode and each ACP session. hob --autoreview does the same for one launch. Autoreview needs file_history: without it autoreview stays off and hob says why
autoreview_background_wait_secs u64 60 - How long a turn stays open for agent work in the background before autoreview (seconds), counted from the end of the turn and including requests that answer its results, which it never interrupts; ready results are consumed first, other background work never holds the turn, and at the deadline the review is deferred until the agent work ends; zero defers at once
autoreview_checks string[] [] - Shell commands autoreview runs in the session folder, in order, before the first review and after each repair turn, such as { "just check", "just lint" }. The first one that fails starts a repair turn with its exit status and the end of its output, and no review runs until all pass. A trusted project’s .hob/init.lua replaces this list. Empty runs no check
autoreview_check_timeout_secs u64 600 1 Time limit for one autoreview check (seconds). A check that runs longer is stopped and counts as failed
autoreview_level “base” | “full” base - Review level of a new session. base reviews correctness and completeness against the requests, and blocker and major defects block a clean review. full also reviews refactoring and improvement of the changes, and a major improvement blocks too
autoreview_max_rounds u32 10 1 Reviewer runs in one autoreview cycle. The report of the last one is final: no repair turn follows it, and a blocking finding it holds stays open
autoreview_max_cost number none - Cost limit of one autoreview cycle, in US dollars of billed cost: the reviewer and the repair turns, as the status bar counts it. When a report arrives and the cycle spent this much or more, that report is final and no repair turn follows. A model with no price, or one a subscription covers, bills nothing and never reaches it. Unset has no limit
autoreview_model String none - Model of the autoreview reviewer, a qualified spec such as anthropic/claude-sonnet-4-6. It must be allowed by provider.allowed_models and provider.excluded_models, and runs on the account the session uses for that provider, or else on its default account. A cycle whose reviewer model cannot be resolved pauses with a notice instead of reviewing with another model. Unset: the model of the run
autoreview_effort “minimal” | “low” | “medium” | “high” | “xhigh” | “max” none - Thinking effort of the autoreview reviewer. It replaces the thinking setting of the run as it is, also xhigh and max on a SOL model, and the model takes it as it takes a /thinking level: a model without thinking runs without, and one with fewer levels sends the closest one it accepts. Unset: the thinking setting of the run, with xhigh and max lowered to high on SOL models
max_turn_output u32 32768 1024 Output tokens one turn asks for, raised where an effort level needs the room and capped by the model’s own limit
compaction_buffer u32 | string 20% - Context reserved for compaction: token count or percent of the context window (e.g. “20%”)
compaction_instructions String none - Extra instructions appended to the compaction summary prompt
post_compaction_instructions String none - Extra instructions the agent receives after any compaction (e.g. re-read plan.md)
stale_read_check bool true - Require re-reading a file that changed on disk before editing it
file_history bool true - Keep what each tool call changed in files, so a rewind can put the files back and autoreview can review them. Changes made by bash are tracked only in the Git checkout hob works in, until the command moves to the background, and only where hob can tell they are its own: a change it cannot tell, such as a file Git ignored or a file whose line ends Git converts, is left out. Autoreview reviews what bash changed; a rewind puts it back only with rewind_shell_changes
rewind_shell_changes bool false - Let a code rewind also put back what bash commands changed. hob infers those changes from Git, comparing the checkout before and after each command, and the inference can be wrong in rare Git states (for example a file Git ignored or hid that a command brought into view); a rewind can then overwrite or delete a file. Even on, a rewind does not put back what a command that moved to the background changed, nor a change of a file that git status showed as unchanged before the command while Git normalizes its line ends on check-in (text, text=auto, eol=lf, core.autocrlf=input): what such a file held is not certain. Off: autoreview still reviews those changes, and a rewind leaves the files bash changed alone. Needs file_history
rtk bool true - Rewrite the model’s bash commands with rtk when it is installed
prevent_sleep bool true - Keep the Mac out of idle sleep while a session works on its own: a turn runs, queued input waits, or background work goes on. A session that waits on you, for a permission, an answer or a sign-in, or that is paused, lets the Mac sleep. The display still sleeps, and closing the lid still puts the Mac to sleep. macOS only, in the TUI and hob -p, not yet in SDK mode (--input-format stream-json) or ACP
shell string auto - Shell for string commands on Windows (jobstart, UI !): auto (Git Bash if installed, else cmd.exe), cmd, or a path to an executable

provider

Field Type Default Min Description
default_model String none - Default model identifier (e.g. anthropic/claude-sonnet-4-6)
allowed_models string[] [] - Glob patterns for permitted qualified model specs; empty permits all models
excluded_models string[] [] - Glob patterns for excluded qualified model specs; exclusions take precedence
connect_timeout_secs u64 10 1 HTTP connect timeout (seconds)
low_speed_timeout_secs u64 120 1 Low speed timeout (seconds with less than 1 byte received)
stream_timeout_secs u64 300 10 Streaming response timeout (seconds)
retry_base_ms u64 2000 1 Base delay between retries (milliseconds, grows per attempt)
retry_max_ms u64 60000 1 Cap on the guessed retry backoff (milliseconds)
max_retries u32 5 - Max retries on a rate limit the server sent no Retry-After for, 0 to never retry them
max_timeout_retries u32 10 - Max retries on stream timeouts

storage

Field Type Default Min Description
max_log_bytes_mb u64 200 1 Max total log size (MB)
max_log_files u32 10 1 Max number of log files to keep
input_history_size usize 100 10 Maximum number of prompts to recall in the current session
session_scope String cwd - Which saved sessions -c, /resume and hob.session.list use: “cwd” (started in this directory), “repo” (started anywhere in this git repository, linked worktrees included, and the same as “cwd” outside one), or “all”

net

Field Type Default Description
allowed_private_hosts string[] [] Hosts allowed to resolve to a private or loopback address, as host, host:port, or a CIDR range. Plain http:// is kept for them instead of being upgraded to https://

hob.net refuses private, loopback and metadata addresses, because the model picks the URLs. List a host here to let it through:

lua
hob.setup({
    net = {
        allowed_private_hosts = { "localhost:8080", "nas.lan", "10.0.0.0/8" },
    },
})

An entry with no port covers every port. A name you list is allowed whatever it resolves to. A name you did not list stays blocked when DNS lands it on a private address, unless that address falls in a range you allowed, so keep ranges as small as the service needs. Every redirect hop is checked against the same list. Permissions covers what the guard protects.

trust

Answers the folder trust question in advance. Read from the global ~/.config/hob/init.lua only, since a project file that could set it would be trusting itself:

lua
hob.setup({
    trust = {
        paths = { "~/src/me/*", "/workspace" },
        prompt = false,
    },
})

paths is a list of globs matched against the project root, empty by default. prompt is a bool, true by default. Setting it to false drops the startup card and leaves the folder restricted unless a paths entry matches. Folder Trust covers glob syntax and which run modes apply the policy.

instructions

Which instruction files Hob loads from each project directory. Read from the global ~/.config/hob/init.lua only, since a project file that could pick its own instructions would be trusting itself.

files replaces the built-in list (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, and friends) with your own, in priority order. An empty list loads no project instruction files at all, and AGENTS.local.md still loads:

lua
hob.setup({
    instructions = { files = { "CLAUDE.md" } },
})

overrides narrows it per checkout, for when one repository wants a different answer. Each entry matches a checkout by path (a glob against the project root, ~ included, like trust.paths) or by remote (a glob against every git remote URL of the project, normalized to host/path: https://host/a/b.git and git@host:a/b.git both become host/a/b). When both are set, both must match; an entry with neither matches every project. The first matching entry wins, and one that sets no files still ends the search, keeping the global files:

lua
hob.setup({
    instructions = {
        overrides = {
            { remote = "github.com/example/*", files = {} },
            { path = "~/src/secret", files = { "CLAUDE.md" } },
        },
    },
})

telemetry

Field Type Default Env Description
enabled bool false HOB_ENABLE_TELEMETRY Master switch
metrics_exporter string none OTEL_METRICS_EXPORTER Where metrics go: otlp, console, none, or a comma-separated mix
logs_exporter string none OTEL_LOGS_EXPORTER Where events go: otlp, console, none, or a comma-separated mix
protocol string http/json OTEL_EXPORTER_OTLP_PROTOCOL OTLP protocol: grpc, http/protobuf, or http/json
endpoint string http://localhost:4318 OTEL_EXPORTER_OTLP_ENDPOINT Collector endpoint. HTTP appends /v1/metrics and /v1/logs. The gRPC default is http://localhost:4317
headers table {} OTEL_EXPORTER_OTLP_HEADERS Headers sent with every export
timeout_ms integer 10000 OTEL_EXPORTER_OTLP_TIMEOUT Deadline for one export, retries included (ms)
compression string none OTEL_EXPORTER_OTLP_COMPRESSION Payload compression: gzip or none
metrics_protocol string - OTEL_EXPORTER_OTLP_METRICS_PROTOCOL Metrics-only protocol override
metrics_endpoint string - OTEL_EXPORTER_OTLP_METRICS_ENDPOINT Metrics-only endpoint, used verbatim with no path appended
metrics_headers table {} OTEL_EXPORTER_OTLP_METRICS_HEADERS Metrics-only headers, merged over headers
metrics_timeout_ms integer - OTEL_EXPORTER_OTLP_METRICS_TIMEOUT Metrics-only export deadline (ms)
logs_protocol string - OTEL_EXPORTER_OTLP_LOGS_PROTOCOL Logs-only protocol override
logs_endpoint string - OTEL_EXPORTER_OTLP_LOGS_ENDPOINT Logs-only endpoint, used verbatim with no path appended
logs_headers table {} OTEL_EXPORTER_OTLP_LOGS_HEADERS Logs-only headers, merged over headers
logs_timeout_ms integer - OTEL_EXPORTER_OTLP_LOGS_TIMEOUT Logs-only export deadline (ms)
metrics_interval_ms integer 60000 OTEL_METRIC_EXPORT_INTERVAL How often metrics are exported (ms)
logs_interval_ms integer 1000 OTEL_LOGS_EXPORT_INTERVAL, OTEL_BLRP_SCHEDULE_DELAY How often queued events are flushed (ms)
logs_max_queue_size integer 2048 OTEL_BLRP_MAX_QUEUE_SIZE Event queue capacity, at most 65536. Events are dropped when it is full
logs_max_export_batch_size integer 512 OTEL_BLRP_MAX_EXPORT_BATCH_SIZE Maximum events per export request
metrics_temporality string delta OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE Metric temporality: cumulative, delta or lowmemory
service_name string hob OTEL_SERVICE_NAME service.name on the exported resource
resource_attributes table {} OTEL_RESOURCE_ATTRIBUTES Extra resource attributes, your place for team or environment labels
metrics_include_session_id bool true OTEL_METRICS_INCLUDE_SESSION_ID Attach session.id to metrics. Turn off to keep metric cardinality low
metrics_include_version bool false OTEL_METRICS_INCLUDE_VERSION Attach app.version to metrics
log_user_prompts bool false OTEL_LOG_USER_PROMPTS Include prompt text in hob.user_prompt events. Off by default
log_tool_details bool false OTEL_LOG_TOOL_DETAILS Include tool input in hob.tool_result events. Off by default
content_max_length integer 10240 HOB_OTEL_CONTENT_MAX_LENGTH Character cap on any logged prompt or tool input

The Env column names the matching environment variable. For enabled, the exporters, metrics_include_*, log_user_prompts, log_tool_details and content_max_length, the variable wins. Every other field is passed to the OpenTelemetry SDK and wins over its variable. See Telemetry for the full picture.

Plugins

The plugins table turns plugins on or off and passes options to them. All bundled plugins are on by default. Set enabled = false to turn one off.

A plugin that is off never loads, so its tool name is free for one of your own plugins to take. Permission rules are keyed by the tool name alone, and names such as bash, write, and task already have rules in hob. A plugin that takes one of them inherits those rules, together with any “always allow” you saved. Hob warns you at load when this happens.

Each plugin checks its own options at startup. A typo, a wrong type, or an unknown plugin name gives you a clear error right away.

The edit plugin’s extra tools are options too: plugins.edit = { multiedit = false, insert_lines = true }. The old tools table is gone. If your config still uses it, Hob stops at startup and shows you the new form.

The names are bundled plugins and installed packages. A module you require from ~/.config/hob/lua/ takes no options here, see Plugins.

lua
hob.setup({
    plugins = {
        bash = { timeout_secs = 180 },
        websearch = { enabled = false },
    },
})

plugins.autotitle

Field Type Default Min Description
active boolean false - Automatically generate session titles.
api_key_env string "" - Environment variable holding the endpoint bearer token.
endpoint string "" - Full OpenAI-compatible chat completions URL.
model string "" - Provider/model spec, or server model ID when endpoint is set.
reasoning_effort string "" - Endpoint-only reasoning effort: none, minimal, low, medium, high, xhigh; empty omits the parameter.
timeout integer 90 1 Inference timeout in seconds, at most 120.

plugins.bash

Field Type Default Min Description
background_log_bytes integer 33554432 1024 Size at which the output log of a command rotates to .log.1. A command gets a log once its output outgrows the reply or it moves to the background. Values above 1 GiB count as 1 GiB.
background_on_timeout boolean false - Move a command that hits its timeout to the background instead of killing it. Applies to the main agent while background tasks are on; elsewhere the command is killed.
max_output_bytes integer - - Override agent.max_output_bytes for this tool.
max_output_lines integer - - Override agent.max_output_lines for this tool.
timeout_secs integer 120 5 Kill the command after this many seconds. A call’s timeout param overrides it.

plugins.code_execution

Field Type Default Min Description
max_memory_mb integer 50 10 Memory limit for the Python sandbox (MB).
max_output_bytes integer - - Override agent.max_output_bytes for this tool.
max_output_lines integer - - Override agent.max_output_lines for this tool.
timeout_secs integer 30 5 Script execution time budget in seconds; waiting on tool calls does not count. A call’s timeout param overrides it.

plugins.completion

Field Type Default Min Description
max_items integer 10 1 Rows the completion popup shows at once.

plugins.edit

Field Type Default Min Description
edit_lines boolean true - Provide the edit_lines tool.
insert_lines boolean false - Provide the opt-in insert_lines tool.
multiedit boolean true - Provide the multiedit tool.

plugins.glob

Field Type Default Min Description
max_output_bytes integer - - Override agent.max_output_bytes for this tool.
max_output_lines integer - - Override agent.max_output_lines for this tool.
search_result_limit integer 100 10 Max files the model sees per search.

plugins.grep

Field Type Default Min Description
max_line_bytes integer 500 80 Truncate lines the model sees at this many bytes.
max_output_bytes integer - - Override agent.max_output_bytes for this tool.
max_output_lines integer - - Override agent.max_output_lines for this tool.
search_result_limit integer 100 10 Max match groups per search. A call’s limit param overrides it.

plugins.index

Field Type Default Min Description
max_file_size_mb integer 2 1 Refuse to index files larger than this many MB.

plugins.infobar

Field Type Default Min Description
finish_time_format string "auto" - The os.date format of the last finish time, such as “%b %d %H:%M”. With auto, minimal shows the date only for an earlier day and classic always shows it.
hide_status_bar boolean false - Hide Hob’s status bar while the infobar is shown.
show_worktree boolean false - Show the linked worktree on the git row.
style string "minimal" - The look of the bar: minimal, or classic for the colored pills of pi-infobar.

plugins.read

Field Type Default Min Description
max_line_bytes integer 500 80 Truncate lines the model sees at this many bytes.
max_output_lines integer - - Override agent.max_output_lines for this tool.

plugins.sessions

Field Type Default Min Description
details boolean true - Show the selected session’s details under the /resume list: folder, id, creation date, turn time, disk size, model, tokens, context, cost, subagents and autoreview cycles.

plugins.skill

Field Type Default Min Description
plugin_dev boolean true - Offer the builtin hob-plugin-dev skill for writing hob plugins.

plugins.task

Field Type Default Min Description
allow_background boolean true - Expose a background input that pushes subagent results to the chat when they finish.
allow_model boolean false - Expose a model input that overrides the subagent model. Only enable if you trust callers to pick an exact model themselves.
max_concurrent integer 8 1 Max concurrently running subagents.

plugins.webfetch

Field Type Default Min Description
max_output_bytes integer - - Override agent.max_output_bytes for this tool.
max_output_lines integer - - Override agent.max_output_lines for this tool.
max_response_bytes integer 5242880 1024 Stop reading a response after this many bytes.

plugins.websearch

Field Type Default Min Description
max_output_bytes integer - - Override agent.max_output_bytes for this tool.
max_output_lines integer - - Override agent.max_output_lines for this tool.
max_response_bytes integer 5242880 1024 Stop reading a response after this many bytes.
provider string "exa" - Search backend: “exa” (default), “youcom” (You.com MCP), “kagi” (Kagi MCP, needs KAGI_API_KEY), or “searxng” (self-hosted).
searxng_base_url string "" - SearXNG instance URL; falls back to the SEARXNG_BASE_URL env var. A LAN instance also needs its host in net.allowed_private_hosts. Only this backend accepts websearch’s time_range (day, week, month, or year); its num_results is capped by the instance page size.

Validation

If a value is below its minimum, Hob shows a ConfigError with the field name, value, and minimum.

Directory layout

Hob follows platform directory conventions. On Linux and macOS that is XDG. On Windows, config, data, state, and logs all live under Roaming AppData (Windows has no separate state dir in this layout).

Purpose Linux / macOS Windows
Config ~/.config/hob/ %APPDATA%\hob\
Data ~/.local/share/hob/ %APPDATA%\hob\
State ~/.local/state/hob/ %APPDATA%\hob\
Logs ~/.local/logs/hob/ %APPDATA%\hob\
Cache ~/.cache/hob/ %LOCALAPPDATA%\hob\

Config holds init.lua, permissions.toml, mcp.toml, providers.toml, and commands/. State holds sessions, auth tokens, memories, plans, folder trust, and model-tier overrides. The install script puts the binary under %LOCALAPPDATA%\hob on Windows; that is separate from these runtime dirs.

~/.hob/ (or %USERPROFILE%\.hob\) is the layout older versions used. Hob does not read it anymore.

Moving from ~/.hob/

Hob moves ~/.hob/ into the locations above on the first start that finds it, before it reads or writes anything else, and shows where the files went. Files hob writes go to state. Your own files (init.lua, lua/, permissions.toml, mcp.toml, providers.toml, .env, AGENTS.md, pack-lock.json, commands/, skills/, themes/ and providers/) go to config. Logs go to logs. Caches are rebuilt.

When both places hold the same file, folder trust and recent models are merged. For any other file hob keeps the copy written last and moves the other one to ~/.hob.bak/. The exception is permissions.toml: older versions applied the one in ~/.config/hob/, so that one stays.

Hob does not move a ~/.hob/ that is a symlink, because it most likely points into a dotfiles repository. Run the move yourself, or retry one that failed, with:

hob migrate xdg

Personal Instructions

On top of the project instruction files Hob loads from the git root down to the cwd (AGENTS.md, CLAUDE.md, and friends; see Context), you can add:

  • AGENTS.local.md in any of those project directories for per-directory preferences (gitignored)
  • ~/.config/hob/AGENTS.md for preferences that apply to all projects
  • instructions.files in the global init.lua to replace the project file list, scoped per checkout with instructions.overrides (see instructions)

All of these are added to the system prompt at the start of every session.

Memory

The memory tool and /memory command store small Markdown notes under the state directory, scoped per project:

…/state/hob/projects/<project-id>/memories/

(Linux/macOS: ~/.local/state/hob/…; Windows: %APPDATA%\hob\…). Use them for non-obvious gotchas and decisions that should survive across sessions. They are separate from skills and from AGENTS.md.

Related pages: Skills, CLI, Providers.

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"