Settings files

Lime config is merged from five scopes, lowest to highest precedence:

#	Scope	Files	Committed?
1	Policy	Path from LIME_MANAGED_SETTINGS (enterprise / policy layer)	n/a
2	User	~/.lime/settings.json, ~/.lime/config.toml	No
3	Project	.lime.json, .lime/settings.json, .lime/config.toml, .mcp.json (MCP servers only)	Usually yes
4	Local	.lime/settings.local.json, .lime/settings.local.toml	No
5	CLI flags	--settings FILE_OR_JSON, --permission-mode, --dangerously-skip-permissions	n/a

Within a single scope, TOML follows JSON (TOML wins on conflict). Later sources deep-merge and override earlier ones.

Tip

Mental model: shared repo defaults → .lime.json. Machine-local overrides → .lime/settings.local.json. For most repos, those two files plus maybe ~/.lime/settings.json are all you ever touch.

Restricting the merge

lime --setting-sources user,local       # ignore project + policy
lime --settings ./test-overlay.json     # bolt one extra layer on top

--settings accepts either a path to a JSON/TOML file, or inline JSON. --setting-sources is a CSV of policy, user, project, local, flag.

Top-level keys

{
  "model": "gpt-5.4",
  "models": {
    "default": { "slug": "gpt-5.4" },
    "high":    { "slug": "claude-opus-4-7", "reasoningEffort": "high" },
    "low":     { "slug": "gpt-5.4-nano",    "verbosity": "low" }
  },

  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["read_file", "glob_search", "grep_search"],
    "ask":   ["write_file", "edit_file"],
    "deny":  ["bash"],
    "additionalDirectories": ["/var/log/myapp"]
  },

  "reasoningEffort": "medium",
  "verbosity": "medium",

  "hooks": {
    "PreToolUse":  ["./scripts/before_tool.sh"],
    "PostToolUse": ["./scripts/log_tool.sh"]
  },

  "mcpServers": {
    "sqlite": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data.db"]
    }
  },

  "plugins": {
    "externalDirectories": ["/path/to/plugins"],
    "marketplaceUrl": "https://marketplace.lime.dev"
  },
  "enabledPlugins": { "my-plugin": true },

  "sandbox": {
    "enabled": true,
    "namespaceRestrictions": true,
    "networkIsolation": true,
    "filesystemMode": "workspace-only",
    "allowedMounts": ["/tmp"]
  }
}

Key	Type	Notes
model	string	Shorthand for models.default.slug.
models	object	Per-tier (default, high, low) overrides — slug, autoCompactThreshold, reasoningEffort, verbosity.
permissions	object	See Permission model. defaultMode is User+Local-only.
reasoningEffort	string	One of none, low, medium, high, xhigh. Applies when the model supports it.
verbosity	string	One of low, medium, high.
hooks	object	See Hooks. Twelve event names.
mcpServers	object	See MCP transports & config. Trusted-pin: User+Local-only.
plugins	object	externalDirectories, installRoot, registryPath, bundledRoot, marketplaceUrl, extraMarketplaceUrls, marketplaceAutoUpdates.
enabledPlugins	object	Map of pluginId → bool. Legacy alternative to plugins.enabled.
sandbox	object	See Sandboxing.

Trusted-settings pin

permissions.defaultMode and mcpServers resolve from User + Local (and Policy) only — Project values are ignored for trust resolution and a diagnostic warning is logged. This prevents a checked-in repo file from silently lowering trust on a teammate’s machine. The rest of the config (permissions.allow/deny/ask, hooks, plugins, sandbox) merges normally.

TOML form

Both JSON and TOML are accepted. Starting fresh, JSON is the simpler choice. The TOML form is useful when you want comments without //:

.lime/config.toml

model = "claude-opus-4-7"

[permissions]
defaultMode = "acceptEdits"
allow = ["read_file", "glob_search"]
ask   = ["write_file"]
deny  = ["bash"]

Inspecting the resolved config

/config              Pretty-print all resolved sections.
/config env          Provider credentials & Lime knobs (redacted).
/config hooks        Hooks resolved for the current session.
/config model        Model catalog with built-in vs user tags.
/config plugins      Plugin discovery and enable state.