Settings

Hull's agent runtime reads its configuration from JSONC files (JSON with comments). The CLI, the VS Code extension and the JetBrains plugin all read the same files, so a change made in one applies to the others. Hull Desktop has its own settings screen for app preferences; see Desktop settings.

Configuring with the agentCopy Anchor Link

The quickest way to change your configuration is to ask the agent. Hull has a built-in skill that knows the config format and can find, create and update your config files.

Things you can ask:

• "Switch my default model to Claude Sonnet."
• "Disable the OpenAI and Groq providers."
• "Set up an MCP server for Figma."
• "Auto-approve all read and glob operations."
• "Create a custom agent for code review."

The agent edits the global or project config file as appropriate and tells you what it changed.

Config filesCopy Anchor Link

Hull also reads hull.json in the same places. If you check a project config file into version control, keep API keys and other secrets out of it (for example provider.*.options.apiKey). Use environment variables instead.

Project config loads only when the project is trusted. The CLI asks the first time you open a project with project configuration, and you can change the decision with hull trust. In VS Code, Hull follows VS Code's workspace trust. To ignore project config completely, set HULL_DISABLE_PROJECT_CONFIG=1.

When Hull creates the global config file, it adds a $schema reference, so editors that understand JSON Schema (VS Code, JetBrains and others) give you autocompletion and validation.

How settings are combinedCopy Anchor Link

Hull merges configuration from several sources. Later sources override earlier ones:

1. Remote defaults: configuration provided by your organization through Hull.
2. Global: ~/.config/hull/hull.jsonc.
3. Custom file: a file named in the HULL_CONFIG environment variable.
4. Project: hull.jsonc in the project.
5. Project .hull directory: .hull/hull.jsonc.
6. Inline: JSON in the HULL_CONFIG_CONTENT environment variable.
7. Managed: configuration installed by an administrator, which always wins. It lives in /Library/Application Support/hull on macOS (or a managed preferences profile), /etc/hull on Linux and %ProgramData%\hull on Windows.

Managed configuration lets organizations enforce settings while developers keep their own preferences for everything else.

Change settingsCopy Anchor Link

Common settingsCopy Anchor Link

Speech to textCopy Anchor Link

When you're signed in to Hull, choose a transcription model in VS Code under Models › Speech to Text Model. It's stored in your global config:

{
  "experimental": {
    "speech_to_text_model": "openai/whisper-large-v3-turbo"
  }
}

Speech to text is available only through the Hull Gateway.

Prompt-training model visibilityCopy Anchor Link

Turn on Hide Prompt-Training Models under Models to hide Hull Gateway models whose providers may use your prompts for training. Models from other providers, and models without prompt-training information, stay visible. It's off by default.

{
  "hide_prompt_training_models": true
}

Reasoning blocksCopy Anchor Link

Reasoning blocks stay expanded in the VS Code chat by default. Turn on Auto-Collapse Reasoning in the Display tab, or set:

{
  "auto_collapse_reasoning": true
}

Terminal command blocksCopy Anchor Link

Terminal command blocks start expanded by default. Choose Collapsed for Terminal Command Blocks in the Display tab, or set terminal_command_display to "collapsed". Valid values are expanded and collapsed.

{
  "terminal_command_display": "collapsed"
}

Markdown diffsCopy Anchor Link

Hull's diff viewers can show Markdown files rendered instead of as raw text. Use the eye and code toggle in a Markdown file's header, or set the VS Code setting hull-code.new.diff.renderMarkdown to true to render Markdown by default.

Context compactionCopy Anchor Link

Hull compacts long conversations automatically when the context window fills up. You can change this under compaction:

{
  "compaction": {
    "auto": true,
    "threshold_percent": 80
  }
}

Run /compact to compact a session yourself.

SandboxCopy Anchor Link

On macOS and Linux, Hull can run agent tools in a sandbox that limits where they can write and blocks outbound network access. It's off by default. Turn it on in the Sandboxing settings tab (VS Code and Hull Desktop) or with the sandbox key in global config. Windows isn't supported.

See Sandboxing for setup, the exact boundaries and platform limits.

Experimental featuresCopy Anchor Link

In VS Code, the Experimental tab lists features that are still changing, including Share Mode, Formatter, LSP, Batch Tool, Codebase Search, Image Generation, Speech to Text, Native Notebook Tools, Shared Agent Board, Continue on Deny, SWE-Pruner, MCP Timeout and Remote Control.

In config files, these live under the experimental key:

{
  "experimental": {
    "codebase_search": true,
    "batch_tool": false,
    "disable_paste_summary": false,
    "mcp_timeout": 30000
  }
}

The $schema in your config file lists every available option.

TelemetryCopy Anchor Link

Telemetry is on by default. In VS Code, Hull Code follows VS Code's own telemetry.telemetryLevel setting; the Telemetry section of the About Hull Code tab opens it for you. For the CLI and the agent runtime, set:

{
  "experimental": {
    "openTelemetry": false
  }
}

If OTEL_EXPORTER_OTLP_ENDPOINT is set, the CLI also exports OpenTelemetry traces and logs to that OTLP HTTP endpoint.