cassady/docs/configuration.md

Configuration

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

• config.json: user preferences, such as the default model and access mode.
• providers.json: provider connection definitions.
• models.json: model metadata.

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

config.json

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

Example:

{
  "default_model": "accounts/fireworks/models/qwen3p7-plus",
  "default_access_mode": "read-only",
  "context_message_limit": 80,
  "model_tool_result_limit": 24000,
  "ui_tool_result_limit": 4000
}

Fields:

• default_provider: optional provider id from providers.json. If omitted, Cass infers the provider from default_model when possible.
• default_model: optional model id to use by default.
• default_access_mode: "read-only" or "full-access".
• context_message_limit: optional number of recent non-system messages sent to the model.
• 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.

Deprecated compatibility fields from older Cass 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": "fireworks",
      "name": "Fireworks",
      "kind": "openai-compatible",
      "base_url": "https://api.fireworks.ai/inference/v1",
      "api_key": "$FIREWORKS_API_KEY",
      "default_model": "accounts/fireworks/models/qwen3p7-plus",
      "models": [
        "accounts/fireworks/models/qwen3p7-plus"
      ]
    }
  ]
}

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 "$FIREWORKS_API_KEY".
• default_model: optional model id to use 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. Cass does not expand partial strings or ${NAME} syntax.

models.json

Example:

{
  "models": [
    {
      "id": "accounts/fireworks/models/qwen3p7-plus",
      "provider": "fireworks",
      "display_name": "Qwen 3p7 Plus",
      "context_length": 262144,
      "max_output_tokens": 32768,
      "supports_tools": true,
      "supports_streaming": true
    }
  ]
}

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.

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.

Ask Cass to edit config

Run Cass in full-access mode and ask it to read these docs before editing:

Read ~/.cass/docs/configuration.md, then add an OpenAI-compatible provider named Together using TOGETHER_API_KEY and add model metadata for meta-llama/Llama-3.1-70B-Instruct-Turbo.

After Cass edits the files, run cass check.