openai / openai/codex-plugin-cc

feat: support a plugin-only Codex configuration layer

Open
#519 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
33.3k
Forks
2.3k
PR merge metrics
No merged PRs in 30d

Description

Problem

The plugin currently inherits ~/.codex/config.toml, so changing the model, reasoning effort, provider, or service tier for an interactive Codex session also changes Claude Code plugin jobs.

This is particularly costly for settings such as service_tier = "fast": a user may want Fast mode interactively without having every background review or delegated task consume the same tier.

Project-level .codex/config.toml is not a complete workaround. Plugin defaults should apply across repositories, while trusted projects must still be able to override those defaults.

Proposed behavior

Support a durable plugin-only Codex configuration file, for example:

~/.codex/config-codex-plugin-cc.toml

Apply configuration in this order, from lowest to highest precedence:

~/.codex/config.toml
~/.codex/config-codex-plugin-cc.toml
trusted project .codex/config.toml
explicit plugin command options such as --model and --effort

Project configuration must retain Codex's existing trust behavior: an untrusted or disabled project layer must not override the plugin-only file.

Example plugin-only configuration:

model = "gpt-5.6-sol"
model_reasoning_effort = "medium"
service_tier = "default"

[features]
fast_mode = false

A malformed plugin-only file should fail with a descriptive error before a Codex thread starts rather than silently falling back to potentially expensive global defaults.

Why profiles and extra arguments do not fully solve this

This is related to #251 and #418, but has different precedence requirements:

  • Selecting a top-level profile still couples the plugin to configuration stored in the general Codex user file.
  • Passing -c overrides or extra app-server arguments places those values above project configuration, preventing trusted project overrides.
  • Environment variables are useful for ephemeral selection but do not provide a discoverable, durable configuration layer with normal TOML semantics.

#213 is also adjacent, but concerns the companion's own operational settings rather than Codex model/provider/service configuration.

Reference implementation

A tested implementation is available here:

https://github.com/megothss/codex-plugin-cc/commit/3c7a316

It parses the plugin-only TOML, reads app-server configuration layers with config/read, excludes leaves supplied by enabled project layers, and passes the remaining values through thread/start.config or thread/resume.config. Tests cover:

  • plugin-only values overriding ordinary user defaults
  • trusted project values overriding conflicting plugin-only leaves
  • disabled/untrusted project layers being ignored
  • malformed TOML stopping before thread creation

This implementation works with the current app-server API, although a native app-server mechanism for inserting a configuration layer at a specified precedence could simplify it if maintainers prefer that direction.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the app-server configuration flow around config/read, then inspect how thread/start.config and thread/resume.config are assembled. Compare the tested reference implementation at commit 3c7a316; done means plugin-only values override ordinary user defaults, trusted project leaves override them, disabled or untrusted layers do not, and malformed TOML prevents thread creation.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
devtools, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.