feat: show number of tokens remaining in UI (#1388)

When using the OpenAI Responses API, we now record the `usage` field for
a `"response.completed"` event, which includes metrics about the number
of tokens consumed. We also introduce `openai_model_info.rs`, which
includes current data about the most common OpenAI models available via
the API (specifically `context_window` and `max_output_tokens`). If
Codex does not recognize the model, you can set `model_context_window`
and `model_max_output_tokens` explicitly in `config.toml`.

When then introduce a new event type to `protocol.rs`, `TokenCount`,
which includes the `TokenUsage` for the most recent turn.

Finally, we update the TUI to record the running sum of tokens used so
the percentage of available context window remaining can be reported via
the placeholder text for the composer:

![Screenshot 2025-06-25 at 11 20
55 PM](https://github.com/user-attachments/assets/6fd6982f-7247-4f14-84b2-2e600cb1fd49)

We could certainly get much fancier with this (such as reporting the
estimated cost of the conversation), but for now, we are just trying to
achieve feature parity with the TypeScript CLI.

Though arguably this improves upon the TypeScript CLI, as the TypeScript
CLI uses heuristics to estimate the number of tokens used rather than
using the `usage` information directly:


296996d74e/codex-cli/src/utils/approximate-tokens-used.ts (L3-L16)

Fixes https://github.com/openai/codex/issues/1242

codex-rs/tui/src/bottom_pane/chat_composer.rs

@@ -1,3 +1,4 @@
+use codex_core::protocol::TokenUsage;
 use crossterm::event::KeyEvent;
 use ratatui::buffer::Buffer;
 use ratatui::layout::Alignment;
@@ -24,6 +25,8 @@ const MIN_TEXTAREA_ROWS: usize = 1;
 /// Rows consumed by the border.
 const BORDER_LINES: u16 = 2;
 
+const BASE_PLACEHOLDER_TEXT: &str = "send a message";
+
 /// Result returned when the user interacts with the text area.
 pub enum InputResult {
     Submitted(String),
@@ -40,7 +43,7 @@ pub(crate) struct ChatComposer<'a> {
 impl ChatComposer<'_> {
     pub fn new(has_input_focus: bool, app_event_tx: AppEventSender) -> Self {
         let mut textarea = TextArea::default();
-        textarea.set_placeholder_text("send a message");
+        textarea.set_placeholder_text(BASE_PLACEHOLDER_TEXT);
         textarea.set_cursor_line_style(ratatui::style::Style::default());
 
         let mut this = Self {
@@ -53,6 +56,41 @@ impl ChatComposer<'_> {
         this
     }
 
+    /// Update the cached *context-left* percentage and refresh the placeholder
+    /// text. The UI relies on the placeholder to convey the remaining
+    /// context when the composer is empty.
+    pub(crate) fn set_token_usage(
+        &mut self,
+        token_usage: TokenUsage,
+        model_context_window: Option<u64>,
+    ) {
+        let placeholder = match (token_usage.total_tokens, model_context_window) {
+            (total_tokens, Some(context_window)) => {
+                let percent_remaining: u8 = if context_window > 0 {
+                    // Calculate the percentage of context left.
+                    let percent = 100.0 - (total_tokens as f32 / context_window as f32 * 100.0);
+                    percent.clamp(0.0, 100.0) as u8
+                } else {
+                    // If we don't have a context window, we cannot compute the
+                    // percentage.
+                    100
+                };
+                if percent_remaining > 25 {
+                    format!("{BASE_PLACEHOLDER_TEXT} — {percent_remaining}% context left")
+                } else {
+                    format!(
+                        "{BASE_PLACEHOLDER_TEXT} — {percent_remaining}% context left (consider /compact)"
+                    )
+                }
+            }
+            (total_tokens, None) => {
+                format!("{BASE_PLACEHOLDER_TEXT} — {total_tokens} tokens used")
+            }
+        };
+
+        self.textarea.set_placeholder_text(placeholder);
+    }
+
     /// Record the history metadata advertised by `SessionConfiguredEvent` so
     /// that the composer can navigate cross-session history.
     pub(crate) fn set_history_metadata(&mut self, log_id: u64, entry_count: usize) {

codex-rs/tui/src/bottom_pane/mod.rs

@@ -2,6 +2,7 @@
 
 use bottom_pane_view::BottomPaneView;
 use bottom_pane_view::ConditionalUpdate;
+use codex_core::protocol::TokenUsage;
 use crossterm::event::KeyEvent;
 use ratatui::buffer::Buffer;
 use ratatui::layout::Rect;
@@ -129,6 +130,18 @@ impl BottomPane<'_> {
         }
     }
 
+    /// Update the *context-window remaining* indicator in the composer. This
+    /// is forwarded directly to the underlying `ChatComposer`.
+    pub(crate) fn set_token_usage(
+        &mut self,
+        token_usage: TokenUsage,
+        model_context_window: Option<u64>,
+    ) {
+        self.composer
+            .set_token_usage(token_usage, model_context_window);
+        self.request_redraw();
+    }
+
     /// Called when the agent requests user approval.
     pub fn push_approval_request(&mut self, request: ApprovalRequest) {
         let request = if let Some(view) = self.active_view.as_mut() {

codex-rs/tui/src/chatwidget.rs

@@ -18,6 +18,7 @@ use codex_core::protocol::McpToolCallEndEvent;
 use codex_core::protocol::Op;
 use codex_core::protocol::PatchApplyBeginEvent;
 use codex_core::protocol::TaskCompleteEvent;
+use codex_core::protocol::TokenUsage;
 use crossterm::event::KeyEvent;
 use ratatui::buffer::Buffer;
 use ratatui::layout::Constraint;
@@ -46,6 +47,7 @@ pub(crate) struct ChatWidget<'a> {
     input_focus: InputFocus,
     config: Config,
     initial_user_message: Option<UserMessage>,
+    token_usage: TokenUsage,
 }
 
 #[derive(Clone, Copy, Eq, PartialEq)]
@@ -131,6 +133,7 @@ impl ChatWidget<'_> {
                 initial_prompt.unwrap_or_default(),
                 initial_images,
             ),
+            token_usage: TokenUsage::default(),
         }
     }
 
@@ -250,6 +253,11 @@ impl ChatWidget<'_> {
                 self.bottom_pane.set_task_running(false);
                 self.request_redraw();
             }
