CodeWhale Configuration File Locations and Precedence: Complete Guide

CodeWhale loads configuration from five hierarchical sources, with CLI arguments overriding environment variables, per-project overlays, workspace entries, and global defaults stored in ~/.codewhale/config.toml.

CodeWhale, the AI-powered terminal coding assistant from the Hmbown/CodeWhale repository, uses a cascading configuration system that merges multiple TOML files and environment variables. Understanding exactly where CodeWhale looks for settings—and which source wins when conflicts arise—is essential for managing API keys, model selections, and behavior flags across different development environments.

Configuration File Locations

CodeWhale discovers settings by scanning six distinct sources across the filesystem. Each location serves a specific purpose, from global user defaults to directory-specific overrides.

Global Default and Legacy Fallback

The primary global configuration resides at ~/.codewhale/config.toml. This file loads automatically on startup and defines baseline settings for all workspaces.

If the modern path does not exist, CodeWhale falls back to the legacy ~/.deepseek/config.toml location. This backward compatibility supports users migrating from the previous DeepSeek-branded iteration of the tool.

CLI and Environment Overrides

Users can bypass the default discovery mechanism through two override methods:

• --config /path/to/file.toml – Supplied as a command-line argument, this path takes absolute precedence over all other sources.
• CODEWHALE_CONFIG_PATH (or the historic alias DEEPSEEK_CONFIG_PATH) – Environment variable pointing to an alternative config file. This applies after the global file loads but yields to --config arguments.

Workspace and Project-Level Configuration

For granular control, CodeWhale supports scoped configurations that apply only to specific directories:

• User-workspace entries – Tables defined in the global file under [workspace."/abs/path/to/project"] (or the legacy [projects."/abs/path"] syntax). These entries activate when the current working directory matches the specified path.
• Per-project overlay – A config.toml file located at <workspace>/.codewhale/config.toml (with fallback to <workspace>/.deepseek/config.toml). This overlay merges on top of the global configuration only when the current directory contains such a file. Use the --no-project-config flag to skip this layer for a single run.

Configuration Precedence Order (Highest to Lowest)

When multiple configuration sources define the same key, CodeWhale resolves values using this strict hierarchy:

1. CLI --config – Explicit file paths specified on the command line win over every other source.
2. CODEWHALE_CONFIG_PATH – Environment variable overrides the global default file but is itself overridden by --config.
3. Per-project overlay – Values in <workspace>/.codewhale/config.toml merge on top of the global config when present.
4. User-workspace entries – Scoped tables like [workspace."/abs/path"] in the global file apply to matching directories. These merge before the per-project overlay, meaning a project-level allow_shell = false still takes precedence over a workspace entry.
5. Global default file – ~/.codewhale/config.toml serves as the foundation. If absent, the legacy ~/.deepseek/config.toml loads instead.

How Configuration Loading Works in the Source Code

The precedence logic is implemented in crates/tui/src/config.rs within the Config::load function (lines 1857–1900). This function orchestrates the loading sequence: reading the default file, applying environment variable overrides, then merging any per-project overlay while respecting the hierarchy described above.

// Conceptual flow from crates/tui/src/config.rs
let config = Config::load()
    .with_global_default()?
    .apply_env_override(CODEWHALE_CONFIG_PATH)?
    .merge_workspace_entries(current_dir)?
    .merge_project_overlay(current_dir)?;

Key supporting files include:

• crates/tui/src/config_ui.rs – Provides the interface for editing configuration files and managing per-project overlays.
• config.example.toml – Reference template documenting all supported top-level keys such as provider, model, and api_key.
• docs/CONFIGURATION.md – Human-readable specification of location discovery and precedence rules.
• docs/REBRAND.md – Documents the legacy ~/.deepseek fallback behavior and migration paths.

Practical Configuration Examples

Use these patterns to control CodeWhale's configuration resolution in daily workflows:

# Use the global config from ~/.codewhale/config.toml

codewhale chat "Explain the main() function"

# Override with an explicit configuration file

codewhale --config ./team-config.toml chat "Review this PR"

# Set configuration via environment variable

export CODEWHALE_CONFIG_PATH=$HOME/.codewhale/work-config.toml
codewhale chat "Show current model settings"

# Create a per-project overlay in repository root

echo 'provider = "openai"' > ./.codewhale/config.toml
echo 'model = "gpt-4o-mini"' >> ./.codewhale/config.toml
codewhale chat "Run with project-specific settings"

# Ignore project-level configuration for one execution

codewhale --no-project-config chat "Use global settings only"

Summary

• CodeWhale searches six configuration sources, from global defaults to CLI arguments.
• Highest precedence: --config flag, followed by CODEWHALE_CONFIG_PATH environment variable.
• Per-project overlays in <workspace>/.codewhale/config.toml override global settings but yield to CLI and environment overrides.
• User-workspace entries in the global file provide directory-scoped configuration without creating separate files.
• Legacy ~/.deepseek/ paths serve as fallbacks for backward compatibility.
• The loading logic resides in crates/tui/src/config.rs, specifically the Config::load implementation.

Frequently Asked Questions

Where does CodeWhale store its global configuration file?

CodeWhale stores global settings in ~/.codewhale/config.toml. If this file does not exist, the application falls back to the legacy path ~/.deepseek/config.toml to support users migrating from earlier versions.

How do I temporarily override CodeWhale's configuration without editing files?

Set the CODEWHALE_CONFIG_PATH environment variable to point to an alternative TOML file, or use the --config /path/to/file.toml command-line argument. The CLI flag takes precedence over the environment variable.

Can I disable the per-project configuration for a single command?

Yes. Pass the --no-project-config flag to skip loading <workspace>/.codewhale/config.toml for that specific invocation. This forces CodeWhale to use only global settings and workspace entries.

What happens if both a workspace entry and a project overlay define the same key?

The per-project overlay wins. According to the configuration logic in docs/CONFIGURATION.md, workspace entries in the global file merge first, then per-project overlays apply on top. This means a config.toml file in your project directory can override settings defined in [workspace."/abs/path"] tables.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}