Reference13 min read

Settings Reference

Auto-approve keys, guardrails, and feature flags in one table

Every configurable setting in one place. Nexgile Code’s settings live in two layers: a small set of VS Code settings (searchable under nexgile-code in your editor’s Settings UI or settings.json) and the much larger in-app settings in the Nexgile Code panel (gear icon → sections: Providers, Modes, Skills, Slash Commands, Auto-Approve, MCP Servers, Checkpoints, Notifications, Context, Terminal, Prompts, Worktrees, UI, Agent Workflow, Experimental, About). The About section provides Export, Import, and Reset for the in-app configuration; nexgile-code.autoImportSettingsPath can auto-import an exported file at startup.

Each table lists the setting, its default, and what it controls. Follow the links for the full explanation of each area.

Two shortcuts before the tables. The settings panel has a search box that matches names and descriptions across every section — usually faster than remembering which tab a toggle lives on. And where a name below appears in code font, that is the key as it appears in an exported configuration file, which is what you search for when reading or editing one by hand.

VS Code settings (`nexgile-code.*`)

Setting	Type / Default	What it controls
`allowedCommands`	array — `["git log", "git diff", "git show"]`	Command prefixes that may run without asking when Execute auto-approve is on
`deniedCommands`	array — `[]`	Command prefixes refused automatically; longest prefix match beats an allow entry; `*` denies everything
`commandExecutionTimeout`	number — `0`	Seconds to wait for a command before timing out (0 = no timeout, max 600)
`commandTimeoutAllowlist`	array — `[]`	Command prefixes exempt from the execution timeout
`preventCompletionWithOpenTodos`	boolean — `false`	Blocks task completion while the todo list has unfinished items
`vsCodeLmModelSelector`	object	Vendor/family selector for the VS Code LM API provider
`customStoragePath`	string — `""`	Relocates task history and settings storage to a custom absolute path
`enableCodeActions`	boolean — `true`	Nexgile Code quick fixes in the editor lightbulb (Explain/Fix/Improve)
`autoImportSettingsPath`	string — `""`	Path to an exported configuration file imported automatically on startup
`maximumIndexedFilesForFileSearch`	number — `10000`	File cap for the `@` file-search index in context mentions
`useAgentRules`	boolean — `true`	Loads `AGENTS.md` / `AGENT.md` / `AGENTS.local.md` rules files
`apiRequestTimeout`	number — `600`	Seconds to wait for an AI-provider response (0 = none, max 3600); raise for slow local models
`newTaskRequireTodos`	boolean — `false`	Requires the `todos` parameter when the agent spawns subtasks
`codeIndex.embeddingBatchSize`	number — `60`	Batch size for embedding calls during codebase indexing
`debug`	boolean — `false`	Adds buttons for viewing the raw API conversation history and UI messages as prettified JSON in temporary files
`debugProxy.enabled`	boolean — `false`	Routes outbound network requests through a proxy for inspection. Only active when the extension itself is being run in a debug session
`debugProxy.serverUrl`	string — `http://127.0.0.1:8888`	Address of that proxy
`debugProxy.tlsInsecure`	boolean — `false`	Accepts self-signed certificates from the proxy — required to inspect TLS traffic, and unsafe outside local debugging

The last four are diagnostic aids rather than everyday settings. debug is the useful one when you need to see exactly what was sent to a model; the proxy trio only takes effect when the extension is launched under a debugger, so turning them on in a normal install does nothing.

Auto-approve (Settings → Auto-Approve)

All off by default — full detail in Auto-Approving Actions.

Setting	Default	What it controls
`autoApprovalEnabled`	off	Master switch; when off, every toggle below is ignored
`alwaysAllowReadOnly`	off	File reads, listings, and searches inside the workspace
`alwaysAllowReadOnlyOutsideWorkspace`	off	Extends read auto-approval outside the workspace
`alwaysAllowWrite`	off	File edits and creations inside the workspace
`alwaysAllowWriteOutsideWorkspace`	off	Extends write auto-approval outside the workspace
`alwaysAllowWriteProtected`	off	Allows auto-writes to protected files
`alwaysAllowExecute`	off	Terminal commands, still filtered by the allow/deny lists
`alwaysAllowMcp`	off	MCP tool calls (each tool must also be on the server’s `alwaysAllow` list)
`alwaysAllowModeSwitch`	off	Agent-requested mode changes
`alwaysAllowSubtasks`	off	Creating and finishing subtasks (Workflow Mode delegations bypass this)
`alwaysAllowFollowupQuestions`	off	Auto-answers follow-up questions with the first suggestion after a timeout
`followupAutoApproveTimeoutMs`	60 s	How long a follow-up question waits before the first suggestion is chosen (1–300 s)

Command guardrails & task limits

Explained in Command Guardrails & Limits.

