Docs
Refer a friend. Get a weekly-quota reset.Friend signs up and uses it → +1 reset (valid 30 days) · up to 10% cash back on their spend.
+1 resetGenerate link

Settings (settings.json)

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

What it is

settings.json decides how wrok Code 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 wrok Code'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

json
{
  "$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-flash",
  "smallModel": "deepseek-flash",
  "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-flash",
  "smallModel": "deepseek-flash",
  "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

FieldTypeDefaultDescription
permissions.defaultModeenum: default / acceptEdits / plan / bypassPermissions / dontAskdefaultPermission mode at startup. See iam
permissions.allowstring[]—Allow rules, e.g. Bash(npm test:*)
permissions.denystring[]—Deny rules (highest precedence)
permissions.askstring[]—Rules that always prompt
permissions.additionalDirectoriesstring[]—Extra directories outside cwd that wrok Code may access
permissions.disableBypassPermissionsMode"disable"—Disable the bypassPermissions mode (usually managed)

Model

FieldTypeDefaultDescription
modelstringdeepseek-flashMain conversation model ID
smallModelstringdeepseek-flashLightweight model for token estimation / compact / hooks / search
alwaysThinkingEnabledbooleantrueAuto-enable thinking on supported models
effortLevelenum: low / medium / high—Persisted effort level
fastModebooleanfalseEnable fast mode
fastModePerSessionOptInbooleanfalseFast mode does not persist across sessions
showThinkingSummariesbooleanfalseShow thinking summaries in the transcript view (Ctrl+O)

Environment variables

FieldTypeDefaultDescription
envrecord[string,string]—Env vars injected into the wrok Code process; see the env matrix below
apiKeyHelperstring—Path to a script whose stdout is used as an auth token
awsCredentialExport / awsAuthRefreshstring—AWS credential export / refresh scripts
gcpAuthRefreshstring—GCP auth refresh command
otelHeadersHelperstring—Script that outputs OpenTelemetry headers

Hooks and status line

FieldTypeDefaultDescription
hooksobject—Shell hooks around tool execution; see hooks
disableAllHooksbooleanfalseDisable all hooks and statusLine execution
statusLine&#123; type: "command", command, padding? &#125;—Custom status line command
allowedHttpHookUrlsstring[]—Allowlist of URL patterns HTTP hooks may target
httpHookAllowedEnvVarsstring[]—Env var names HTTP hooks may interpolate into headers

MCP and plugins

FieldTypeDefaultDescription
enableAllProjectMcpServersbooleanfalseAuto-approve every MCP server in the project's .mcp.json
enabledMcpjsonServersstring[]—Approved .mcp.json server list
disabledMcpjsonServersstring[]—Rejected .mcp.json server list
enabledPluginsrecord[plugin-id@marketplace-id, bool/array]—Enabled plugin map
extraKnownMarketplacesrecord[string, object]—Extra marketplaces registered for this repository
pluginConfigsrecord[string, object]—Per-plugin config, keyed by plugin@marketplace

Git / worktree / editor integration

FieldTypeDefaultDescription
includeCoAuthoredBybooleantrueWhether commits include Co-Authored-By (deprecated; prefer attribution)
attribution.commitstring—Custom commit attribution text (empty string hides it)
attribution.prstring—Custom PR description attribution text
includeGitInstructionsbooleantrueInclude built-in commit / PR workflow instructions in the system prompt
worktree.symlinkDirectoriesstring[]—Directories to symlink from main repo into worktrees (e.g. node_modules)
worktree.sparsePathsstring[]—Sparse-checkout paths for large monorepos
defaultShellenum: bash / powershellbashShell backing input-box ! commands
respectGitignorebooleantrueWhether the file picker respects .gitignore

Appearance and UX

FieldTypeDefaultDescription
outputStylestringdefaultAssistant output style; switch with /output-style
languagestring—Preferred language (e.g. "japanese" / "spanish")
syntaxHighlightingDisabledbooleanfalseDisable syntax highlighting in diffs
prefersReducedMotionbooleanfalseReduce animations (spinner shimmer, flashes, etc.)
spinnerTipsEnabledbooleantrueWhether to show spinner tips
spinnerVerbs&#123; mode: "append" / "replace", verbs: string[] &#125;—Customize spinner verbs
spinnerTipsOverride&#123; excludeDefault?: bool, tips: string[] &#125;—Override spinner tips
terminalTitleFromRenamebooleantrueWhether /rename updates the terminal tab title

Persistence and sessions

FieldTypeDefaultDescription
cleanupPeriodDaysint ≥ 030Days to retain chat transcripts; 0 disables persistence entirely
autoMemoryEnabledboolean—Enable auto-memory (project-scoped memory)
autoMemoryDirectorystring~/.crabcode/projects/[sanitized-cwd]/memory/Auto-memory storage path (supports ~/ prefix)
autoDreamEnabledboolean—Enable background memory consolidation (auto-dream)
crabcodeMdExcludesstring[]—Glob patterns to exclude when loading CRABCODE.md files
FieldTypeDefaultDescription
autoUpdatesChannelenum: latest / stablelatestAuto-update channel
minimumVersionstring—Pin a minimum version (prevents downgrades when switching to stable)
webSearch.providerenum: ali / bocha—Local search provider (replaces OAuth with a local API key)
webSearch.ali.apiKey / endpoint / modelstring—Alibaba DashScope search config
webSearch.bocha.apiKey / endpointstring—Bocha search config

Custom model provider

FieldTypeDefaultDescription
customModel.providerstring (enum)—Provider type; possible values are listed by the /login → "Custom model configuration" flow
customModel.baseUrlstring (URL)—API base URL (e.g. https://api.example.com/v1)
customModel.apiKey / apiKeyHandlestring—API key in plaintext or secure-storage handle (one of)
customModel.modelsrecord[alias, ModelDef]—Model definitions with id / contextWindow / maxOutputTokens / supportsThinking, etc.

Enterprise policy fields

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

FieldTypeDescription
availableModelsstring[]Allowlist of selectable models; accepts family aliases / version prefixes / full IDs. Empty array means only the default model
modelOverridesrecord[string, string]Map from acosmi-canonical model ID to provider-specific ID (e.g. a Bedrock inference profile ARN)
allowManagedHooksOnlybooleanOnly managed hooks run; user/project/local hooks ignored
allowManagedPermissionRulesOnlybooleanOnly managed allow/deny/ask rules apply
allowManagedMcpServersOnlybooleanallowedMcpServers read from managed only (deniedMcpServers still merges)
allowedMcpServersobject[]MCP server allowlist (one of serverName / serverCommand / serverUrl)
deniedMcpServersobject[]MCP server denylist (takes precedence over the allowlist)
strictPluginOnlyCustomizationboolean / ("skills" / "agents" / "hooks" / "mcp")[]Lock the listed surfaces so they can only be customized via plugins
strictKnownMarketplacesobject[]Strict allowlist of marketplace sources (checked before download)
blockedMarketplacesobject[]Marketplace source blocklist (checked before download)
forceLoginMethodenum: acosmi / consoleForce a specific login method
forceLoginOrgUUIDstringOrganization UUID used for OAuth login
pluginTrustMessagestringCustom text appended to the plugin trust warning
companyAnnouncementsstring[]Startup announcements (one is picked at random when multiple are set)
skipWebFetchPreflightbooleanSkip WebFetch blocklist preflight (for environments with restrictive network policies)
sshConfigsobject[]Pre-configured SSH connections for remote environments

Env override matrix

env accepts a wide set of variables. Common ones:

VariableUse
ACOSMI_BASE_URLAcosmi gateway address (self-hosted / staging)
ACOSMI_API_KEY / ACOSMI_AUTH_TOKENDirect Acosmi auth
ACOSMI_MODELMain model default (equivalent to model, env wins)
ACOSMI_DEFAULT_MODEL / ACOSMI_DEFAULT_FAST_MODE_MODEL / ACOSMI_DEFAULT_MAX_EFFORT_MODELDefault / fast / max-effort model overrides
ACOSMI_SMALL_FAST_MODELsmallModel default
CRABCODE_USE_BEDROCK=1Route through Amazon Bedrock
CRABCODE_USE_VERTEX=1Route through Google Vertex AI
CRABCODE_USE_FOUNDRY=1Route through Microsoft Foundry
ACOSMI_BEDROCK_BASE_URL / ACOSMI_VERTEX_BASE_URL / ACOSMI_FOUNDRY_BASE_URLPer-provider base URL overrides
VERTEX_REGION_[model-id]Per-model Vertex region routing (prefix-matched)
BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS / BASH_MAX_OUTPUT_LENGTHBash tool default / max timeouts and output cap
MCP_TIMEOUT / MCP_TOOL_TIMEOUT / MAX_MCP_OUTPUT_TOKENSMCP startup / tool-call timeouts; per-call output cap
CRABCODE_MAX_OUTPUT_TOKENSModel output token cap
MAX_THINKING_TOKENSThinking budget cap
CRABCODE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1Bash tool keeps project cwd (no drift after cd)
CRABCODE_DISABLE_NONESSENTIAL_TRAFFIC=1Disable non-essential telemetry / analytics traffic
CRABCODE_DISABLE_TERMINAL_TITLE=1Disable terminal title updates
CRABCODE_IDE_SKIP_AUTO_INSTALL=1Skip IDE auto-install prompts
DISABLE_BUG_COMMAND=1Disable /bug
DISABLE_FEEDBACK_COMMAND=1Disable /feedback
DISABLE_TELEMETRY=1Disable telemetry upload
DISABLE_ERROR_REPORTING=1Disable error reporting
DISABLE_AUTOUPDATER=1Disable auto-update
DISABLE_COST_WARNINGS=1Suppress cost warning dialogs

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 wrok Code 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