How to Set Workspace-Scoped Configuration in CodeWhale: A Complete Guide

Set workspace-scoped configuration in CodeWhale by adding a [workspace."/absolute/path"] table to your global ~/.codewhale/config.toml or by creating a per-project overlay at <workspace>/.codewhale/config.toml, with the local overlay taking precedence over global entries.

CodeWhale supports granular workspace-scoped overrides that let you tailor AI assistant settings per project without modifying your user-wide defaults. Understanding how to set workspace-scoped configuration in CodeWhale allows you to safely enable tools like allow_shell for trusted repositories or enforce read-only sandbox modes for sensitive codebases, all while keeping configurations portable and version-controllable.

Global Workspace Entries in User Config

The primary mechanism for workspace-scoped configuration relies on TOML tables keyed to absolute paths inside your global user configuration file.

Syntax for Workspace-Scoped Tables

Open your global configuration at ~/.codewhale/config.toml and add a table named with the absolute path of your workspace. According to [docs/CONFIGURATION.md](https://github.com/Hmbown/CodeWhale/blob/main/docs/CONFIGURATION.md#workspace-entries), the config loader parses these tables and merges values only when the launched workspace path matches the table key (see implementation in [crates/config/src/lib.rs](https://github.com/Hmbown/CodeWhale/blob/main/crates/config/src/lib.rs), lines 23‑34).

# ~/.codewhale/config.toml

[workspace."/home/alice/projects/secure-api"]
allow_shell = true
sandbox_mode = "workspace-write"
model = "claude-3-opus"

Any top-level configuration key can be overridden within this table. When CodeWhale launches from /home/alice/projects/secure-api, it applies these values on top of the global defaults.

Legacy Projects Table Support

For backward compatibility, CodeWhale still accepts the legacy [projects."/absolute/path"] syntax (lines 34‑35 of the config loader). While functional, new configurations should migrate to the [workspace."..."] format as documented in the current specification.

Per-Project Configuration Overlays

If a repository should dictate its own settings—ideal for teams sharing consistent constraints—you can commit a configuration file directly inside the workspace.

Creating a Repo-Local Config File

Create .codewhale/config.toml at the root of your project. This file is automatically discovered and merged on top of the global configuration (including any workspace-scoped entries) when the TUI starts (lines 37‑40).

# <workspace>/.codewhale/config.toml

allow_shell = false          # Explicitly disable even if global entry enables it

sandbox_mode = "read-only"
provider = "deepseek"

The per-project overlay always wins in conflicts. A local allow_shell = false overrides a global workspace entry that sets it to true, ensuring repository owners maintain final control over sensitive permissions.

Bypassing Project Config

To launch CodeWhale while ignoring the per-project overlay—useful for debugging or auditing—pass the --no-project-config flag or set the environment variable CODEWHALE_NO_PROJECT_CONFIG=1 (line 50):

codewhale --no-project-config

Configuration Precedence and Verification

Understanding the merge order prevents unexpected behavior. CodeWhale resolves configuration through this hierarchy, with later sources overriding earlier ones:

1. Global defaults from ~/.codewhale/config.toml
2. Workspace-scoped table matching the current directory path
3. Per-project overlay at <workspace>/.codewhale/config.toml
4. Environment variables (highest priority)

To verify the final merged state for your current working directory, run:

codewhale doctor --json

Inspect the workspace field and key values like allow_shell to confirm which configuration source is active.

Practical Implementation Example

The following workflow demonstrates setting up both global workspace entries and per-project overlays, then verifying the final configuration:

# 1. Edit global config to add a workspace-scoped entry

codewhale config edit   # Opens ~/.codewhale/config.toml in $EDITOR

# Add this table to the file:

# [workspace."/home/alice/projects/data-pipeline"]

# allow_shell = true

# sandbox_mode = "workspace-write"

# 2. Create a per-project overlay that restricts the same workspace

cd /home/alice/projects/data-pipeline
mkdir -p .codewhale
cat > .codewhale/config.toml <<'EOF'
allow_shell = false
sandbox_mode = "read-only"
EOF

# 3. Verify the merged configuration

codewhale doctor --json | jq '.allow_shell, .sandbox_mode'

# Output:

# false

# "read-only"

In this example, the per-project overlay disables shell access despite the global workspace entry enabling it, demonstrating the safety-first precedence rules implemented in [crates/config/src/lib.rs](https://github.com/Hmbown/CodeWhale/blob/main/crates/config/src/lib.rs).

Summary

• Global workspace entries use [workspace."/absolute/path"] tables in ~/.codewhale/config.toml to apply settings only when working in specific directories.
• Per-project overlays at <workspace>/.codewhale/config.toml provide version-controlled, repository-specific defaults that override global settings.
• Precedence is strict: per-project overlay > workspace table > global config > environment variables.
• Bypass locally using --no-project-config when you need to ignore committed configuration files.
• Reference [config.example.toml](https://github.com/Hmbown/CodeWhale/blob/main/config.example.toml) for the canonical structure when creating new configuration files.

Frequently Asked Questions

What is the difference between workspace-scoped and per-project configuration in CodeWhale?

Workspace-scoped configuration resides in your global ~/.codewhale/config.toml inside a path-keyed table like [workspace."/home/user/project"], applying only when you open that specific directory. Per-project configuration is a standalone config.toml file committed inside the repository at .codewhale/config.toml, portable with the codebase and taking precedence over global workspace entries.

Where does CodeWhale store workspace configuration?

CodeWhale does not create a separate file for each workspace. Instead, it stores workspace-specific settings as tables within the global user configuration file at ~/.codewhale/config.toml, or reads them from a local .codewhale/config.toml inside the project root. The effective configuration is computed at runtime by merging these sources according to the precedence rules defined in the source code.

How do I temporarily ignore a project's local config.toml?

Launch CodeWhale with the --no-project-config flag or set the CODEWHALE_NO_PROJECT_CONFIG=1 environment variable. This skips the per-project overlay entirely, loading only the global configuration and any matching workspace-scoped tables, which is useful for testing behaviors without repository-specific restrictions.

Can I use relative paths in workspace table keys?

No. Workspace-scoped tables in the global config must use absolute paths as table names (e.g., [workspace."/home/user/repo"]). Relative paths are not resolved during configuration parsing, as the loader performs literal string matching against the current working directory's absolute path (lines 23‑34 in [crates/config/src/lib.rs](https://github.com/Hmbown/CodeWhale/blob/main/crates/config/src/lib.rs)).

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