Settings (settings.json)

CrabCode's JSON config file. Controls permissions, env vars, hooks, model, plugins, and more.

What it is

settings.json decides how CrabCode behaves for the current user / project. It loads in layers, later overrides earlier:

1. User: ~/.crabcode/settings.json
2. Project: <repo>/.crabcode/settings.json (committed, team-shared)
3. Local: <repo>/.crabcode/settings.local.json (gitignored, personal overrides)
4. Managed / policy: pushed by enterprise admins, highest precedence

On Windows the user-level path is %USERPROFILE%\.crabcode\settings.json. Set CRABCODE_CONFIG_DIR to override the user-level root (defaults to ~/.crabcode).

settings.json and CrabCode's runtime global state (~/.crabcode.json — holds things like theme, login info, counters) are two different files. This page only covers settings.json.

When you see this doc

• The "Learn more" link from /config
• A startup-time validation error pointing here
• A skill or plugin install prompts you to add config

Field overview

{
  "$schema": "https://json.schemastore.org/crabcode-settings.json",
  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(npm test:*)"],
    "deny": ["Bash(rm -rf:*)"],
    "ask":  ["WebFetch"],
    "additionalDirectories": ["~/code/sibling-repo"]
  },
  "env": {
    "DEBUG": "true",
    "ACOSMI_BASE_URL": "https://api-staging.acosmi.com"
  },
  "hooks": {
    "PreToolUse": [{ "matcher": "Bash", "hooks": [/* ... */] }]
  },
  "model": "deepseek-v4-flash",
  "smallModel": "qwen3.6-plus",
  "outputStyle": "default",
  "cleanupPeriodDays": 30
}

{
  "$schema": "https://json.schemastore.org/crabcode-settings.json",
  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(npm test:*)"],
    "deny": ["Bash(rm -rf:*)"],
    "ask":  ["WebFetch"],
    "additionalDirectories": ["~/code/sibling-repo"]
  },
  "env": {
    "DEBUG": "true",
    "ACOSMI_BASE_URL": "https://api-staging.acosmi.com"
  },
  "hooks": {
    "PreToolUse": [{ "matcher": "Bash", "hooks": [/* ... */] }]
  },
  "model": "deepseek-v4-flash",
  "smallModel": "qwen3.6-plus",
  "outputStyle": "default",
  "cleanupPeriodDays": 30
}

Field matrix

The tables below group the main fields with types and defaults. The full source of truth is the JSON schema — set the $schema field and most editors give completion.

Permissions and directories

Model

Environment variables

Hooks and status line

MCP and plugins

Git / worktree / editor integration

Appearance and UX

Persistence and sessions

Auto-update and local search

Custom model provider

Enterprise policy fields

These fields live in managed settings.json (policy layer) and override personal settings; team members cannot undo them.

Env override matrix

env accepts a wide set of variables. Common ones:

For safety, redirect-class variables (ACOSMI_BASE_URL, etc.), trust-root variables (NODE_TLS_REJECT_UNAUTHORIZED, NODE_EXTRA_CA_CERTS), and project-switching vars (API keys / tokens) trigger an extra confirmation dialog when injected via remote managed settings. Writing them in your own user-level settings.json is not gated.

Limits and caveats

• Strict JSON: no comments, no trailing commas
• Three layers merge: settings.local.json is the best place to tweak while debugging without polluting team config
• env is not exported: it lives only inside the CrabCode process; your outer shell stays untouched
• Unknown keys are preserved: when a schema field is renamed across versions, your old key isn't silently deleted — it's just not validated
• Load order: user → project → local → managed; later layers override same-named scalar keys; array-shaped fields merge per their declared semantics
• Enterprise policy fields only apply in managed settings.json: setting allowManagedHooksOnly in personal settings has no effect

Related

• iam
• hooks
• memory
• mcp
• security