Setting	Default	What it controls
`allowedCommands` / `deniedCommands`	see above	Prefix allow/deny lists (editable in Auto-Approve → Execute or VS Code settings)
`commandExecutionTimeout` / `commandTimeoutAllowlist`	0 / `[]`	Command timeout and its exemption list
`allowedMaxRequests`	unlimited	Max LLM calls per task; at the cap the task pauses with a “Reset and Continue” prompt
`allowedMaxCost`	unlimited	Max USD spend per task; same pause-and-confirm behavior
`requestDelaySeconds`	5 s base	Base delay for exponential backoff when a failed API request is retried

Context (Settings → Context)

Explained in Context Management.

Setting	Default	What it controls
`autoCondenseContext`	on	Automatically summarizes older conversation turns near the context limit
`autoCondenseContextPercent`	100%	Context-window fill level that triggers condensing (slider 10–100; lower it to condense earlier)
`customCondensingPrompt`	built-in	Replaces the default summarization prompt
`profileThresholds`	—	Per-API-profile condensing thresholds overriding the global percent
`maxOpenTabsContext`	20	How many open editor tabs are mentioned in context (0–500)
`maxWorkspaceFiles`	200	Workspace-file listing cap in context (0–500)
`includeDiagnosticMessages`	on	Includes Problems-panel diagnostics in tool results
`maxDiagnosticMessages`	50	Diagnostics cap per result (0 = unlimited)
`writeDelayMs`	1000 ms	Pause after auto-approved writes so diagnostics can catch new problems (0–5000)
`includeCurrentTime`	on	Puts the current time and timezone in the system prompt. Turn off if a model starts refusing work over how old it thinks the information is
`includeCurrentCost`	on	Puts the running task cost in the system prompt
`maxGitStatusFiles`	0	Git status entries included in the environment details. `0` disables the file list; above `0` the branch/commit header is always included too
Show ignored files	off	Lists `.nexgileignore`’d files with a lock symbol instead of hiding them from listings and searches entirely
`enableSubfolderRules`	off	Also loads `.nexgile/rules/` and `AGENTS.md` from subdirectories, not just the workspace root — see Rules Files
`maxImageFileSize`	5 MB	Largest single image `read_file` will process
`maxTotalImageSize`	20 MB	Cumulative image budget for one `read_file` call; images that would push past it are skipped
`diagnosticsEnabled`	on	Master switch for diagnostic collection

Environment details are the block of workspace state attached to each request: visible files, open tabs, actively running terminals, files modified since the agent last read them, the current mode, and the workspace file listing — plus, subject to the settings above, the current time, running cost, and git status. Trimming what goes in there is the cheapest way to cut per-request token cost on a large repository, and maxGitStatusFiles defaulting to 0 is why you won’t see a file-by-file git listing unless you ask for one.

Per-profile settings (Settings → Providers)

These belong to an API configuration profile, not to the app as a whole — so the same workspace can run a fast cheap profile and a careful expensive one with different values for each. Switch profiles from the chat header, or pin one to a mode.

Setting	Default	What it controls
`modelTemperature`	model’s own default	Sampling temperature. Leave unset unless you have a reason; the shipped default is whatever the model recommends
`consecutiveMistakeLimit`	3	How many consecutive tool failures the agent may hit before it stops and asks you for direction. `0` disables the guard
`rateLimitSeconds`	0	Minimum gap between API requests on this profile — the fix for provider rate limits
`todoListEnabled`	on	Whether `update_todo_list` is offered on this profile
`includeMaxTokens`	—	Sends an explicit max-tokens value with each request (OpenAI-compatible endpoints that need it)
`enableReasoningEffort` / `reasoningEffort`	off	Reasoning-effort level for models that expose one
`modelMaxTokens`	model’s own default	Output-token ceiling per response
`modelMaxThinkingTokens`	—	Thinking-token budget for extended-thinking models
`verbosity`	model’s own default	Response verbosity, where the model supports the control

consecutiveMistakeLimit is the one worth knowing by name. It is what stops a model that has misread a file from burning your budget retrying the same broken edit — three failures in a row and it hands the problem back to you.

Checkpoints (Settings → Checkpoints)

Explained in Checkpoints.

Setting	Default	What it controls
`enableCheckpoints`	on	Shadow-git snapshotting of every agent change
`checkpointTimeout`	15 s	Max time to wait for a checkpoint save (10–60 s)

Terminal (Settings → Terminal)

Explained in Terminal & Shell Integration.

Setting	Default	What it controls
`terminalOutputPreviewSize`	medium	Inline output preview cap — small 5 KB / medium 10 KB / large 20 KB; the rest spills to disk for `read_command_output`
`terminalShellIntegrationDisabled`	on	“Use Inline Terminal (recommended)” — runs commands through the built-in process runner; turn off to use VS Code shell integration
`terminalShellIntegrationTimeout`	5000 ms	How long to wait for shell integration to initialize
`terminalCommandDelay`	0 ms	Artificial delay after each command (workaround for some shells)
`terminalPowershellCounter`	off	PowerShell counter workaround for duplicate-command detection
`terminalZshClearEolMark`	on	Clears the zsh end-of-line mark that can garble output
`terminalZshOhMy` / `terminalZshP10k` / `terminalZdotdir`	off	Oh My Zsh, Powerlevel10k, and ZDOTDIR compatibility

