Skip to content

Add native /context usage breakdown for context window visibility #27898

Open
Open
Add native /context usage breakdown for context window visibility#27898
Labels
CLIIssues related to the Codex CLITUIIssues related to the terminal user interface: text input, menus and dialogs, and terminal displaycontextIssues related to context management (including compaction)enhancementNew feature or request

Description

@faj-design5260
faj-design5260
opened on Jun 12, 2026

What variant of Codex are you using?

CLI / TUI

What feature would you like to see?

I would like to propose a read-only /context command in the Codex TUI that shows a native-style context usage card.

The command would help users inspect how the current context window is being used during a session. In workflows that use MCP servers, tools, or skills, it is not always easy to tell how much of the available context window is being used by system prompt content, system tools, MCP tool schemas, skill-related context, regular messages, or remaining free space.

The proposed /context card would show the current context window composition across these categories:

  • System prompt
  • System tools
  • MCP tools
  • Skills
  • Messages
  • Free space

The command would support a compact default view through /context and a fuller breakdown through /context full.

The goal is to provide a lightweight inspection surface that helps users understand what is currently occupying the context window, without changing request construction, conversation history, model behavior, or provider-side usage accounting.

This proposal is not intended to change provider-side usage accounting, rate limit behavior, context compaction behavior, tool or skill injection policy, or request construction semantics. It is intended only as a native visibility and inspection feature.

A focused implementation can stay inside the native Codex codebase. It can include the core /context feature, native context usage bucket accounting, compact and full slash command routing, TUI rendering, and relevant in-repo tests or snapshots needed to keep the behavior stable.

The command should remain read-only. It should not mutate the live session, should not add messages to the conversation, and should not change the next request.

Additional information

I attached two screenshots below to show the proposed TUI shape:

Default compact /context view:

Image

Full /context view:

Image

For the initial upstream PR, I would keep the submitted changes focused on the native feature implementation and the relevant in-repo tests or snapshots.

During development, I also checked the accounting model against request-shaped context data to make sure the displayed buckets align with how the context is assembled. I do not think that external validation harness needs to be part of the clean feature PR by default.

If maintainers think additional validation details, test cases, or validation scripts would be useful or acceptable for upstream review, I would be happy to provide them or adapt the PR accordingly.

This proposal is related to context visibility and usage inspection discussions such as:

#26845
#27244
#24403

If this direction looks aligned with Codex’s roadmap, I would be happy to open a focused PR.

Activity

  1. faj-design5260
    added
    enhancementNew feature or request
    on Jun 12, 2026
  2. github-actions
    added
    CLIIssues related to the Codex CLI
    TUIIssues related to the terminal user interface: text input, menus and dialogs, and terminal display
    contextIssues related to context management (including compaction)
    on Jun 12, 2026

  3. github-actions commented on Jun 12, 2026

    @github-actions
    github-actionsbot
    on Jun 12, 2026 – with GitHub Actions
    Contributor

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

    Powered by Codex Action

  4. alainkaiser commented on Aug 11, 2026

    @alainkaiser
    alainkaiser
    on Aug 11, 2026

    I liked the request and idea and had the same for a while. So I decided to build it.
    I used your screenshots here as the starting point for a native, read-only /context command in the Codex TUI.

    Image

    /context shows how the latest model request uses the context window: system prompt, system tools, MCP schemas, skills, output schema, conversation, and free space.

    Image

    /context full adds details for individual system tools and MCP servers.

    Image

    This is more than a UI mockup. The implementation carries the accounting through the protocol, app server, core, and TUI, with tests across those layers. The branch is split into seven commits by responsibility.

    Working implementation: compare feat/context-breakdown with openai/main

    I’d love to get this upstream. If this direction fits the roadmap, I’m happy to adapt it to the preferred scope and open a focused PR if invited.

  5. iamenahs commented on Aug 26, 2026

    @iamenahs
    iamenahs
    on Aug 26, 2026

    Been digging around this code for an unrelated reason and hit something @alainkaiser's branch surfaces nicely.

    The card measures everything properly, but the status line percentage sitting next to it still divides by a constant. status/context.rs draws a "Status line" row off CONTEXT_WINDOW_BASELINE_TOKENS — still 12,000 — with the note "Status line excludes 12K from both usage and capacity", directly under a stack of rows that are all real measurements. percent_of_context_window_remaining itself is untouched, in both copies.

    That constant matters more than it looks:

    effective_window = context_window - BASELINE_TOKENS
