›_ Codex Issues
Codex Issues / #19679

Make skills metadata context budget configurable instead of hardcoded 2%

Open 💬 17 comments Opened Apr 26, 2026 by iqdoctor
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What problem does this solve?

Codex currently reserves a fixed 2% of the model context window for the model-visible skills metadata list. When many skills are installed, this can produce warnings like:

Warning: Exceeded skills context budget of 2%. Loaded skill descriptions were truncated by an average of N characters per skill.

The problem is that the percentage is hardcoded and cannot be tuned by users or distributions with larger skill catalogs.

Where is it hardcoded?

On origin/main today:

  • codex-rs/core-skills/src/render.rs
  • const SKILL_METADATA_CONTEXT_WINDOW_PERCENT: usize = 2;
  • default_skill_metadata_budget(...) computes context_window * SKILL_METADATA_CONTEXT_WINDOW_PERCENT / 100.
  • budget_warning_prefix(...) also hardcodes the user-facing warning text as Exceeded skills context budget of 2%.

Relevant current code:

const DEFAULT_SKILL_METADATA_CHAR_BUDGET: usize = 8_000;
const SKILL_METADATA_CONTEXT_WINDOW_PERCENT: usize = 2;
SkillMetadataBudget::Tokens(
    window
        .saturating_mul(SKILL_METADATA_CONTEXT_WINDOW_PERCENT)
        .saturating_div(100)
        .max(1),
)
"Exceeded skills context budget of 2%."

Why this should be configurable

Different installations can have very different skill/plugin surfaces:

  • small default installs may be fine with 2%;
  • power-user or enterprise installs can have many local/project/plugin skills;
  • larger context-window models can reasonably allocate more than 2% to skill discovery;
  • some users may prefer the opposite and want a smaller budget.

Right now the only way to change this is to patch and rebuild Codex.

Requested behavior

Please expose the skills metadata budget as a configurable setting, for example one or more of:

  • skills.metadata_context_window_percent / skills.context_budget_percent in config;
  • an absolute token budget override;
  • an environment variable override;
  • dynamic warning text that reflects the effective configured value instead of always saying 2%.

Expected result

Users should be able to tune the skill metadata budget without modifying source code, and warnings should report the effective budget value.

View original on GitHub ↗

17 Comments

github-actions[bot] contributor · 2 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #19090

Powered by Codex Action

tstager · 2 months ago

I have the same issue and believe that the OP is correct that this behavior should be adjusted to be configurable by the user.

informal-stripes-condo · 2 months ago

+1, I think there should be a config option for this

aldegad · 2 months ago

Adding a concrete data point from a current local catalog because it points to a companion issue, not just the configurable-budget request.

Environment:

  • Codex CLI: codex-cli 0.125.0-alpha.3
  • OS: macOS
  • Warning observed:
Warning: Exceeded skills context budget of 2%. Loaded skill descriptions were truncated by an average of 235 characters per skill.

In that setup, trimming only local/project skill descriptions reduced total loaded skill-description payload from about 15,822 chars to about 13,992 chars and stopped the warning in a fresh codex exec smoke run. So configurability would help, but catalog-side description length also matters.

Audit of only first-party plugin skill descriptions found:

  • 25 plugin skills
  • 7,908 total description characters
  • 19 descriptions over 220 chars
  • top examples include Hugging Face vision trainer (775 chars), LLM trainer (629), HF Jobs (561), Gmail (429), Transformers.js (393), GitHub gh-address-comments (387), and Google Calendar (346).

I filed the plugin/catalog hygiene side separately here: #19957

I think these two fixes complement each other:

  1. make the metadata budget configurable, as requested in this issue;
  2. keep first-party plugin frontmatter descriptions short/linted so the default catalog does not consume a large share of the budget by itself.
ariccio · 2 months ago

Yeah, wait, WTF, I need to optimize and heavily prune mine, I know, but why just truncate them!?

1Const1 · 2 months ago

agreed with that affected 125 version of cli. so it looks like downgrade abilities of codex

Need parameter for this in config

TheSingular · 2 months ago

It seems they have added the ability to just shorten the skill description if it exceeds the budget now, but it has not been the same ever since they added the "budget".

BinaryOutlook · 2 months ago

+1

Cerebrovinny · 2 months ago

+1

em-winterschon · 2 months ago

The fix is simple. OAI makes it a configurable setting or people will find an alternative, especially those with their own colocated GPU infra who use Codex for specific tasks. Ignoring "power users" is a very bad idea. We will code around it and stop paying for Pro accounts if we're ignored for too long, just wait and see.

JoeChen2me · 2 months ago

I implemented this in my fork and validated it end to end.

## Summary

  • add skills.listing_budget_fraction in config.toml
  • keep the default behavior at 0.02
  • validate the setting as a fraction in the 0.0..=1.0 range
  • thread the configured value through session/context construction
  • update the warning text so it reflects the effective configured value instead of always saying 2%
  • update schema and tests accordingly

## Validation

  • cargo fmt --all
  • cargo test -p codex-core-skills
  • cargo test -p codex-core skills_listing_budget_fraction_is_loaded_from_config
  • cargo test -p codex-core build_initial_context_emits_thread_start_skill_warning_on_repeated_builds
  • cargo test -p codex-core config_schema_matches_fixture
  • cargo test -p codex-app-server config_read_preserves_skills_listing_budget_fraction_in_additional
  • cargo test -p codex-app-server turn_start_emits_thread_scoped_warning_notification_for_trimmed_skills
  • cargo test -p codex-tui live_app_server_warning_notification_renders_message

If the Codex team is open to an external PR for this, I can send the patch from my fork immediately.

1Const1 · 2 months ago
I implemented this in my fork and validated it end to end.

You can share with us first fork with branch

Somebody in OpenAI - we don't know when it can happens

nullbio · 1 month ago

Please fix.

1Const1 · 1 month ago

Claude code have setting about it in config

``skillListingBudgetFraction``

Why Codex still don't have it?

Radar-Lei · 22 days ago

please add this option to the settings

TheSingular · 17 days ago
I implemented this in my fork and validated it end to end. ..... If the Codex team is open to an external PR for this, I can send the patch from my fork immediately.

I'm not from the codex team, but please open the PR if you haven't already. That would be a great way to bring it to their attention.

gtcuco-personal · 3 days ago

Confirming this on macOS with Codex CLI 0.144.5 and a larger local/plugin skill catalog. The current session warns that skill descriptions were shortened to fit the fixed 2% budget, and there is no supported configuration key to raise it.

A user-configurable value such as skills.listing_budget_fraction = 0.03 would solve this cleanly while preserving the 2% default. The warning should report the effective configured value. In this case, moving from 2% to 3% would provide 50% more routing-metadata space without disabling useful skills or plugins.