# Configuration Precedence and Project Trust in the Codex Plugin > Understand Codex plugin configuration precedence. Discover how project trust dictates the application of user and project level settings on the openai/codex-plugin-cc repository. - Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc) - Tags: deep-dive - Published: 2026-07-07 --- **The Codex plugin loads user-level settings from `~/.codex/config.toml` first, then applies project-level overrides from [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) only if the workspace is explicitly trusted.** The openai/codex-plugin-cc repository implements a hierarchical configuration system that mirrors the underlying Codex app-server behavior. Understanding how configuration precedence works—and how project trust gates access to local settings—is essential for securing your development environment while maintaining flexibility across different codebases. ## Configuration Precedence Hierarchy The plugin recognizes two configuration tiers that merge at runtime. According to the README (lines 80-85), project-level values overwrite matching keys from the user-level file, creating an effective configuration that balances global defaults with per-project customization. ### User-Level Configuration The foundation layer resides at `~/.codex/config.toml` in the user's home directory. This file contains global defaults such as **model selection** and **reasoning effort settings** that apply across all workspaces unless explicitly overridden. ### Project-Level Overrides Workspace-specific settings live in [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) at the repository root. These values take precedence over user-level settings but are only loaded when the project meets trust requirements defined by the Codex runtime. ## How Project Trust Controls Configuration Loading Trust determination prevents untrusted code from silently modifying security-sensitive settings like model providers or API endpoints. When a project lacks trust status, the plugin ignores the local [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) entirely and falls back to user-level configuration only. ### Trust Conditions The Codex CLI, which the plugin delegates to, evaluates three conditions to establish trust: - **`.codex/trust` file**: Generated by running `codex trust`, its presence marks the workspace as explicitly trusted - **Trusted repository domains**: Git remotes pointing to domains listed in the user's `trusted-repos` configuration (set via `codex config trusted-repos`) - **Explicit trust command**: Running `codex trust ` adds the directory to the trusted set for the current user ### Security Implications This trust mechanism ensures that cloned repositories or third-party code cannot silently change model, provider, or other security-critical settings. The plugin communicates with the Codex app-server via `plugins/codex/scripts/lib/codex.mjs`, which enforces these trust checks before reading project-level configuration files. ## Implementation Details in state.mjs The merging logic resides in `plugins/codex/scripts/lib/state.mjs`. The `defaultState()` function establishes baseline configurations including `stopReviewGate: false`, while `loadState()` merges persisted state with defaults according to the precedence order (lines 19-27 and 66-73). ```javascript // Reading effective configuration for the current workspace import { getConfig } from "./plugins/codex/scripts/lib/state.mjs"; const cwd = process.cwd(); const config = getConfig(cwd); console.log("Effective config:", config); ``` ```toml # ~/.codex/config.toml - user-level defaults model = "gpt-4" model_reasoning_effort = "medium" ``` ```toml # .codex/config.toml - project-level overrides (trusted projects only) model = "gpt-5.4-mini" model_reasoning_effort = "high" ``` ```bash # Mark directory as trusted codex trust . # Verify trust status codex status --show-trust ``` ## Summary - Configuration precedence follows a two-tier hierarchy: user-level settings apply first, then project-level overrides (if trusted) - Project trust is required to load [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) and prevents unauthorized configuration changes - Trust can be established via `.codex/trust` files, domain-based repository trust, or explicit `codex trust` commands - The implementation in `plugins/codex/scripts/lib/state.mjs` handles merging through `defaultState()` and `loadState()` functions ## Frequently Asked Questions ### What happens if a project is not trusted? When a project lacks trust status, the plugin ignores any [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) files in the workspace and uses only the user-level configuration from `~/.codex/config.toml`. This prevents potentially malicious repositories from altering model settings or other security-critical parameters without explicit user consent. ### How do I check if my current workspace is trusted? Run the command `codex status --show-trust` in your workspace directory. This queries the Codex CLI's trust database and displays whether the current directory meets the trust conditions required to load project-level configuration files. ### Can I override configuration precedence manually? No, the precedence order is hardcoded in the plugin's state management layer. The `getConfig()` function in `plugins/codex/scripts/lib/state.mjs` always applies user-level settings first, then overlays project-level values only after verifying trust status. To change effective settings in untrusted projects, modify the user-level `~/.codex/config.toml` file instead. ### Where does the plugin store the merged configuration state? The merged state is computed at runtime by the `loadState()` function in `plugins/codex/scripts/lib/state.mjs`. This function combines the baseline from `defaultState()` with any persisted configuration, maintaining the precedence order where project settings override user defaults exclusively for trusted workspaces.