used             = max(tokens_in_context_window - BASELINE_TOKENS, 0)
remaining%       = (effective_window - used) / effective_window

    The subtraction cancels in the numerator — it's just context_window - tokens_in_context_window — so the baseline only ever moves the denominator. It can't wash out. Whatever it's wrong by lands straight on the displayed number.

    And it's wrong in both directions. The repo's own test config is a reasonable reference point: token_count_includes_rate_limits_snapshot sends 8 tools, and pricing that request's fixed parts with approx_token_count comes to 7,015 — 5,337 of base instructions, 1,678 of tool schemas. So a plain session is being told it has more room than it has. Load up MCP servers and skills, cross 12,000, and it starts under-reporting instead. There's no setup where the constant is right except by luck.

    Your card already computes every number needed to replace it, which is why I'm raising it here rather than in isolation — looks like a few lines once the breakdown exists.

    Couple of things that bit me when I tried it.

    The tool payload has two wire sizes. build_responses_request collapses every spec into a single namespace object when use_responses_lite && namespace_tools, and sends them one by one otherwise, so you have to price whichever branch the request is actually going to take.

    Also worth resisting the urge to fix estimate_token_count_with_base_instructions while you're in there. It omits tool schemas, which looks like the same bug, but it feeds recompute_token_usage → get_total_token_usage → token_limit_reached. Touch it and you've moved when Codex compacts. Leaving it alone is the entire reason this can stay a display change.

    One more that only shows up once the baseline is per-request: it has to belong to the request whose usage you're showing. Local compaction builds a Prompt with no tools and no output schema but still reports provider usage, so carrying the previous turn's baseline onto that event subtracts a fixed cost that request never paid. Shows up as free space jumping right after a compact.

    Separately, while someone's in this file: the comment on the constant says "Includes prompts, tools and space to call compact." The compact half isn't true — context_window.rs reserves its own headroom off auto_compact_token_limit() plus fallback_buffer_tokens, and never reads BASELINE_TOKENS.

    I have a branch doing just the denominator, floored at 12,000 so nothing moves for anyone below it: iamenahs#1. It doesn't overlap what you've built — lift any of it if it's useful. Filed the percentage on its own as #40756 too, since it hits people who never open /context.

  6. axisrow commented on Oct 9, 2026

    @axisrow
    axisrow
    on Oct 9, 2026

    +1 I also want

  7. axisrow commented on Oct 9, 2026

    @axisrow
    axisrow
    on Oct 9, 2026

    I liked the request and idea and had the same for a while. So I decided to build it.
    I used your screenshots here as the starting point for a native, read-only /context command in the Codex TUI.

    Image

    /context shows how the latest model request uses the context window: system prompt, system tools, MCP schemas, skills, output schema, conversation, and free space.

    Image

    /context full adds details for individual system tools and MCP servers.

    Image

    This is more than a UI mockup. The implementation carries the accounting through the protocol, app server, core, and TUI, with tests across those layers. The branch is split into seven commits by responsibility.

    Working implementation: compare feat/context-breakdown with openai/main

    I’d love to get this upstream. If this direction fits the roadmap, I’m happy to adapt it to the preferred scope and open a focused PR if invited.

    Open PR! Don't Wait!

  8. raviknits commented on Oct 11, 2026

    @raviknits
    raviknits
    on Oct 11, 2026

    A data point for the categories: in my own Codex sessions, command output was about 30% of what was sent and file contents about 28%, so those two might deserve their own rows in the card next to the system prompt and MCP schemas.

    I measured it with a small offline script over ~/.codex/sessions, if anyone wants to compare their own:

    curl -fsSL https://densilo.com/tokens.py | python3 -

    (I build Densilo, which is where the script is from.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    CLIIssues related to the Codex CLITUIIssues related to the terminal user interface: text input, menus and dialogs, and terminal displaycontextIssues related to context management (including compaction)enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions