›_ Codex Issues
Codex Issues / #19679

Make skills metadata context budget configurable instead of hardcoded 2%

Open 💬 19 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 ↗

19 Comments

github-actions[bot] contributor · 4 months ago

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

  • #19090

Powered by Codex Action

tstager · 4 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 · 4 months ago

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

aldegad · 4 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 · 4 months ago

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

1Const1 · 3 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 · 3 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 · 3 months ago

+1

Cerebrovinny · 3 months ago

+1

em-winterschon · 3 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 · 3 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 · 3 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 · 2 months ago

Please fix.

1Const1 · 2 months ago

Claude code have setting about it in config

``skillListingBudgetFraction``

Why Codex still don't have it?

Radar-Lei · 2 months ago

please add this option to the settings

TheSingular · 1 month 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 · 1 month 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.

Yan-Yang-PYZNTech · 1 month ago

Related but distinct control-surface issue: #21425 tracks separating installed plugin availability from default per-session skill injection.

A current macOS reproduction on Codex CLI 0.144.6 reported the same 2% warning, with 14 repo-local SKILL.md files versus 83 in the installed plugin cache. It also found skills associated with a plugin configured as disabled still present in the injected Available Skills list.

Making the budget configurable here would reduce truncation. It would not, by itself, let users keep plugins installed without injecting their skill metadata into every default session, so the two changes are complementary.

gtcuco-personal · 1 month ago

Fuller reproduction on macOS, Codex CLI 0.144.5, supporting both this issue and the coupling described in #21425.

Setup: 56 user skills in ~/.codex/skills, 33 SKILL.md files in ~/.codex/plugins/cache, 8 plugins explicitly enabled = true in config.toml.

  1. The budget warning is cwd-dependent. Running from $HOME (no repo-local skills): 66 skills injected, no warning. Running from a repo containing 52 repo-local SKILL.md files: 63 skills injected and the CLI prints "warning: Skill descriptions were shortened to fit the 2% skills context budget. Codex can still see every skill, but some descriptions are shorter."
  1. The model is never told its descriptions were shortened. The warning is CLI-side only. Asked to transcribe any truncation notice present in its own prompt, the truncated session replied there is none — the degradation is silent on the model side, so it cannot compensate (e.g. by reading a SKILL.md in full before dismissing a skill).
  1. Skills from a plugin absent from config are still injected. github@openai-curated-remote has no entry in my config.toml — nor is that marketplace declared there — yet github:github, github:yeet, github:gh-fix-ci and github:gh-address-comments appear in the injected Available Skills list. The filtering is also inconsistent: 20 openai-templates skills from the same cache directory are not injected.

This supports treating the two fixes as complementary: a configurable budget (this issue) raises the ceiling; decoupling the installed-plugin cache from per-session injection (#21425) stops unrequested skills from spending it.