Configuration

ccode uses YAML configuration files with a two-level merge system: a user-level config for secrets and an optional project-level config for model settings.

Config locations

Field naming

Every profile field maps 1:1 to a Claude Code environment variable. The YAML field name is the lowercased env var name:

ANTHROPIC_BASE_URL        ->  anthropic_base_url
ANTHROPIC_MODEL           ->  anthropic_model
CLAUDE_CODE_EFFORT_LEVEL  ->  claude_code_effort_level

For the full list of ~200+ supported fields, see the Config Reference.

Merge behavior

When both user and project configs exist, ccode merges them field-by-field:

1. User config is loaded first (base layer, carries secrets)
2. Project config is overlaid on top (model settings override user values)
3. --config flag replaces the project config in the merge chain

Launch modes

ccode can automatically enable Claude Code’s launch modes via config. Each has a --flag/--no-flag CLI override.

always_yolo takes priority over always_auto (they’re mutually exclusive permission modes). always_control can be combined with either.

Note: At the time of writing, claude remote-control does not accept custom permission flags (--dangerously-skip-permissions or --permission-mode auto). Combining --control with --auto or --yolo will print a warning but still attempt to pass the flags, in case a future Claude Code update enables it. Auto permissions can be set in the Claude app/web UI instead.

Global env

The top-level env: block sets environment variables for all profiles. This is useful for settings you want everywhere:

env:
  DISABLE_TELEMETRY: "1"
  CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: "80"

profiles:
  default: {}
  deepseek:
    anthropic_base_url: https://api.deepseek.com/anthropic
    anthropic_auth_token: sk-your-key-here

Each profile can also have its own env: block for per-profile overrides. Priority order: global env < profile fields < profile env.

Example user config

default_profile: deepseek

profiles:
  # Passthrough - launches Claude Code as-is with your subscription
  default: {}

  deepseek:
    anthropic_base_url: https://api.deepseek.com/anthropic
    anthropic_auth_token: sk-your-deepseek-key-here
    anthropic_model: "deepseek-v4-pro[1m]"
    anthropic_default_opus_model: "deepseek-v4-pro[1m]"
    anthropic_default_sonnet_model: "deepseek-v4-pro[1m]"
    anthropic_default_haiku_model: deepseek-v4-flash
    claude_code_subagent_model: deepseek-v4-flash
    claude_code_effort_level: max
    env:
      CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: "1"

Split config example

User config (~/.config/ccode/config.yaml) - has secrets, never committed:

default_profile: deepseek
profiles:
  deepseek:
    anthropic_auth_token: sk-abc123
  openrouter:
    anthropic_auth_token: sk-or-xyz789

Project config (./ccode.yaml) - safe to commit:

default_profile: deepseek
profiles:
  deepseek:
    anthropic_base_url: https://api.deepseek.com/anthropic
    anthropic_model: "deepseek-v4-pro[1m]"
    anthropic_default_opus_model: "deepseek-v4-pro[1m]"
    anthropic_default_sonnet_model: "deepseek-v4-pro[1m]"
    anthropic_default_haiku_model: deepseek-v4-flash
    claude_code_subagent_model: deepseek-v4-flash
    claude_code_effort_level: max
    env:
      CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: "1"

The merged result has both the API key (from user config) and the model settings (from project config).

The idea is that the project configs could allow using a faster model (like DeepSeek V4 Flash) for one project, and demand using a bigger model (like DeepSeek V4 Pro) for another, all while the actual API keys per-user remain private and there’s lower risk of accidentally committing and pushing them somewhere public.

If you need per-project API keys or want them committed to your private repositories you can do that too, just please be careful.

More info

• Providers - setup guides for every supported provider
• Config Reference - complete list of all YAML fields