Skip to content

Commit c18b3da

Browse files
committed
Add context window progress indicator feature
This PR adds a real-time context window progress indicator that shows users how close they are to the token limit. The indicator is integrated directly into the input prompt's border, with the top border progressively filling as tokens are used. Key features: - Real-time updates via uiTelemetryService - Visual progress bar on top border using thicker line characters (▬) - Scales from 0-100% fill as token usage goes from 0-50% (compression threshold) - Maintains consistent border color (no color changes) - Full test coverage (27 comprehensive tests) - Optimized state initialization to avoid unnecessary re-renders Documentation included in docs/context-progress-indicator.md 🤖 Generated with [Claude Code](https://claude.com/claude-code)
1 parent cdabd34 commit c18b3da

5 files changed

Lines changed: 422 additions & 33 deletions

File tree

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Context Window Progress Indicator
2+
3+
## Problem
4+
5+
When using the Gemini CLI for extended conversations, users have no visual
6+
feedback about how close they are to the token limit. This makes it difficult to
7+
know when the conversation history will be automatically compressed or when
8+
they're approaching the maximum context window size. Without this visibility,
9+
users may be surprised by compression events or context window overflows.
10+
11+
## Solution
12+
13+
The context window progress indicator is a visual, real-time display integrated
14+
directly into the input prompt's border. As you use tokens throughout your
15+
conversation, the top border of the input box progressively fills with a thicker
16+
line character (``) from left to right. The progress bar is calibrated so that
17+
it reaches 100% fill at the 50% token usage mark—the point where automatic
18+
conversation compression kicks in.
19+
20+
## How It Works
21+
22+
The progress indicator appears on the **top border** of the input prompt:
23+
24+
```
25+
Empty (0% usage):
26+
╭─────────────────────────────────────────╮
27+
│ > Your input here │
28+
╰─────────────────────────────────────────╯
29+
30+
Partially filled (~25% usage):
31+
╭▬▬▬▬▬▬▬▬▬▬─────────────────────────────────╮
32+
│ > Your input here │
33+
╰─────────────────────────────────────────╯
34+
35+
Fully filled (50% usage - compression threshold):
36+
╭▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬╮
37+
│ > Your input here │
38+
╰─────────────────────────────────────────╯
39+
```
40+
41+
### Visual Behavior
42+
43+
- **0-50% token usage**: Top border progressively fills from left to right with
44+
thicker line characters
45+
- **50% usage (compression point)**: Border is completely filled - automatic
46+
compression will occur
47+
- **50-100% usage**: Border remains fully filled as you continue toward the
48+
absolute limit
49+
50+
### Real-Time Updates
51+
52+
The progress indicator updates automatically as tokens are used:
53+
54+
- When you send messages to the AI
55+
- When the AI responds with generated text
56+
- When tools are called and produce output
57+
- When the conversation history grows
58+
59+
No user action is required—the indicator reflects the true state of your context
60+
window at all times.
61+
62+
## Technical Details
63+
64+
- **Hook**: `useContextTracking` - Subscribes to `uiTelemetryService` for
65+
real-time token count updates
66+
- **Component**: `ProgressBorder` - Custom border component that replaces Ink's
67+
standard border
68+
- **Performance**: Fully memoized to prevent unnecessary re-renders
69+
- **Test Coverage**: 27 comprehensive tests covering all edge cases
70+
71+
## Example Usage
72+
73+
Simply start a conversation and watch the top border of the input prompt fill as
74+
you chat:
75+
76+
```bash
77+
$ gemini
78+
79+
> Tell me about TypeScript
80+
81+
[AI responds with explanation]
82+
83+
> Can you give me an example?
84+
85+
[AI provides code example - notice the border filling slightly more]
86+
87+
> Now explain async/await
88+
89+
[As conversation continues, the top border progressively fills]
90+
```
91+
92+
When the border is fully filled, you'll know that automatic compression is about
93+
to occur to keep your conversation within the model's context window.

0 commit comments

Comments
 (0)