#20861: feat(context): add conversation transcript stats to /context command
agents
size: L
trusted-contributor
Cluster:
Context Management Enhancements
## Summary
- Parse session JSONL transcript to show post-compaction message count, per-role char breakdown, and combined context window estimate
- Adds conversation stats to `/context list`, `/context detail`, and `/context json` views
- Combined estimate line shows `system + tools + conversation` vs context window with usage percentage
## Details
The `/context` command previously showed system prompt, tools, skills, and workspace files — but had no visibility into the actual conversation messages consuming the context window. This adds a `readConversationStats()` function that:
- Reads the raw session JSONL file (no SessionManager overhead)
- Resets accumulators on `type: "compaction"` entries so only post-compaction messages are counted
- Tracks per-role (user, assistant, toolResult) message count and char totals
- Uses chars/4 token estimation (matching the pruner's `CHARS_PER_TOKEN_ESTIMATE`)
### Example output (`/context list`)
```
Conversation (post-compaction): 47 messages, 128,340 chars (~32,085 tok)
Compactions: 2
Context estimate: ~45,200 tok (system ~8,100 + tools ~5,015 + conversation ~32,085) / window=200,000 (23%)
Session tokens (cached): 51,234 total / ctx=200000
```
### Changes
Single file: `src/auto-reply/reply/commands-context-report.ts`
- `ConversationStats` / `ConversationRoleStats` types
- `getEntryContentChars()` — extract char count from message content (handles string, array blocks with text/thinking/tool_use)
- `readConversationStats()` — parse JSONL, reset on compaction boundaries, aggregate per-role
- Wired into `buildContextReply()` for list, detail, and json sub-commands
## Test plan
- [ ] `/context list` — verify conversation line and combined estimate appear
- [ ] `/context detail` — verify per-role breakdown appears sorted by chars descending
- [ ] `/context json` — verify `conversation` object present in output
- [ ] Fresh session (no transcript) — verify "unavailable" fallback
- [ ] After compaction — verify only post-compaction messages are counted
- [ ] `pnpm tsgo` passes (no new type errors)
---
_Re-opened from #19600 (auto-closed during fork maintenance)._
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR adds conversation transcript statistics to the `/context` command, providing visibility into post-compaction message counts and context window usage. The implementation parses the session JSONL file directly to extract per-role statistics (message count, char totals) while resetting accumulators on compaction boundaries. The stats are integrated into `/context list`, `/context detail`, and `/context json` views with a combined context estimate showing system + tools + conversation vs window size.
Key changes:
- Added `readConversationStats()` function that parses JSONL transcripts and tracks post-compaction messages only
- New `getEntryContentChars()` helper extracts character counts from message content (handles string, array blocks with text/thinking/tool_use)
- Uses chars/4 token estimation matching the pruner's `CHARS_PER_TOKEN_ESTIMATE` constant
- Graceful fallback when transcript is unavailable
- Combined estimate line shows comprehensive context breakdown with usage percentage
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- The implementation is clean, well-contained, and uses appropriate defensive patterns throughout. The function correctly handles missing sessions, malformed JSONL lines, and missing content fields with try-catch blocks and empty fallbacks. The token estimation aligns with existing codebase constants, and the `resolveSessionFilePathOptions` helper is used correctly for path resolution. All error conditions return safe empty states.
- No files require special attention
<sub>Last reviewed commit: 2e264bb</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#16916: feat(status): expose context overhead breakdown in --deep mode
by soumikbhatta · 2026-02-15
75.7%
#19923: feat: track held messages during compaction gate and split verifica...
by PrivacySmurf · 2026-02-18
75.6%
#18997: fix: improve context overflow error messages and docs
by realhoratiobot · 2026-02-17
74.7%
#22387: fix: session_status context tracking undercount for cached providers
by 1ucian · 2026-02-21
73.7%
#7975: feat(commands): add /reset-context command
by sergi039 · 2026-02-03
73.5%
#15126: fix(status): avoid false 100% context usage when totals mirror context
by AlexAnys · 2026-02-13
73.1%
#8961: feat: smarter compaction tool truncation + token count in system pr...
by SocialNerd42069 · 2026-02-04
72.4%
#15749: fix: improve context overflow error with diagnostic details
by superlowburn · 2026-02-13
72.4%
#12966: feat(logging): Add session context and breadcrumbs to error logs
by trevorgordon981 · 2026-02-10
72.4%
#10915: fix: prevent session bloat from oversized tool results and improve ...
by DukeDeSouth · 2026-02-07
72.0%