Everything from terminalShellIntegrationTimeout down applies only when “Use Inline Terminal” is switched off — those settings tune the VS Code terminal, and some of them need an IDE restart to take effect. With the inline terminal on (the default), commands bypass your shell profile entirely, which is exactly why it’s the recommended setting: no prompt themes or plugins to garble the output the agent has to read.

Codebase indexing

Configured from the indexing popover (status badge in the chat area), not a settings tab. Explained in Codebase Indexing & Semantic Search.

Setting	Default	What it controls
`codebaseIndexEnabled`	off	Master switch for semantic indexing
`codebaseIndexQdrantUrl` (+ optional API key)	—	Address of your Qdrant vector store
Embedder provider / model / dimension	—	OpenAI, OpenAI-compatible, Ollama, Gemini, Mistral, Bedrock, OpenRouter, or Vercel AI Gateway
Search score threshold	0.4	Minimum similarity (0–1) for a result to be returned
Maximum search results	50	Result cap per query (10–200)
`nexgile-code.codeIndex.embeddingBatchSize`	60	Embedding batch size (VS Code setting)

Agent Workflow (Settings → Agent Workflow)

Feature toggles stored in the panel’s local storage; details in Settings & Feature Flags and Workflow Mode.

Setting	Default	What it controls
`workflowModeEnabled`	off	Routes new Code/Debug tasks through the Orchestrator → Code → Tester → Reviewer → Shipper chain
Task Board	off	Interactive task panel for user-defined and agent-derived tasks
Task Progress Bar	off	Phase indicator: Plan → Read → Edit → Verify → Done
Pipeline View	on	Multi-agent pipeline visualization
Code Review Gate	on	Post-task lint, type-check, and AI self-review of changed files
Test Runner	on	Post-task test detection and execution for changed files
Visual Preview	off	Open-in-browser button for UI verification (`previewUrl` default `http://localhost:3000`)
Task Templates	on	Prebuilt templates: Feature, Bug Fix, Refactor, Security Audit
Task Dashboard	on	Productivity metrics: task count, cost, tokens, daily activity

Experiments (Settings → Experimental)

All off by default; see Tool Reference for the tools they add.

Experiment	What it enables
`preventFocusDisruption`	Background editing without stealing editor focus
`imageGeneration`	The `generate_image` tool (via OpenRouter)
`runSlashCommand`	Lets the agent invoke slash commands itself
`customTools`	Loads user-defined tools from `.nexgile/tools/` and `~/.nexgile/tools/`

Notifications (Settings → Notifications)

Setting	Default	What it controls
`soundEnabled`	off	Sound effects on task events
`soundVolume`	0.5	Effect volume (0–1)
`ttsEnabled`	off	Text-to-speech reading of agent responses
`ttsSpeed`	1.0	Speech rate

Worth turning on if you run long auto-approved tasks — a sound is how you find out the agent is waiting for you without watching the panel.

Interface & behavior

Setting	Default	What it controls
`mcpEnabled`	on	Master switch for MCP. Off disconnects every server and removes the MCP tools from the prompt
`enterBehavior`	`send`	Whether Enter sends the message and Shift+Enter adds a newline, or the reverse
`disabledTools`	`[]`	Tools switched off globally — excluded from the prompt and refused at execution (Tool Reference)
`showWorktreesInHomeScreen`	on	Shows the Worktrees selector on the home screen
`language`	from your editor locale	The language the agent thinks and responds in — 18 options, falling back to English for unrecognized locales
`includeTaskHistoryInEnhance`	—	Feeds recent conversation into the prompt-enhancement feature so it can improve a prompt in context
`enhancementApiConfigId`	—	Runs prompt enhancement on a dedicated (usually cheaper) profile
`telemetrySetting`	—	Records a usage-telemetry preference. See the note below — nothing is transmitted in this build regardless of how it is set
`historyPreviewCollapsed` / `reasoningBlockCollapsed`	—	Whether the history preview and model reasoning blocks start collapsed

Also worth knowing

Search the settings. The settings panel has a search box — the fastest route to any row in this reference, since it matches setting names and descriptions across every section.
Per-mode model pinning: every mode can pin a named API configuration profile (Modes tab → “API Configuration”), so Architect can plan on a strong model while Code executes on a cheaper one. See Model Behavior & Costs.
Export / Import / Reset live in Settings → About. The export is a JSON file containing your global settings and every API configuration profile; task history and the record of which profile is currently selected are left out. nexgile-code.autoImportSettingsPath re-applies such a file at startup, which is how a team ships one agreed configuration to every machine. A few advanced keys — such as execaShellPath, which overrides the shell the inline terminal launches — have no control in the panel and can only be set this way.
Treat an exported settings file as a secret. API keys normally live in your editor’s encrypted secret storage, but export copies the profiles verbatim — keys included — into plain JSON. Strip the credentials before committing one to a shared repository, and have each person add their own key after importing.