Settings

HooCode uses JSON settings files with project settings overriding global settings.

Edit directly or use /settings for common options.

All Settings

Model & Thinking

thinkingDisplay

"omitted" keeps full reasoning effort but skips streaming the thinking summary, lowering time-to-first-token (faster tool use) at the cost of not showing thinking text. "summarized" returns visible thinking. When unset, Opus 4.8 defaults to "omitted"; other models default to "summarized".

{
  "thinkingDisplay": "summarized"
}

thinkingBudgets

{
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768
  }
}

UI & Display

Tips

An occasional one-line tip on the band above the prompt, shown when the session has been idle for a while or when a turn has been running long enough that you are watching a spinner. A tip never interrupts: it is only ever posted when the band is empty, so it cannot delay or replace a notification you caused. It never repeats until it has run out of things to say, and it remembers across sessions.

The tips themselves live in one file, src/modes/interactive/tips.ts. Know a trick that is not in there? Send a PR — it is one row in an array, and it is genuinely one of the easiest useful first contributions to the project.

Telemetry and update checks

enableInstallTelemetry is inert: HooCode sends no install or update telemetry anywhere, and the setting is kept only so an existing settings.json does not fail to parse. Update checks are separate and do still run – they read the published version straight from the npm registry (https://registry.npmjs.org/@kolisachint/hoocode-agent/latest) and send nothing but a User-Agent. Set HOOCODE_OFFLINE=1 or HOOCODE_SKIP_VERSION_CHECK=1 to turn that off too.

Set HOOCODE_SKIP_VERSION_CHECK=1 to disable the HooCode version update check. Use --offline or HOOCODE_OFFLINE=1 to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry.

Warnings

{
  "warnings": {
    "anthropicExtraUsage": false,
    "websearchApiKey": false
  }
}

Both warnings are shown once per session in the TUI and can also be toggled from /settings → Warnings.

Compaction

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

Context budget

Everything in the system prompt and in an active tool’s schema is re-sent on every request. These three settings decide how large that is, and /settings groups them under Context with the live per-turn cost printed under the list.

light is read at startup to pick the tool set and the system prompt, so toggling it in /settings applies on the next session. --light turns it on for a single run. Auto-compaction lives in the same category and is documented under Compaction.

/settings also prices each tool by what its schema costs per turn, on the switch itself, so it is clear which one is worth turning off. hoocode --print-token-surface prints the same measurement as text.

Branch Summary

Retry

When a provider requests a retry delay longer than retry.provider.maxRetryDelayMs (e.g., Google’s “quota will reset after 5h”), the request fails immediately with an informative error instead of waiting silently. Set to 0 to disable the cap.

{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  }
}

Message Delivery

Terminal & Images

Shell

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

npmCommand is used for all npm package-manager operations, including installs, uninstalls, and dependency installs inside git packages. Use argv-style entries exactly as the process should be launched. When npmCommand is configured, git package dependency installs use plain install to avoid npm-specific flags in wrappers or alternate package managers.

Normally the package manager’s global modules location is queried using root -g. As a special case, if the first element of npmCommand is "bun", the modules location will instead be queried with pm bin -g.

Sessions

{ "sessionDir": ".hoocode/sessions" }

When multiple sources specify a session directory, precedence is --session-dir, HOOCODE_CODING_AGENT_SESSION_DIR, then sessionDir in settings.json.

Learning from sessions

The window /learn mines when looking for repeated directives, fixes, and workflows.

All five are editable from /settings under Learning. /learn settings prints the same values as text, alongside the paths of both settings files and the session directory being read.

{ "learnMaxSessions": 50, "learnMaxAgeDays": 90, "learnMinRepeats": 3 }

Widen the window on a repo you touch rarely, so a habit spread over months still reaches the repeat threshold. Narrow it on one you work in daily, where the last few weeks are the only relevant history. learnMinRepeats is the signal/noise dial: raise it for fewer, better-evidenced proposals.

Both thresholds count distinct sessions, not occurrences: saying a thing twice in one sitting usually means it was ignored the first time, which is evidence about that afternoon rather than about how you work. learnMinRequestRepeats is higher than learnMinRepeats on purpose — a rule stated twice is a rule, but a job asked for twice may just be a job that came up twice. learnMaxProposals bounds what a single run can ask you to review; every proposal costs the model context.

Non-numeric or non-positive values fall back to the default rather than narrowing the window to nothing. As with all settings, a project .hoocode/settings.json overrides the global one, so a repo can carry its own window.

Plugins and artifacts

Where hoocode writes what it authors. Both are editable from /settings under Plugins, which writes the global settings file — the layout a machine targets is an environment-level choice, so it is set once rather than passed on every run.

{ "enablePluginTools": true, "platform": ["claude", "github"], "pluginInstallScope": "user" }

/settings writes the global file. If a project .hoocode/settings.json sets one of these keys it is merged over that on the next session, so the pane marks the row as overridden rather than letting the change look permanent.

enablePluginTools is off by default and is the one gate for the whole autonomous system — see Plugins. Toggling it in /settings attaches the tools on the next session, since they are wired up when the session is built; the reuse nudge re-reads the setting and follows immediately. The --enable-plugintools flag turns it on for a single run. Slash-command plugin management (/plugin) is unaffected either way.

