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.luain 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
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 onUse 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:
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:
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:
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:
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:
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.
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 xdgPersonal 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.mdin any of those project directories for per-directory preferences (gitignored)~/.config/hob/AGENTS.mdfor preferences that apply to all projectsinstructions.filesin the globalinit.luato replace the project file list, scoped per checkout withinstructions.overrides(seeinstructions)
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.