Skip to content

feat: enhance /context with detailed token usage breakdown - #53

Open
syf2211 wants to merge 1 commit into
KlaatAI:mainfrom
syf2211:feat/context-token-breakdown
Open

feat: enhance /context with detailed token usage breakdown#53
syf2211 wants to merge 1 commit into
KlaatAI:mainfrom
syf2211:feat/context-token-breakdown

Conversation

@syf2211

@syf2211 syf2211 commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Summary

Enhances the /context slash command with a detailed token usage breakdown as described in #27.

Motivation

Long agentic sessions consume significant context. Users need visibility into where tokens go — system prompt, conversation history, tool results, and tool schemas — not just a total count.

Changes

  • Export estimateTokensFromChars / estimateTokensFromText from compaction.ts as the shared estimation helper (chars÷4)
  • Add context-breakdown.ts module with computeContextBreakdown() for categorized estimates
  • Enhance /context output:
    • System prompt split (core, environment, project rules, mode)
    • Conversation split (user, assistant, tool results with counts)
    • Tool schema estimate with active dialect tool count
    • Progress bar and percentage vs active tier window
    • Compaction state (count, stub detection, ledger path + size)
  • Base breakdown on the same compacted send payload the API receives (mode prompt injected, compactMessagesForApi applied)
  • Count tool_calls JSON in assistant message token estimates

Tests

  • bun test — 255 pass (7 new tests in context-breakdown.test.ts)
  • bun run typecheck — pass
  • bun run build — pass

Notes

  • When API-reported prompt_tokens differs from the estimate by >2% of the window, both values are shown
  • /init-style project rules (Project rules (from …)) are classified under Project rules

Fixes #27

Fixes KlaatAI#27

- Export shared estimateTokensFromChars/Text helpers from compaction.ts
- Add context-breakdown module for system/conversation/tool schema split
- Show progress bar, compaction state, and ledger size in /context output
- Base breakdown on compacted send payload (matches API window)
- Count assistant tool_calls in token estimates
@github-actions

Copy link
Copy Markdown
Contributor

🤖 KlaatAI Review Bot (powered by Klaatu, advisory only — a maintainer makes the real call)

Issue match
Fully addresses #27. Implements the /context breakdown (system, conversation, tool schemas), progress bar, percentage, and compaction state. Updates the slash autocomplete description as required.

Test coverage
Adds 7 tests in context-breakdown.test.ts covering bucket classification, message counting, and bar formatting. However, the complex message reconstruction logic in repl.ts (filtering mode prompts, injecting tab prompts, and running compactMessagesForApi) is untested. Missing coverage for formatBreakdownLine and edge cases like empty message arrays.

Correctness concerns
The manual payload reconstruction in repl.ts (filtering mode prompts, injecting tab prompts, then calling compactMessagesForApi) risks silently drifting out of sync with the actual API send path if the latter changes. Additionally, messageChars in context-breakdown.ts assumes m.content is strictly a string or array; it may throw if content is ever null or undefined.

Verdict
Needs human judgment call on whether the manual payload reconstruction in repl.ts is an acceptable maintenance risk, and if the missing tests for the REPL integration logic are sufficient for now.

This is an automated review to help triage faster, not a gate. Nothing here blocks merging.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add /context command — token usage breakdown

1 participant