Settings Reference

Overview

Loop’s behavior is controlled by ~/.loop/agent/settings.json. Project-level overrides live in .loop/settings.json (requires project trust). View current settings in the TUI:

/settings

Complete Schema

{
  "defaultProvider": "soket",
  "defaultModel": "qwen3-30b",
  "defaultThinkingLevel": "off",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "enabledModels": ["qwen3-*"],
  "skills": [],
  "disabledSkills": [],
  "extensions": [],
  "prompts": [],
  "themes": [],
  "enableSkillCommands": true,
  "quietStartup": false,
  "hideThinkingBlock": false,
  "doubleEscapeAction": "tree",
  "uiMode": "normal",
  "sandbox": {
    "mode": "off",
    "isolation": "full",
    "runtime": "runc"
  },
  "fileEditReview": "newSession",
  "diffEditor": "cursor",
  "toolPermissions": {
    "write": "ask",
    "edit": "ask",
    "bash": "ask",
    "read": "allow"
  },
  "defaultProjectTrust": "ask",
  "mcpServers": {},
  "disabledMcpServers": [],
  "responseHeaderTimeoutMs": 60000,
  "tracing": {
    "enabled": true,
    "backend": "langfuse"
  },
  "providers": []
}

Field Reference

Model & Provider

Field	Type	Default	Description
`defaultProvider`	string	unset	Provider id saved by `/model`. With `defaultModel`, this is the startup model
`defaultModel`	string	unset	Model id saved by `/model`. Loop does not invent one
`defaultThinkingLevel`	string	`"off"`	`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. `Shift+Tab` cycles `off`, `low`, `medium`, and `high`
`enabledModels`	string[]	`[]`	Glob patterns for models shown in the picker

Appearance

Field	Type	Default	Description
`theme`	string	`"dark"`	Active theme name
`uiMode`	string	`"normal"`	UI mode
`quietStartup`	boolean	`false`	Suppress startup messages
`hideThinkingBlock`	boolean	`false`	Hide thinking blocks in output
`doubleEscapeAction`	string	`"tree"`	`"tree"`, `"fork"`, or `"none"`

Compaction

Field	Type	Default	Description
`compaction.enabled`	boolean	`true`	Enable automatic context compaction
`compaction.reserveTokens`	number	`16384`	Tokens reserved for model response
`compaction.keepRecentTokens`	number	`20000`	Recent tokens to preserve during compaction

Sandbox

Field	Type	Default	Description
`sandbox.mode`	string	`"off"`	`"off"` or `"local"`
`sandbox.isolation`	string	`"full"`	`"full"` or `"partial"`
`sandbox.runtime`	string	`"runc"`	`"runc"`, `"crun"`, `"runsc"`, or `"krun"`

Permissions

Field	Type	Default	Description
`toolPermissions.read`	string	`"allow"`	`"allow"`, `"ask"`, or `"deny"`
`toolPermissions.write`	string	`"ask"`	`"allow"`, `"ask"`, or `"deny"`
`toolPermissions.edit`	string	`"ask"`	`"allow"`, `"ask"`, or `"deny"`
`toolPermissions.bash`	string	`"ask"`	`"allow"`, `"ask"`, or `"deny"`
`fileEditReview`	string	`"newSession"`	`"newSession"`, `"always"`, or `"never"`
`diffEditor`	string	—	`"cursor"` or `"code"` for diff review
`defaultProjectTrust`	string	`"ask"`	`"ask"`, `"always"`, or `"never"`

Extensibility

Field	Type	Default	Description
`skills`	string[]	`[]`	Extra skill directories, after the built-in user and project locations. See Skills
`disabledSkills`	string[]	`[]`	Skill names hidden from the model and from `/skill:`. A project file adds names to the global list
`prompts`	string[]	`[]`	Directories for prompt templates
`themes`	string[]	`[]`	Directories for custom themes
`extensions`	string[]	`[]`	Directories for Rhai extensions
`enableSkillCommands`	boolean	`true`	Accepted in settings. `/skill:` is available for every enabled skill

MCP

Field	Type	Default	Description
`mcpServers`	object	`{}`	MCP servers to connect at startup
`disabledMcpServers`	string[]	`[]`	Configured servers that stay disconnected. A project file adds names to the global list

Each MCP server entry:

{
  "command": "npx",
  "args": ["-y", "some-mcp-server"],
  "env": {},
  "url": null,
  "headers": {}
}

Use command/args for stdio servers or url/headers for remote HTTP servers.

Response headers

Field	Type	Default	Description
`responseHeaderTimeoutMs`	number	`60000`	Max wait for model HTTP response headers, in milliseconds. `0` waits indefinitely. Change it in the TUI with `/ttfb`

Tracing

Global only. A project cannot override this block. The telemetry feature must be compiled in for /tracing to export spans. See Tracing.

Field	Type	Default	Description
`tracing.enabled`	boolean	`true`	Off after `/tracing disable`
`tracing.backend`	string	`"langfuse"`	`"langfuse"` or `"otlp"`
`tracing.langfuseHost`	string		Host saved by `/tracing setup`
`tracing.langfusePublicKey`	string		Langfuse public key
`tracing.otlpEndpoint`	string		OTLP/HTTP collector URL

Secrets (Langfuse secret key, OTLP authorization header) stay in the credential store.

Custom providers

Global only. Filled by /login custom.

Field	Type	Description
`providers`	array	`{ id, name, baseUrl }` entries

Project-Level Settings

Create .loop/settings.json in your project root to override global settings per-project:

{
  "defaultModel": "gpt-4o",
  "sandbox": {
    "mode": "local",
    "isolation": "full"
  }
}

Project settings require the project to be trusted. See Project Trust.

Configuration Precedence

Settings are resolved in this order (later wins):

Built-in defaults
~/.loop/agent/settings.json (global)
.loop/settings.json (project, if trusted)
Command-line flags
Environment variables

​Overview

​Complete Schema

​Field Reference

​Model & Provider

​Appearance

​Compaction

​Sandbox

​Permissions

​Extensibility

​MCP

​Response headers

​Tracing

​Custom providers

​Project-Level Settings

​Configuration Precedence

Overview

Complete Schema

Field Reference

Model & Provider

Appearance

Compaction

Sandbox

Permissions

Extensibility

MCP

Response headers

Tracing

Custom providers

Project-Level Settings

Configuration Precedence