Repository navigation
Open
Labels
configIssues involving config.toml, config keys, config merging, or config updatesIssues involving config.toml, config keys, config merging, or config updatesenhancementNew feature or requestNew feature or requestskillsIssues related to skillsIssues related to skills
Description
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.rsconst SKILL_METADATA_CONTEXT_WINDOW_PERCENT: usize = 2;default_skill_metadata_budget(...)computescontext_window * SKILL_METADATA_CONTEXT_WINDOW_PERCENT / 100.budget_warning_prefix(...)also hardcodes the user-facing warning text asExceeded 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_percentin 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.
Reacted by Batuhan Çimşit, Zishan Khan, informal-stripes-condo, Ondrej Merkun, vjain419, Alexander Riccio, Rodrigo Itao, Wenbing Li, 1Const1, Carine Bruyndoncx and 30 more
Metadata
Metadata
Assignees
Labels
configIssues involving config.toml, config keys, config merging, or config updatesIssues involving config.toml, config keys, config merging, or config updatesenhancementNew feature or requestNew feature or requestskillsIssues related to skillsIssues related to skills
Activity
github-actions commentedon Apr 26, 2026
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
tstager commentedon Apr 27, 2026
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 commentedon Apr 27, 2026
+1, I think there should be a config option for this
aldegad commentedon Apr 28, 2026
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 0.125.0-alpha.3In 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 execsmoke run. So configurability would help, but catalog-side description length also matters.Audit of only first-party plugin skill descriptions found:
I filed the plugin/catalog hygiene side separately here: #19957
I think these two fixes complement each other:
ariccio commentedon Apr 28, 2026
Yeah, wait, WTF, I need to optimize and heavily prune mine, I know, but why just truncate them!?
1Const1 commentedon May 1, 2026
agreed with that affected 125 version of cli. so it looks like downgrade abilities of codex
Need parameter for this in config
docs(codex): document 2% skills context budget warning
TheSingular commentedon May 7, 2026
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 commentedon May 11, 2026
+1
Cerebrovinny commentedon May 14, 2026
+1
em-winterschon commentedon May 19, 2026
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 commentedon May 21, 2026
I implemented this in my fork and validated it end to end.
Summary
skills.listing_budget_fractioninconfig.toml0.020.0..=1.0range2%Validation
cargo fmt --allcargo test -p codex-core-skillscargo test -p codex-core skills_listing_budget_fraction_is_loaded_from_configcargo test -p codex-core build_initial_context_emits_thread_start_skill_warning_on_repeated_buildscargo test -p codex-core config_schema_matches_fixturecargo test -p codex-app-server config_read_preserves_skills_listing_budget_fraction_in_additionalcargo test -p codex-app-server turn_start_emits_thread_scoped_warning_notification_for_trimmed_skillscargo test -p codex-tui live_app_server_warning_notification_renders_messageIf the Codex team is open to an external PR for this, I can send the patch from my fork immediately.
1Const1 commentedon May 21, 2026
You can share with us first fork with branch
Somebody in OpenAI - we don't know when it can happens
nullbio commentedon Jun 4, 2026
Please fix.
1Const1 commentedon Jun 9, 2026
Claude code have setting about it in config
skillListingBudgetFractionWhy Codex still don't have it?
Radar-Lei commentedon Jun 29, 2026
please add this option to the settings
TheSingular commentedon Jul 3, 2026
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 commentedon Jul 17, 2026
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.03would 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 commentedon Jul 21, 2026
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.6reported the same 2% warning, with 14 repo-localSKILL.mdfiles 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 commentedon Jul 21, 2026
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, 33SKILL.mdfiles in~/.codex/plugins/cache, 8 plugins explicitlyenabled = trueinconfig.toml.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-localSKILL.mdfiles: 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."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.mdin full before dismissing a skill).Skills from a plugin absent from config are still injected.
github@openai-curated-remotehas no entry in myconfig.toml— nor is that marketplace declared there — yetgithub:github,github:yeet,github:gh-fix-ciandgithub:gh-address-commentsappear in the injected Available Skills list. The filtering is also inconsistent: 20openai-templatesskills 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.
pacphi commentedon Sep 2, 2026
Additional evidence from an agentic-kit cross-host startup-context audit.
Environment:
0.152.1258,400tokens25,985tokens (10.06%of that effective window; this is total startup/request context and is not attributed solely to skills)The current warning is now a stronger failure mode than description shortening:
Agentic-kit reduced its own fully enabled managed guidance from 29,633 to 10,175 bytes for Claude, 4,537 to 1,684 bytes for Codex machine AGENTS.md, and 13,794 to 4,656 bytes for OpenCode. That does not solve the remaining Codex-owned catalogue omission: installed skills can become undiscoverable, and the model does not receive a useful machine-readable coverage state.
This supports the configurable budget requested here, plus two companion requirements:
Agentic-kit will keep its owned projections bounded and will not patch Codex skill enumeration or installed plugin caches. A released configurable/observable host contract is the removal proof for its upstream constraint.
yoavshmariahu commentedon Oct 20, 2026
The configurable budget (#38978) helps, but the default still scales with the context window and is uncapped when unset: 2% of 272k = ~5.4k tokens for gpt-6-astra, ~10k for gpt-6.1-sol, re-sent on every model call. Since #46070 there's also no warning when it's large.
Data point from a large repo (PostHog, 108 repo skills) on gpt-6-astra, 15 tasks that each depend on one specific skill. Replacing the listing with names + paths only:
For comparison, on the same repo Claude Code's skill listing is already compact (removing all 108 skills changes its first-turn input by ~850 tokens), and Cursor truncates each description to ~80 chars.
Suggestion: apply a fixed default cap (e.g. ~1–2k tokens) instead of scaling with the window, falling back to names + paths when the catalog doesn't fit.
Estimate Codex's skill-listing budget and flag skills OpenCode truncates