platform governs the two things hoocode writes: authored plugins, and the /new-skill, /new-agent and /new-command scaffolds. Reading is unaffected — every vendor convention is read regardless of this setting.

It takes a list because emitting for two platforms at once is a supported shape; in /settings the three tokens are independent toggles for that reason. Unsetting it (all toggles off) is not the same as targeting nothing: the defaults come back, which are claude for an authored plugin and .hoocode/ for a scaffold. agents is a scaffold-only target — a plugin is a distribution unit and the native layout belongs to no marketplace — so plugin authoring filters it out rather than failing.

The --platform CLI flag sets the same targets for a single run and overrides this setting.

Model Cycling

{
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

Markdown

External tools

hoocode is self-sufficient without any of these. Five optional Rust binaries expand what it can do: two make an existing tool faster, three add a capability hoocode otherwise does not have. Each resolves from HOOCODE_<TOOL>_BINARY → hoocode’s bin directory → PATH → a published release download.

Because hoocode degrades quietly without them, they are easy to miss. /settings → External tools lists all five with live status and what each one adds; rows below that are inert without their binary are marked needs <binary> there.

Environment variables:

On Android/Termux the published Linux builds do not run; install with pkg install <name> instead.

Mapping a long page

webfetch(url, outline: true) returns the page’s headings instead of its body — each with the offset that reads its section and what that section costs:

  Installation — offset 0, ~143 tokens
  Configuration — offset 557, ~145 tokens
Read a section by fetching it at the offset shown.

A page maps for a few dozen tokens whatever its length, and the one section worth reading is then fetched at its own offset. Outline offsets are the same offsets paging uses, so a row feeds straight back into offset.

Needs a webtools binary that supports --outline (v0.5.0 or newer). An older one rejects the flag, and hoocode reports that the binary needs updating rather than passing the parser message through.

Finding a mention on a long page

An outline helps when the page has headings and one names what you are after. webfetch(url, grep: "pattern") covers the rest — where does this page mention a thing, on a document whose headings do not say, or that has none:

offset 512 in "Configuration" (+2 nearby) — …the rate limit defaults to sixty…
Read a match by fetching it at the offset shown.

Match offsets are the offsets offset reads, like outline offsets, so a hit is read by fetching at it. The pattern is a regular expression, case-insensitive unless it carries an uppercase letter. Occurrences close together collapse into one hit carrying a count, so a term repeated through a paragraph is one result rather than eight near-identical ones.

outline and grep are alternatives, not a pair: asking for both is rejected before a subprocess is spawned. Needs webtools v0.6.0 or newer.

Reading a long page

webfetch budgets its output in tokens (maxTokens, default 4000, hard cap 25000). When a page runs past that, the result says so — the budget it stopped at, and the ways past it — so a long document reads as a first page rather than a dead end. The TUI marks the same fetch ~4000 tokens (truncated at 4000).

When the webtools binary reports paging offsets, the note names the offset to continue at; pass it back as offset to read the next window. Windows tile the document exactly, so a long page costs one budget per window rather than one copy of the page per attempt. Against an older binary the note falls back to advising a larger maxTokens.

Prefer a more specific URL or #anchor over paging a whole document: extraction has already dropped nav and boilerplate, so the first few thousand tokens are usually the article itself.

Web search providers

websearch needs no configuration: it defaults to keyless DuckDuckGo Lite. That backend is scraped HTML, though — rate-limited hard, and it can fail outright — so when search reliability matters, point it at a backend with an actual API contract. With none configured, the TUI says so once per session (see warnings.websearchApiKey).

The webtools binary reads its own webtools key out of the user-level ~/.hoocode/settings.json, using its own (snake_case) key names. HooCode never writes this block; it only reads it to tell whether a keyed backend exists. Put it in the user-level file — a project .hoocode/settings.json is not read by the binary, and a file holding credentials is worth keeping out of a working tree.

{
  "webtools": {
    "search": {
      "provider": "brave",
      "fallback": "duckduckgo",
      "providers": {
        "brave": { "api_key": "..." },
        "tavily": { "api_key": "..." },
        "searxng": { "base_url": "https://searx.internal" }
      }
    }
  }
}

Environment variables win over the file, so a key can stay out of it entirely:

Every result records the backend that answered it, so a fallback to the scraped backend is never silent.

Resources

These settings define where to load extensions, skills, prompts, and themes from.

Paths in ~/.hoocode/settings.json resolve relative to ~/.hoocode. Paths in .hoocode/settings.json resolve relative to .hoocode. Absolute paths and ~ are supported.

Arrays support glob patterns and exclusions. Use !pattern to exclude. Use +path to force-include an exact path and -path to force-exclude an exact path.

packages

String form loads all resources from a package:

{
  "packages": ["hoocode-skills", "@org/my-extension"]
}

Object form filters which resources to load:

{
  "packages": [
    {
      "source": "hoocode-skills",
      "skills": ["brave-search", "transcribe"],
      "extensions": []
    }
  ]
}

See packages.md for package management details.

Example

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true,
    "websearchApiKey": true
  },
  "packages": ["hoocode-skills"]
}

Project Overrides

Project settings (.hoocode/settings.json) override global settings. Nested objects are merged:

// ~/.hoocode/settings.json (global)
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// .hoocode/settings.json (project)
{
  "compaction": { "reserveTokens": 8192 }
}

// Result
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 8192 }
}