Конфигурация

Cusp настраивается JSON-файлами настроек в распространённом формате settings.json. Чтобы начать работу, ни один из них не нужен. Они пригодятся, когда вы захотите закрепить модель, заранее разрешить команды, добавить хуки или настроить песочницу.

Файлы настроекСкопировать ссылку на раздел

На каждом уровне Cusp также читает общий файл (.claude/settings.local.json, .claude/settings.json, ~/.claude/settings.json). Если на одном уровне есть оба, приоритет у файла из .cusp/.

Управляемые настройкиСкопировать ссылку на раздел

Как объединяются настройкиСкопировать ссылку на раздел

Приоритет, от наивысшего: управляемые → командная строка → локальные → проектные → пользовательские.

• Скалярные значения (model, effortLevel, …): побеждает самый высокий уровень, где задан ключ.
• Правила разрешений со всех уровней объединяются и проверяются в порядке deny → ask → allow. Запрет на любом уровне побеждает.
• Хуки со всех уровней выполняются все.
• Значения env объединяются; для каждой переменной побеждает более высокий уровень.

Настройки читаются нестрого. Неизвестные ключи сохраняются и игнорируются. Известный ключ с недопустимым значением отбрасывается с предупреждением, где указаны файл и ключ, а остальная часть файла всё равно применяется. Файл с некорректным JSON пропускается с предупреждением.

Что не может задать проектСкопировать ссылку на раздел

Настройки репозитория пишет автор репозитория, поэтому некоторые ключи ограничены:

• Пока вы не доверились рабочей области, проектные и локальные файлы не могут задавать hooks, env, apiKeyHelper, statusLine, enableAllProjectMcpServers, enabledMcpjsonServers, permissions.allow и permissions.additionalDirectories. Правила deny и ask при этом действуют, потому что они только сужают возможности агента.
• Никогда: проектные и локальные файлы не могут установить permissions.defaultMode в auto или bypassPermissions и не могут задавать защищённые переменные окружения (HOME, TMPDIR, TMP, TEMP, XDG_*, OTEL_EXPORTER_OTLP_*, а также переменные с папками конфигурации Cusp и агентов, чьи файлы он читает). Ослабить песочницу они тоже не могут: отключить её, открыть localhost или Unix-сокеты, добавить пути для чтения или записи можно только в пользовательских, управляемых файлах или в файлах --settings.
• Только управляемые: allowManagedHooksOnly и allowManagedPermissionRulesOnly действуют только в управляемых настройках.

ПримерСкопировать ссылку на раздел

{
  "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 ." }]
      }
    ]
  }
}

КлючиСкопировать ссылку на раздел

МодельСкопировать ссылку на раздел

РазрешенияСкопировать ссылку на раздел

Синтаксис правил описан в разделе Разрешения.

ХукиСкопировать ссылку на раздел

ПесочницаСкопировать ссылку на раздел

autoAllowBashIfSandboxed, allowUnsandboxedCommands, excludedCommands, filesystem.denyWrite и network.allowAllUnixSockets принимаются, чтобы существующие настройки загружались, но пока не применяются. Настройки, ослабляющие песочницу, в проектных настройках игнорируются. См. Песочница.

MCPСкопировать ссылку на раздел

См. MCP-серверы.

Инструкции, навыки и агентыСкопировать ссылку на раздел

Окружение и инструментыСкопировать ссылку на раздел

GitСкопировать ссылку на раздел

ОбслуживаниеСкопировать ссылку на раздел

Другие файлы, которые читает CuspСкопировать ссылку на раздел

У каждого пути в .cusp/ есть пользовательский аналог в ~/.cusp/ и эквивалент в .claude/, который Cusp тоже читает.

Конфигурация демонаСкопировать ссылку на раздел

Демон (daemon) берёт собственную конфигурацию из флагов и переменных окружения CUSP_*. Они редко нужны: десктопное приложение и CLI задают их за вас.