Configuration Precedence and Project Trust in the Codex Plugin

The Codex plugin loads user-level settings from ~/.codex/config.toml first, then applies project-level overrides from .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 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 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 <path> 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).

// 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);

# ~/.codex/config.toml - user-level defaults

model = "gpt-4"
model_reasoning_effort = "medium"

# .codex/config.toml - project-level overrides (trusted projects only)

model = "gpt-5.4-mini"
model_reasoning_effort = "high"

# 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 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 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.

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