Configuration

Hokan reads TOML configuration and applies defaults for omitted settings. Unknown fields are rejected, so validate after editing.

Bash
hokan config pathhokan config inithokan config showhokan config validate

config init creates a default file and refuses to overwrite an existing one.

File locations

Data	Default location	Root override
Configuration	~/.config/hokan/config.toml	XDG_CONFIG_HOME
Private credentials	~/.config/hokan/credentials.toml	XDG_CONFIG_HOME
Custom command specs	~/.config/hokan/specs/	XDG_CONFIG_HOME
History and diagnostics	~/.hokan/	HOKAN_STATE_DIR, then XDG_STATE_HOME
Cache	~/.cache/hokan/	XDG_CACHE_HOME

Credentials and history files must be owned by the current user and private (0600 or stricter); the state directory is 0700. See AI setup for the provider wizard and environment-variable credentials.

Shell and appearance

TOML
[core]login_shell = false[ui]max_rows = 8max_width = 76color = "auto"nerd_fonts = trueshow_hidden = false

• core.login_shell = true loads login-shell configuration, useful for themes initialized in .zprofile.
• max_rows is the total overlay height, including two border rows; range 3–50.
• max_width has range 40–240 columns.
• color accepts auto, always, or never. NO_COLOR=1 also selects a plain terminal for the AI wizard.
• Set nerd_fonts = false if icons appear as empty squares.

Keys

TOML
[keys]accept = "tab"activate = "enter"up = "up"down = "down"page_up = "page-up"page_down = "page-down"dismiss = "escape"history = "ctrl-r"toggle = "back-tab"

Use disabled to turn off a binding. Enabled bindings cannot conflict. See your first session for each action's behavior.

Completion and history

TOML
[completion]local_timeout_ms = 100max_candidates = 0 # Keep all matching candidatescd_enter_behavior = "execute"[history]enabled = truemax_command_bytes = 16384exclude = []

The incremental completion budget accepts 10–5000 milliseconds. Reaching it publishes the current batch while remaining sources continue. The candidate limit defaults to 0 (all matches); an explicit 10–10000 limit still caps the list. Existing configurations with max_candidates = 1000 retain that cap; set it to 0 to browse all matches. ui.max_rows controls the visible page height, and arrow and page keys wrap through the list. History's command size limit accepts 100–100000 bytes. History exclusions use regular expressions. Local command history can contain sensitive text, so treat it as private data.

cd_enter_behavior controls Enter on a selected directory candidate for cd:

• "execute" (default): fill the selected path and execute cd immediately.
• "continue": fill the path and suggest child directories without executing.

Tab always fills the path and continues completion. With no selection, Enter executes the input as typed.

Diagnostic logging

TOML
[logging]enabled = falsemax_bytes = 1048576rotations = 3

Logs are opt-in and bounded. When enabled, they are written to ~/.hokan/debug.log (the default state directory, relocatable with HOKAN_STATE_DIR or XDG_STATE_HOME). They contain typed event categories and timing data, not query text, history entries, full working directories, HTTP bodies, or environment variable values.

Automatic updates

TOML
[update]enabled = trueinterval_secs = 1800

Updates follow the installed binary’s channel. Legacy channel values are accepted but ignored; use hokan upgrade --channel stable or --channel beta for a one-time cross-channel upgrade to a higher version. Set enabled = false to disable automatic updates, or HOKAN_NO_AUTO_UPDATE=1 for one session. The updated binary takes effect on the next launch. See updates and maintenance.