Configuration

Cusp is configured with JSON settings files in the widely used settings.json format. You don't need any of them to get started. They exist for when you want to pin a model, pre-approve commands, add hooks or adjust the sandbox.

Settings filesCopy Anchor Link

At each scope Cusp also reads the shared file (.claude/settings.local.json, .claude/settings.json, ~/.claude/settings.json). When both exist at the same scope, the .cusp/ file takes precedence.

Managed settingsCopy Anchor Link

How settings combineCopy Anchor Link

Precedence, highest first: managed → command line → local → project → user.

• Scalar values (model, effortLevel, …): the highest scope that sets the key wins.
• Permission rules from every scope are combined, then evaluated deny → ask → allow. A deny anywhere wins.
• Hooks from every scope all run.
• env values are merged, with higher scopes winning per variable.

Settings are read leniently. Unknown keys are kept and ignored. A known key with an invalid value is dropped with a warning naming the file and key, and the rest of the file still applies. A file that isn't valid JSON is skipped with a warning.

What a project can't setCopy Anchor Link

A repository's settings come from whoever wrote the repository, so some keys are limited:

• Until you trust the workspace, project and local files can't set hooks, env, apiKeyHelper, statusLine, enableAllProjectMcpServers, enabledMcpjsonServers, permissions.allow or permissions.additionalDirectories. Deny and ask rules still apply, because they only narrow what the agent can do.
• Ever: project and local files can't set permissions.defaultMode to auto or bypassPermissions, and can't set protected environment variables (HOME, TMPDIR, TMP, TEMP, XDG_*, OTEL_EXPORTER_OTLP_*, and the config directory variables of Cusp and of the agents whose files it reads). They also can't weaken the sandbox: turning it off, opening localhost or Unix sockets, or adding readable or writable paths only works from user, managed or --settings files.
• Managed only: allowManagedHooksOnly and allowManagedPermissionRulesOnly take effect only in managed settings.

ExampleCopy Anchor Link

{
  "model": "anthropic:claude-opus-5-5",
  "effortLevel": "medium",
  "permissions": {
    "allow": ["Bash(bun test *)", "Bash(bun run lint)", "Edit(src/**)"],
    "deny": ["Read(.env)", "Read(**/*.pem)"],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_OPTIONS": "--max-old-space-size=8192"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write|ApplyPatch",
        "hooks": [{ "type": "command", "command": "bunx biome format --write ." }]
      }
    ]
  }
}

KeysCopy Anchor Link

ModelCopy Anchor Link

PermissionsCopy Anchor Link

Rule syntax is described in Permissions.

HooksCopy Anchor Link

SandboxCopy Anchor Link

autoAllowBashIfSandboxed, allowUnsandboxedCommands, excludedCommands, filesystem.denyWrite and network.allowAllUnixSockets are accepted so existing settings load, but not applied yet. Settings that weaken the sandbox are ignored in project settings. See Sandbox.

MCPCopy Anchor Link

See MCP servers.

Instructions, skills and agentsCopy Anchor Link

Environment and toolsCopy Anchor Link

GitCopy Anchor Link

HousekeepingCopy Anchor Link

Other files Cusp readsCopy Anchor Link

Every .cusp/ path has a ~/.cusp/ user-level counterpart, and a .claude/ equivalent that Cusp also reads.

Daemon configurationCopy Anchor Link

The daemon takes its own configuration from flags and CUSP_* environment variables. You rarely need these; the desktop app and CLI set them for you.