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

> Learn how to set workspace-scoped configuration in CodeWhale. Discover methods for global and project-specific settings to optimize your workflow. Master CodeWhale config today.

- Repository: [Hunter Bown/CodeWhale](https://github.com/Hmbown/CodeWhale)
- Tags: how-to-guide
- Published: 2026-06-02

---

**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)](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)](https://github.com/Hmbown/CodeWhale/blob/main/crates/config/src/lib.rs), lines 23‑34).

```toml

# ~/.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`](https://github.com/Hmbown/CodeWhale/blob/main/.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).

```toml

# <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):

```bash
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:

```bash
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:

```bash

# 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)](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)](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`](https://github.com/Hmbown/CodeWhale/blob/main/config.toml) file committed inside the repository at [`.codewhale/config.toml`](https://github.com/Hmbown/CodeWhale/blob/main/.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`](https://github.com/Hmbown/CodeWhale/blob/main/.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)](https://github.com/Hmbown/CodeWhale/blob/main/crates/config/src/lib.rs)).