# Settings (https://docs.withhull.com/reference/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](/desktop/settings). ## Configuring with the agent [#configuring-with-the-agent] 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 files [#config-files] | Scope | Location | Applies to | | ------- | ------------------------------------------------------------------------------------ | ---------------------------------------- | | Global | `~/.config/hull/hull.jsonc` (Windows: `C:\Users\\.config\hull\hull.jsonc`) | Every project. | | Project | `hull.jsonc` in the project root, or `.hull/hull.jsonc` | That project. Overrides global settings. | 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 combined [#how-settings-are-combined] 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. Some settings can only be widened in global config. For example, project config can turn the sandbox on, but it can't turn it off or add writable paths. See [Sandboxing](/security/sandboxing). ## Change settings [#change-settings] Click the gear icon () in Hull Code to open **Settings**. Tabs include Providers, Models, Agent Behaviour, Auto-Approve, Browser, Checkpoints, Display, Autocomplete, Notifications, Context, Indexing, Sandboxing, Experimental, Language and About Hull Code. Changes are written to the same config files the CLI uses. Choose **Local Config** or **Global Config** in the Settings header to open the matching file. If there's more than one candidate, pick the file from the list. If the file doesn't exist yet, Hull creates it. ### Export and import [#export-and-import] In the **About Hull Code** tab: * **Export** saves your global config as `hull-settings.json`. Values are exported as they are, so check the file before you share it. * **Import** loads an exported file into the settings draft. Nothing changes until you choose **Save**; choose **Discard** to cancel. Open **Settings › Tools › Hull Code**. Sections include User Profile, Providers, Models, Agent Behavior, Auto-Approve, Context and Advanced. The plugin reads and writes the same config files as the CLI. Edit the JSONC files directly, or ask the agent to do it. Config files are plain text, so you can copy them between machines. To check what Hull has loaded: ```bash hull debug config # the resolved configuration hull debug paths # where Hull keeps config, data, cache and state ``` To move sessions between machines, use `hull export` and `hull import`. ## Common settings [#common-settings] ### Speech to text [#speech-to-text] 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: ```json { "experimental": { "speech_to_text_model": "openai/whisper-large-v3-turbo" } } ``` Speech to text is available only through the Hull Gateway. ### Prompt-training model visibility [#prompt-training-model-visibility] 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. ```json { "hide_prompt_training_models": true } ``` ### Reasoning blocks [#reasoning-blocks] Reasoning blocks stay expanded in the VS Code chat by default. Turn on **Auto-Collapse Reasoning** in the **Display** tab, or set: ```json { "auto_collapse_reasoning": true } ``` ### Terminal command blocks [#terminal-command-blocks] 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`. ```json { "terminal_command_display": "collapsed" } ``` ### Markdown diffs [#markdown-diffs] 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 compaction [#context-compaction] Hull compacts long conversations automatically when the context window fills up. You can change this under `compaction`: ```json { "compaction": { "auto": true, "threshold_percent": 80 } } ``` Run `/compact` to compact a session yourself. ## Sandbox [#sandbox] 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](/security/sandboxing) for setup, the exact boundaries and platform limits. ## Experimental features [#experimental-features] 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: ```json { "experimental": { "codebase_search": true, "batch_tool": false, "disable_paste_summary": false, "mcp_timeout": 30000 } } ``` The `$schema` in your config file lists every available option. ## Telemetry [#telemetry] 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: ```json { "experimental": { "openTelemetry": false } } ``` If `OTEL_EXPORTER_OTLP_ENDPOINT` is set, the CLI also exports OpenTelemetry traces and logs to that OTLP HTTP endpoint.