+            EventMsg::TokenCount(token_usage) => {
+                self.token_usage = add_token_usage(&self.token_usage, &token_usage);
+                self.bottom_pane
+                    .set_token_usage(self.token_usage.clone(), self.config.model_context_window);
+            }
             EventMsg::Error(ErrorEvent { message }) => {
                 self.conversation_history.add_error(message);
                 self.bottom_pane.set_task_running(false);
@@ -410,3 +418,31 @@ impl WidgetRef for &ChatWidget<'_> {
         (&self.bottom_pane).render(chunks[1], buf);
     }
 }
+
+fn add_token_usage(current_usage: &TokenUsage, new_usage: &TokenUsage) -> TokenUsage {
+    let cached_input_tokens = match (
+        current_usage.cached_input_tokens,
+        new_usage.cached_input_tokens,
+    ) {
+        (Some(current), Some(new)) => Some(current + new),
+        (Some(current), None) => Some(current),
+        (None, Some(new)) => Some(new),
+        (None, None) => None,
+    };
+    let reasoning_output_tokens = match (
+        current_usage.reasoning_output_tokens,
+        new_usage.reasoning_output_tokens,
+    ) {
+        (Some(current), Some(new)) => Some(current + new),
+        (Some(current), None) => Some(current),
+        (None, Some(new)) => Some(new),
+        (None, None) => None,
+    };
+    TokenUsage {
+        input_tokens: current_usage.input_tokens + new_usage.input_tokens,
+        cached_input_tokens,
+        output_tokens: current_usage.output_tokens + new_usage.output_tokens,
+        reasoning_output_tokens,
+        total_tokens: current_usage.total_tokens + new_usage.total_tokens,
+    }
+}