cassady/docs/configuration.md

Configuration

Cassady reads user-editable config files from ~/.cass.

• config.json: user preferences, active defaults, and compatibility fields.
• providers.json: provider connection definitions.
• models.json: model metadata.
• global.md: optional global instructions included in new chat system prompts when they fit the active request; they cannot override access modes, tool denials, approvals, or workspace boundaries.
• conversations/: saved JSONL chats.
• docs/: bundled docs installed from the current binary.

Cassady creates providers.json and models.json automatically if they are missing. The default provider is Fireworks.

Setup wizard

Run:

cass setup

Cassady also offers setup automatically when cass cannot resolve a usable active provider, model, or API key before starting a chat.

The wizard uses keyboard prompts: ↑/↓ moves through choices, Space selects providers in the multi-select screen, and Enter submits. Text fields use the same prompt style instead of falling back to plain line input.

The wizard supports configuring multiple OpenAI-compatible providers at once. If more than one provider is configured, setup asks which one should be active first. If the selected API key environment variable is set, Cassady tries to fetch models from GET {base_url}/models and lets you choose one. If discovery fails, it offers a retry before falling back to manual model entry. If the API key is not set, setup asks for a model id manually.

Setup stores API keys as environment-variable references such as "$OPENAI_API_KEY" by default. After setup, Cassady writes/updates config.json, providers.json, and models.json, validates them, and starts a chat only when the active API key is available in the current shell.

config.json

config.json should contain preferences only. Provider connection details belong in providers.json; model metadata belongs in models.json.

Example:

{
  "default_provider": "openai",
  "default_model": "gpt-4.1",
  "default_reasoning_effort": "medium",
  "default_access_mode": "read-only",
  "context_message_limit": 80,
  "model_tool_result_limit": 24000,
  "ui_tool_result_limit": 4000,
  "show_reasoning": false,
  "confirm_destructive_operations": false
}

Fields:

• default_provider: optional provider id from providers.json. If omitted, Cassady infers the provider from default_model when possible.
• default_model: optional model id to use by default.
• default_reasoning_effort: optional off, low, medium, or high, clamped to model metadata.
• default_access_mode: "read-only", "workspace-edit", or "full-access".
• context_message_limit: optional legacy upper bound for recent non-system messages. Cassady primarily budgets context from model metadata and trims along valid tool-call boundaries.
• model_tool_result_limit: optional max bytes of tool output sent back to the model.
• ui_tool_result_limit: optional max bytes of tool output shown in the UI unless full output is toggled.
• show_reasoning: optional boolean, defaults to false. Shows provider-streamed reasoning in the transcript.
• confirm_destructive_operations: optional compatibility preference currently stored in config.

Deprecated compatibility fields from older Cassady versions are still accepted: provider, model, base_url, and api_key_env. Prefer moving provider connection details to providers.json.

providers.json

Example:

{
  "providers": [
    {
      "id": "openai",
      "name": "OpenAI",
      "kind": "openai-compatible",
      "base_url": "https://api.openai.com/v1",
      "api_key": "$OPENAI_API_KEY",
      "default_model": "gpt-4.1",
      "models": ["gpt-4.1"]
    }
  ]
}

Fields:

• id: required unique provider id.
• name: optional display name.
• kind: required provider kind. Currently only "openai-compatible" is supported.
• base_url: required OpenAI-compatible API base URL.
• api_key: required string. Use either a literal key or an environment-variable reference like "$OPENAI_API_KEY".
• default_model: optional model id used when no default model is configured.
• models: optional list of model ids associated with this provider.

Only strings that start with $ are resolved as environment variables. Cassady does not expand partial strings or ${NAME} syntax.

models.json

Example:

{
  "models": [
    {
      "id": "gpt-4.1",
      "provider": "openai",
      "display_name": "GPT-4.1",
      "context_length": 1047576,
      "max_output_tokens": 32768,
      "supports_tools": true,
      "supports_streaming": true,
      "reasoning": {
        "supported": true,
        "required": false,
        "default_effort": "medium",
        "request_format": "reasoning_effort"
      }
    }
  ]
}

Fields:

• id: required model id sent to the provider.
• provider: required provider id from providers.json.
• display_name: optional human-friendly name.
• context_length: optional positive integer.
• max_output_tokens: optional positive integer.
• supports_tools: optional boolean, defaults to true.
• supports_streaming: optional boolean, defaults to true.
• reasoning: optional object. Defaults to reasoning support enabled with medium effort for model entries.
  • supported: optional boolean, defaults to true.
  • required: optional boolean, defaults to false.
  • default_effort: optional off, low, medium, or high; defaults to medium. Cannot effectively be off when required is true.
  • request_format: optional reasoning_effort or reasoning_object; defaults to reasoning_effort.

Reasoning effort is a runtime per-turn setting. Press Tab to cycle it while idle. Provider-streamed reasoning is persisted and sent back in future model context using the provider's reasoning field, such as reasoning_content or reasoning.

Precedence

• CLI access-mode flags override default_access_mode for the current session.
• --model overrides the configured default model for the current session.
• --base-url overrides the active provider base URL for the current session.
• --api-key-env ENV makes the active provider read $ENV for the current session.
• config.json preferences override built-in defaults.
• Provider defaults in providers.json are used when no configured model is selected.
• Environment variables provide the actual API key value when api_key starts with $.

Check configuration

Run:

cass check

This validates JSON syntax, expected schema, duplicate provider/model ids, model/provider references, active provider/model resolution, and API key environment-variable availability. Missing API keys for inactive providers are warnings; a missing active provider API key is an error.

When setup is incomplete, cass check prints actionable next steps such as:

export PROVIDER_API_KEY=...
cass check
cass

Safe manual editing

1. Edit one file at a time.
2. Keep provider ids and model provider references in sync.
3. Prefer API key env references over literal keys.
4. Run cass check before starting a chat.

Invalid JSON, unknown fields, duplicate ids, and missing provider/model links are reported by cass check with the file that failed.