Docs: rollout_budget documents stale reminder_interval_tokens key

Open
#36,705 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
58/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Quiet
Tech stack
rust
Domain
cli, documentation

Research direction

Start with the published configuration reference and compare its rollout_budget entry with codex-rs/core/config.schema.json and the rust-v0.144.1/current main definitions. Update the reference and sample to use reminder_at_remaining_tokens with an integer array, document the threshold constraints, and remove the obsolete default claim. Done means the published configuration matches the current schema and parses successfully.

Written by the indexing model from the issue text.

Description

CLI config documentation windows-os

Summary

The published Codex configuration reference documents the stale
features.rollout_budget.reminder_interval_tokens key, but Codex CLI expects
features.rollout_budget.reminder_at_remaining_tokens as an array of explicit
remaining-token thresholds.

Documentation:
https://learn.chatgpt.com/docs/config-file/config-reference#configtoml

This makes the documented TOML fail to parse and prevents users from enabling
the under-development rollout_budget feature from the published reference.

Environment

  • Codex CLI: 0.144.1
  • OS: Windows
  • The same reminder_at_remaining_tokens field is present in the
    rust-v0.144.1 tag and current main.

Reproduction

Using the key currently listed in the configuration reference:

[features.rollout_budget]
enabled = true
limit_tokens = 100000
reminder_interval_tokens = 10000

Equivalent one-off CLI reproduction:

codex -c 'features.rollout_budget.enabled=true' \
  -c 'features.rollout_budget.limit_tokens=100000' \
  -c 'features.rollout_budget.reminder_interval_tokens=10000' \
  features list

Observed result:

Error: data did not match any variant of untagged enum FeatureToml
in `features.rollout_budget`

Implemented configuration

The CLI accepts the following configuration instead:

[features.rollout_budget]
enabled = true
limit_tokens = 100000
reminder_at_remaining_tokens = [50000, 25000, 10000]
sampling_token_weight = 1.0
prefill_token_weight = 1.0

With the equivalent one-off overrides, codex features list exits successfully
and reports:

rollout_budget  under development  true

Root cause

PR #29423 intentionally replaced the interval configuration with explicit
remaining-token reminder thresholds:

https://github.com/openai/codex/pull/29423

The implementation and generated schema now use:

pub reminder_at_remaining_tokens: Option<Vec<i64>>,

The published configuration reference still lists:

  • features.rollout_budget.reminder_interval_tokens
  • type: integer
  • a claimed default of 10% of limit_tokens

Those statements describe the pre-#29423 implementation.

Suggested documentation fix

  1. Replace features.rollout_budget.reminder_interval_tokens with
    features.rollout_budget.reminder_at_remaining_tokens.
  2. Change the documented type from integer to array<integer>.
  3. Explain that every threshold must be positive and below limit_tokens.
  4. Remove the old claim that the interval defaults to 10% of limit_tokens;
    the current implementation requires the threshold array when the feature is
    enabled.
  5. Update the sample configuration to use an explicit array such as
    [50000, 25000, 10000].
  6. If practical, validate published config keys against
    codex-rs/core/config.schema.json to catch future drift.

Contribution offer

I have read docs/contributing.md and understand that external pull requests
are accepted by invitation only. If a Codex team member invites me to
contribute this fix, I would be happy to submit a focused documentation PR with
the updated reference/sample and any requested validation coverage.

Dominant language
Rust
Stars
125k
Forks
19.5k
Avg merge
1m
Merged PRs (30d)
1k

Contributor guide

Open the contributing guide

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.

More from openai/codex

All issues in openai/codex

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.